EclipseLink provides sophisticated and high performance object-relational mapping services and complete support for the JPA specification. JPA objects are mapped through the package [http://java.sun.com/javaee/5/docs/api/javax/persistence/package-summary.html 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 [http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManager.html EntityManager] class in the javax.persistence package. EclipseLink also provides extended runtime API through the package org.eclipse.persistence.jpa.

EclipseLink provides sophisticated and high performance object-relational mapping services and complete support for the JPA specification. JPA objects are mapped through the package [http://java.sun.com/javaee/5/docs/api/javax/persistence/package-summary.html 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 [http://java.sun.com/javaee/5/docs/api/javax/persistence/EntityManager.html EntityManager] class in the javax.persistence package. EclipseLink also provides extended runtime API through the package org.eclipse.persistence.jpa.

−

EclipseLink also provides a [http://en.wikipedia.org/wiki/Plain_Old_Java_Object 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.

+

EclipseLink also provides a [http://en.wikipedia.org/wiki/Plain_Old_Java_Object 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.

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 <code>SchemaManager</code> 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,

+

[[EclipseLink/Examples/JPA/EMAPI#Getting_a_JDBC_Connection_from_an_EntityManager|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.

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_Extensions_%28ELUG%29#Using_EclipseLink_JPA_Weaving|Using EclipseLink JPA Weaving]]

If a trigger is updating data required back in the application, or the id, the [http://www.eclipse.org/eclipselink/api/2.1/org/eclipse/persistence/annotations/ReturnInsert.html @ReturnInsert], [http://www.eclipse.org/eclipselink/api/2.1/org/eclipse/persistence/annotations/ReturnUpdate.html @ReturnUpdate] or [http://www.eclipse.org/eclipselink/api/2.1/org/eclipse/persistence/descriptors/ReturningPolicy.html 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.

** This should be the easiest to diagnose, as it is within your own code.

+

* Database - the database is deadlocked on a set of transactions.

+

** You will see JDBC access as the last call on the stack.

+

** This is normally caused by database table, row and page locks.

+

** Check for usages of pessimistic locking, or concurrent updates to the same set of rows.

+

** If a set of updates is deadlocking, trying setting the persistence unit property "eclipselink.order-updates"="true".

+

** EclipseLink avoids database deadlocks through several mechanisms, including providing optimistic locking, a read and sequence connection pool, and ordering writes by table, and ordering updates and deletes by id.

+

** Ensure a sequence connection pool is being used if using TABLE sequencing. See [http://www.eclipse.org/eclipselink/api/2.3/org/eclipse/persistence/config/PersistenceUnitProperties.html#CONNECTION_POOL_SEQUENCE PersistenceUnitProperties.CONNECTION_POOL_SEQUENCE];

* Connection pool - the application has exceed the size of the connection pool and a thread with a connection requires an additional connection.

+

** You will see a connection request as the last method on the stack.

+

** Ensure an adequate number of connections in your connection pool.

+

* Cache - If using a shared cache, EclipseLink requires locking the cache on reads and writes to ensure consistency.

+

** You will see cache access, such as IdentityMapManager acquireLock or acquireDeferredLock, or WriteLockManager as the last call on the stack.

+

** Ensure you are using the latest EclipseLink release, the issue may have been fixed. Otherwise log a bug including the relevant stack dump.

+

** This is normally related to having relationships that do not use LAZY, ensure all relationship use LAZY.

+

*** An alternative to using LAZY is to set the persistence unit property, <code>"eclipselink.weaving.eager"="true"</code>.

+

** It can also be caused by join fetching, so remove any join fetches to diagnose the problem.

+

** A workaround is to disable the shared cache. See [[EclipseLink/FAQ/How to disable the shared cache?|How to disable the shared cache?]].

+

** The cache isolation in EclipseLink can be configured. Try using a SessionCustomizer to call <code>session.getLogin().setCacheTransactionIsolation(CONCURRENT_READ_WRITE)</code>.

+

** A possible workaround is to configure <code>DeferredLockManager.SHOULD_USE_DEFERRED_LOCKS = false</code>.

+

+

==Do I have to maintain both sides of a bi-directional relationship?==

+

Yes, you need to maintain both sides of the relationship in JPA.

+

It is a common problem that an application does not do this, and then sees inconsistent objects afterwords.

+

This is normally not done by mistake, but is also done on purpose, normally with a ManyToOne/OneToMany relationship,

+

where the application programmer wants to avoid the cost of reading in the OneToMany collection, especially if it is large.

+

+

If you are updating a child in a OneToMany, then you just need to find() it, and update it, or use merge(). You do not need to merge() or modify the parent or its children relationship.

+

+

If you are adding a new child, then you need to persist() or merge() it, set its parent to the one from the current persistence context using find() (merge can do this, but if your parent is transient, or nulled out, then you need to do this yourself, and if the parent's children are transient or nulled out, then you need to be careful it is not merged or cascaded).

+

You also need to add the child to the parent's children (otherwise it will not be there in the current persistence context, or possibly future ones if you are using a shared cache).

+

+

If you are deleting a child, then you need to call remove() on it, unless you have set the relationship to deleteOrphans. You also need to remove it from the parent's children, (otherwise it will still be there in the current persistence context, or possibly future ones if you are using a shared cache).

+

+

There are alternatives to adding and removing the child though, if you want to avoid the cost of reading the children:

+

* If you are using LAZY relationship, a List (it is also possible with Set, but there can be issues), and weaving (static or dynamic), then add() and remove() will not instantiate the children.

+

* If the children is not something you want to ever read, then consider not mapping it, just query it if needed.

+

* If the parent's children is not instantiated, you could avoid adding the child. (see PersistenceUnitUtil.isLoaded()).

+

* You can call refresh() on the parent after the commit to reset its children.

+

* You can avoid adding the child if you clear or throw away your persistence unit, and are not using a shared cache.

+

+

==How to access what changed in an object or transaction?==

+

EclipseLink tracks changes made to managed objects within a persistence context or transaction. This allows EclipseLink to update only exactly what changed. Changes are tracked in two main different ways, depending on your objects and configuration. These are defined in the ChangeTrackingType enum, and are either ATTRIBUTE, OBJECT or DEFERRED.

+

+

ATTRIBUTE weaves a PropertyChangeListener into your class. Whenever any field in your class changes, this listener is notified of the change. ATTRIBUTE is used when weaving is enabled through dynamic or static weaving.

+

+

DEFERRED does not require any class changes, so is used when weaving is not enabled. A backup copy of the object is made when it is first registered in the persistence context. On commit or flush, the current managed state of the object is compared to the backup to determine the changes.

+

+

OBJECT uses a combination of the two.

+

+

EclipseLink creates instances of ObjectChangeSet that capture the changes made to an object. EclipseLink uses these change sets internally, but they are also available to the application if it also requires to know what has changed. There are two ways to access the change sets, directly from the UnitOfWork, and through events.

To access changes from events, EclipseLink's DescriptorEvents must be used. Descriptor events can be registered for using a DescriptorEventListener similar to using an EntityListener. DescriptorEventListener has events for pre/post/aboutTo Update/Insert/Delete. You can access the object from the event using <code>getObject</code> and you can access the change set using <code>getChangeSet</code>

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.

How do I migrate from using Oracle TopLink to EclipseLink?

How do I migrate from using TopLink Essentials to EclipseLink?

How do I migrate from another JPA provider to EclipseLink?

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.

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 (connect 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.

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.

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.

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).

This should be the easiest to diagnose, as it is within your own code.

Database - the database is deadlocked on a set of transactions.

You will see JDBC access as the last call on the stack.

This is normally caused by database table, row and page locks.

Check for usages of pessimistic locking, or concurrent updates to the same set of rows.

If a set of updates is deadlocking, trying setting the persistence unit property "eclipselink.order-updates"="true".

EclipseLink avoids database deadlocks through several mechanisms, including providing optimistic locking, a read and sequence connection pool, and ordering writes by table, and ordering updates and deletes by id.

The cache isolation in EclipseLink can be configured. Try using a SessionCustomizer to call session.getLogin().setCacheTransactionIsolation(CONCURRENT_READ_WRITE).

A possible workaround is to configure DeferredLockManager.SHOULD_USE_DEFERRED_LOCKS = false.

Do I have to maintain both sides of a bi-directional relationship?

Yes, you need to maintain both sides of the relationship in JPA.
It is a common problem that an application does not do this, and then sees inconsistent objects afterwords.
This is normally not done by mistake, but is also done on purpose, normally with a ManyToOne/OneToMany relationship,
where the application programmer wants to avoid the cost of reading in the OneToMany collection, especially if it is large.

If you are updating a child in a OneToMany, then you just need to find() it, and update it, or use merge(). You do not need to merge() or modify the parent or its children relationship.

If you are adding a new child, then you need to persist() or merge() it, set its parent to the one from the current persistence context using find() (merge can do this, but if your parent is transient, or nulled out, then you need to do this yourself, and if the parent's children are transient or nulled out, then you need to be careful it is not merged or cascaded).
You also need to add the child to the parent's children (otherwise it will not be there in the current persistence context, or possibly future ones if you are using a shared cache).

If you are deleting a child, then you need to call remove() on it, unless you have set the relationship to deleteOrphans. You also need to remove it from the parent's children, (otherwise it will still be there in the current persistence context, or possibly future ones if you are using a shared cache).

There are alternatives to adding and removing the child though, if you want to avoid the cost of reading the children:

If you are using LAZY relationship, a List (it is also possible with Set, but there can be issues), and weaving (static or dynamic), then add() and remove() will not instantiate the children.

If the children is not something you want to ever read, then consider not mapping it, just query it if needed.

If the parent's children is not instantiated, you could avoid adding the child. (see PersistenceUnitUtil.isLoaded()).

You can call refresh() on the parent after the commit to reset its children.

You can avoid adding the child if you clear or throw away your persistence unit, and are not using a shared cache.

How to access what changed in an object or transaction?

EclipseLink tracks changes made to managed objects within a persistence context or transaction. This allows EclipseLink to update only exactly what changed. Changes are tracked in two main different ways, depending on your objects and configuration. These are defined in the ChangeTrackingType enum, and are either ATTRIBUTE, OBJECT or DEFERRED.

ATTRIBUTE weaves a PropertyChangeListener into your class. Whenever any field in your class changes, this listener is notified of the change. ATTRIBUTE is used when weaving is enabled through dynamic or static weaving.

DEFERRED does not require any class changes, so is used when weaving is not enabled. A backup copy of the object is made when it is first registered in the persistence context. On commit or flush, the current managed state of the object is compared to the backup to determine the changes.

OBJECT uses a combination of the two.

EclipseLink creates instances of ObjectChangeSet that capture the changes made to an object. EclipseLink uses these change sets internally, but they are also available to the application if it also requires to know what has changed. There are two ways to access the change sets, directly from the UnitOfWork, and through events.

To access changes from events, EclipseLink's DescriptorEvents must be used. Descriptor events can be registered for using a DescriptorEventListener similar to using an EntityListener. DescriptorEventListener has events for pre/post/aboutTo Update/Insert/Delete. You can access the object from the event using getObject and you can access the change set using getChangeSet