Jump to: navigation, search

EclipseLink/Development/JPA 2.0/entitymanager updates

Updated EntityManager / Query APIs

JPA 2.0 Root | Enhancement Request

Issue Summary

In JPA 2.0 the specification extends EntityManager and Query APIs. New APIs have been added for getting supported properties and getting the owning Entity Manager Factory.

A new operation 'detach' was also added including a new Cascade Type. Calling detach on an Entity allows the user to remove an Entity and cascaded related entities from the persistence context. Effectively an unregister call.

See JPA 2.0 ED section 3.1.1 and 3.2.6 for details.

New methods are added to EM API in the latest spec. Here are the new methods that are added to the latest specification:

find(Class <T> entityClass, Object primaryKey, Map<String,Object> properties)

refresh(Object entity, Map<String,Object> properties)

detach(Object entity) and CascadeType.DETACH

setProperty(String propertyName,Object value)


General Solution

The implementation of this functionality should be straight forward.

Work Required

  1. Develop test for testing new non-pessimistic locking APIs
    approx 2 days
  2. Update Processing to
    approx 3 days - clear(Object entity)
    approx 2 days - remaining APIs
    approx 2 days - Query Hints
  3. The new lockmodes 'PESSIMISTIC_READ' and 'PESSIMISTIC_WRITE',setProperty(Object,Value),createQuery(CriteriaQuery),
    getQueryBuilder(),and getMetamodel() are yet to be implemented.
  4. And also CascadeType.DETACH is yet to be implemented.

Work Completed

Implementation of the following functions have been completed so far in EM API Update

  1. public Map<String,Object> getProperties();
  2. public Set<String> getSupportedProperties();
  3. public void detach(Object entity);
  4. public <T> T unwrap(Class<T> cls);
  5. public EntityManagerFactory getEntityManagerFactory();
  6. public LockModeType getLockMode(Object entity);
  7. find(Class <T> entityClass, Object primaryKey, Map<String,Object> properties)
  8. refresh(Object entity, Map<String,Object> properties)

Implementation Details

Here are the implementation details described briefly of the 'getLockMode(Object entity)' method -- In EclipseLink, optimistically and pessimistically locked objects are tracked in 'getOptimisticReadLockObjects()' and 'getPessimisticReadLockObjects()' . The 'getOptimisticReadLockObjects()' returns a map that contains boolean as value . The 'getPessimisticReadLockObjects()' returns a map that contains an object as value. When an object is locked , the following has to be checked to determine the lockmodetype-

  1. OPTIMISTIC --- getOptimisticReadLockObjects() should contain the entity with boolean value 'false'
  2. OPTIMISTIC_FORCE_INCREMENT ---- getOptimisticReadLockObjects() should contain the entity with boolean value 'true'
    and 'getPessimisticReadLockObjects()' should NOT contain the entity
  3. PESSIMISTIC_FORCE_INCREMENT---getOptimisticReadLockObjects() should the entity with boolean value 'true'
    and 'getPessimisticReadLockObjects()' should contain the entity.
  4. NONE
  5. READ --- It is same as OPTIMISTIC
  6. WRITE --- It is same as OPTIMISTIC_FORCE_INCREMENT


As discussed , when getLockMode(entity) is called on an entity that is removed, it throws 'IllegalArgumentException.' This has been

taken care by checking whether the entity is contained in the active unit of work or not.


'getProperties()' method returns a unmodifiable Map of properties that the entity manager possess.If the entity manager is created

by passing 'properties' , then the passed properties are appended to the underlying session properties and are returned back the user.

If no properties are passed through entity manager, only the underlying session properties are returned.

'getSupportedProperties()' method returns all the properties that the entity manager can support irrespective of whether it is set or not.

Here are the list of supported properties in Entity Manager API:

  1. JOIN_EXISTING_TRANSACTION
  2. PERSISTENCE_CONTEXT_REFERENCE_MODE
  3. PERSISTENCE_CONTEXT_CLOSE_ON_COMMIT
  4. PERSISTENCE_CONTEXT_PERSIST_ON_COMMIT
  5. PERSISTENCE_CONTEXT_FLUSH_MODE
  6. ORACLE_PROXY_TYPE
  7. EXCLUSIVE_CONNECTION_MODE
  8. EXCLUSIVE_CONNECTION_IS_LAZY
  9. JTA_DATASOURCE
  10. NON_JTA_DATASOURCE
  11. JDBC_DRIVER
  12. JDBC_URL
  13. JDBC_USER
  14. JDBC_PASSWORD
  15. CONNECTION_POLICY
  16. VALIDATE_EXISTENCE
  17. FLUSH_CLEAR_CACHE

'unwrap(Class<T> cls)' unwraps the following classes :

  1. unwrapping UnitOfWork.class --- returns UnitOfWork
  2. unwrapping JpaEntityManager.class --- returns EntityManagerImpl
  3. unwrapping Session.class --- returns ServerSession
  4. unwrapping Connection.class --- returns Connection

unwrapping classes other than the above throws an persistence exception.

'detach(Object entity)' throws an 'IllegalArgumentException' if null or a non-entity is passed as argument. 'detach(entity)' basically unregisters

the object from the unitofwork. It basically removes it from IdentityMapAccessor and also from the clone mapping.

Rest of the method implementations are quite straight-forward.

Open Issues

em.detach() - triggered indirection on a detached instance for mappings marked as CascadeType.DETACH must return detached instances as well. Currently those instances would be managed. Mappings not marked CascadeType.DETACH should continue to return managed instances.