Revision as of 15:58, 17 March 2009

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)

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

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. PESSIMISTIC_READ ---getPessimisticReadLockObjects() should contain the entity
3. OPTIMISTIC_FORCE_INCREMENT ---- getOptimisticReadLockObjects() should contain the entity with boolean value 'true'

   and 'getPessimisticReadLockObjects()' should NOT contain the entity

4. PESSIMISTIC_FORCE_INCREMENT---getOptimisticReadLockObjects() should the entity with boolean value 'true'

   and 'getPessimisticReadLockObjects()' should contain the entity.

5. NONE
6. READ --- It is same as OPTIMISTIC
7. 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.

The new lockmode 'PESSIMISTIC_WRITE' is yet to be implemented.

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