Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

EclipseLink/FAQ/JPA

< EclipseLink‎ | FAQ
Revision as of 10:28, 19 May 2011 by James.sutherland.oracle.com (Talk | contribs) (What databases are supported?)

What is Object-Relational Mapping

Object-relational mapping or ORM is the category of products that provide services to map objects to relational databases. The Java Persistence API (JPA) is the Java specification that provides a standard to ORM in Java. JPA provides both a standard mapping definition (through annotations or XML) and a standard runtime API and object-level query language (JPQL). JPA is part of the EJB specification and JEE platform, but can also be used in JSE.

EclipseLink provides sophisticated and high performance object-relational mapping services and complete support for the JPA specification. JPA objects are mapped through the package javax.persistence annotations and JPA persistence.xml and orm.xml. EclipseLink also provides extended annotations through the package org.eclipse.persistence.annotations. JPA provides a runtime API through the EntityManager class in the javax.persistence package. EclipseLink also provides extended runtime API through the package org.eclipse.persistence.jpa.

EclipseLink also provides a POJO ORM API and mapping model which its JPA support is based on. The mapping model classes are in the org.eclipse.persistence.descriptors and org.eclipse.persistence.mappings packages, and sessions.xml and project.xml files. The runtime API is provided through the Session and UnitOfWork classes in the org.eclipse.persistence.sessions package.

What are the Best Practices for using EclipseLink JPA?

See EclipseLink JPA Best Practices.

Migrating to EclipseLink JPA

How do I migrate from using Oracle TopLink to EclipseLink?

See Oracle TopLink

How do I migrate from using TopLink Essentials to EclipseLink?

See TopLink Essentials

How do I migrate from another JPA provider to EclipseLink?

See JPA Migration

What databases are supported?

EclipseLink supports any relational database that is compliant with SQL and has a compliant JDBC driver. EclipseLink has extended support for several database platforms. The extended support mainly consists of providing native sequencing support, schema creation, and certain database functions. These platform classes can be found in the org.eclipse.persistence.platform.database and org.eclipse.persistence.platform.database.oracle packages.

These include:

  • Oracle
  • Oracle JDBC (8, 9, 10, 11)
  • MySQL
  • PostgreSQL
  • Derby
  • DB2
  • DB2 (mainframe)
  • Microsoft SQL Server
  • Sybase
  • Informix
  • SQL Anywhere
  • HSQL
  • H2
  • Firebird
  • Microsoft Access
  • Attunity
  • Cloudscape
  • DBase
  • PointBase
  • TimesTen
  • Symfoware
  • MaxDB

It also possible to extend EclipseLink to add extended support for additional platforms. There are also several user contributed platforms in the EclipseLink incubator project, see Platform Incubator.

EclipseLink has extended support for Oracle JDBC drivers. Including:

  • LOB's
  • NChar's
  • XMLType's
  • TIMESTAMP (TZ, LTZ)'s
  • Native batch writing
  • Structured object-relational data-types
  • PLSQL data-types and stored procedures
  • VPD, RAC, proxy authentication
  • XDK XML parser

EclipseLink also has support for structure object-relational data-types and databases, and Enterprise Information Systems (EIS, legacy datasources and messaging platforms).

How is EclipseLink integrated with the Oracle database?

EclipseLink is completely independent from, but also tightly integrated with the Oracle database. EclipseLink has extended support for most Oracle SQL, JDBC and database extensions.

EclipseLink's extended support for the Oracle database includes:

  • LOB's
  • NChar's
  • XMLType's
  • TIMESTAMP (TZ, LTZ)'s
  • Native batch writing
  • Structured object-relational data-types
  • PLSQL data-types and stored procedures
  • VPD, RAC, proxy authentication
  • XDK XML parser
  • Hierarchical selects (Select by prior)
  • Returning clause
  • Flashback history and queries
  • Stored procedures, output parameters and output cursors
  • Stored functions
  • Oracle AQ

How to access table, column and schema information at runtime?

EclipseLink stores the mapping metadata from the JPA annotations and orm.xml in its ClassDescriptor and DatabaseMapping objects. These objects can be accessed at runtime from the EntityManager or EntityManagerFactory by casting or unwrapping to the EclipseLink JPA interface.

EntityManager em = getEntityManager();
String table = em.unwrap(JpaEntityManager.class).getServerSession().getDescriptor(MyClass.class).getTables().get(0).getName();
String schema = em.unwrap(JpaEntityManager.class).getServerSession().getDescriptor(MyClass.class).getTables().get(0).getTableQualifier();
String column = em.unwrap(JpaEntityManager.class).getServerSession().getDescriptor(MyClass.class).getMappingForAttributeName("myAttribute").getField().getName();

If you use JPA annotations, you may also be able to access specified schema information using Java reflection to access your annotation objects.

The JPA 2.0 metamodel can also be used to provide information on how the attributes are mapped (but not their database schema information).

You can also use native SQL queries to query your database catalogs for schema information, or use the JDBC connection metadata APIs. EclipseLink also exposes the JDBC catalog APIs through its SchemaManager class.

How to access the JDBC connection?

Sometimes when using JPA it may be required to have lower level access to your database through JDBC. If you are using a JEE DataSource, you can just access the same DataSource that JPA uses, if it is a JTA DataSource it will be in the same transaction context as JPA.

If you are not using a DataSource, or want the same connection in the same transaction as JPA, you can obtain the JDBC Connection from the EntityManager.

See, Getting a JDBC Connection from an EntityManager

How to disable or enable weaving?

In a Java SE environment weaving is not enabled by default. This can affect LAZY OneToOne, ManyToOne and Basic relationships. It also has a major effect on performance and disable attribute change tracking.

To enable weaving in Java SE, the EclipseLink agent must be used when starting the Java VM.

 java -javaagent:eclipselink.jar

Spring could also be used to allow JPA weaving in Java SE.

Static weaving can also be used to weave your jar.

See, How to Configure Static Weaving

In a Java EE environment weaving is enabled by default (on any JEE EJB 3.0 fully compliant app server, Weblogic, Webspehere, Glassfish. JBoss does not allow weaving so you must use static weaving or Spring).

To disable weaving the weaving persistence unit property can be used,

 <property name="eclipselink.weaving" value="false">

For more information on weaving see the EclipseLink UserGuide, Using EclipseLink JPA Weaving

Are stored procedures and triggers supported?

EclipseLink has extended support for stored procedures and triggers.

Stored procedures are support through the @NamedStoredProcedureQuery, StoredProcedureCall, StoredFunctionCall and PLSQLStoredProcedureCall classes.

The following stored procedures features are supported:

  • IN parameters
  • OUT parameter
  • INOUT parameters
  • result sets
  • CURSOR OUT parameters
  • Object-relational datatypes (Struct, Array)
  • Oracle PLSQL types such as TABLE, RECORD, BOOLEAN
  • Using a stored procedure in a named query
  • Using a stored procedure in a dynamic query
  • Using a stored procedure to override an Entity's persist, update, remove or find query.
  • Using a stored procedure to override a mapping's select, insert or delete query.
  • Stored functions
  • Oracle, SQL Server, MySQL, Sybase, DB2, other stored procedure capable platforms


Triggers can be used in the tables being processed by EclipseLink.

If a trigger is updating data required back in the application, or the id, the @ReturnInsert, @ReturnUpdate or ReturningPolicy can be used the return the values updated by the trigger.

How to get the SQL for a Query?

To see the SQL for a JPA Query you can enable logging on FINE or lower.

To get the SQL for a specific Query at runtime you can use the DatabaseQuery API.

Session session = em.unwrap(JpaEntityManager).getActiveSession();
DatabaseQuery databaseQuery = ((EJBQueryImpl)query).getDatabaseQuery();
databaseQuery.prepareCall(session, new DatabaseRecord());
String sqlString = databaseQuery.getSQLString();

This SQL will contain ? for parameters. To get the SQL translated with the arguments you need a DatabaseRecord with the parameter values.

Session session = em.unwrap(JpaEntityManager).getActiveSession();
DatabaseQuery databaseQuery = ((EJBQueryImpl)query).getDatabaseQuery();
String sqlString = databaseQuery.getTranslatedSQLString(session, recordWithValues);

Back to the top