EJB3 EntityManager

Persisting Entities

• entityManager.persist(object);
• Can automatically generate a primary key
• Throws IllegalArgumentException if its parameter is not an entity type
• Throws TransactionRequiredException (Thrown by the persistence provider when a transaction is required but is not active).
• If the Entity Manager is an extended persistent context, it is legal to call persist() outside a transaction scope.
  

Finding entities

• There are 3 ways to find entities
• find(), getReference() and createQuery()
• The find() and getReference() methods works in the same way, they take the entity's class as a parameter and the primary key (Long).
  

find(Class entityClass, Object primaryKey);
getReference(Class entityClass, Object primaryKey);

Example:
Person person = null;
person = entityManager.find(Person.class, 5);

• Two differences between find() and getReference() methods

1. find() returns null if the entity is not found and the getReference() method throws a EntityNotFoundException.
2. find() method initializes the state, based on the lazy-loading policies of each property, getReference() does not do that.

• Both methods throws IllegalArgumentExceptions and they can be invoked outside the scope of transaction, but the object returned will be detached (unless entity manger is an extended persistent context).
• With the createQuery() method it is possible to use EJB QL, HQL.
• Summary: all the objects found using these three methods will remain managed as long as the persistent context in which you accessed them remains active.
  

Updating entities

• To update an object while it is while it is managed by the persistent context is very easy. All updates on returned object (from find(), getReference(), createQuery()) will be synchronized automatically (depending on the flush mode). This is true as long as an active persistence context is still associated with the transaction. (Read more about Transaction Attribute (defaults to Required) but can be set in either ejb-jar deployment descriptor or on the EJB's bean class using @TransactionAttribute)
  

Merging entities

• To merge state changes made to a detached entity back into persistent storage.

Example (person is a detached entity):
Person copy = entityManager.merge(person);

• There are two different scenarios for the merge method, depending on if the entity manager is already managing the person entity with the same ID or not.
  
• If the entity manager isn't managing the person entity with same ID, a full copy of the person parameter is made and returned from the merge() method. Now this copy will be managed by the entity manager and any additional setter methods called on it will be synchronized with the database (when flush).
• If the entity manager is already managing the person entity with the same ID, then the contents of the person parameter is copied into this managed object instance. The merge() operation will return this managed instance and the person parameter will remain detached and unmanaged.

Removing entities

• entityManager.remove(person);
• person instance will not be managed any longer and will become detached
  
• Associated entities may also be removed based on cascading rules
• remove() can only be undone using persist() again
  

Refresh entity

• Use entityManager.refresh(person) if you are concerned that the managed person entity is not up-to-date with the database. Will overwrite any changes of the managed entity with the one in the database.
  
• Related entities may also be refreshed based on the setup cascading policy.

Contains

• Use entityManager.contains(person) if you want to know if "person" is currently managed by the persistent context.

Clear

• Use entityManager.clear() if you want to detach all managed entity instances from a persistence context. (Any changes made to managed entities are lost). Avoid this by calling flush() before clear().

FlushModeType

• Flush is made automatically before any query (besides find() and getReference()) by the entity manager.
• Change default behaviour by using Flushmode.COMMIT instead of default AUTO.
• Using COMMIT means that changes are flushed only when the transaction commits, not before any query.
• Set FlushType by calling the entityManager.setFlushType() method

Transactions (read more here)