The EJB3 compatible Hibernate EntityManager is built on top of Hibernate core and Hibernate Annotations. You have to use compatible versions of each module. This version is known to work on Hibernate 3.1.1 and Hibernate Annotations 3.1beta8. The following libraries have to be in your classpath: hibernate3.jar, hibernate-annotations.jar, hibernate-entity-manager.jar and all needed third party libraries for each package.(incl. ejb-persistence.jar).

The configuration for entity managers both inside an application server and in a standalone application reside in a persistence archive. A persistence archive is a JAR file which must define a persistence.xml file that resides in the META-INF folder. All properly annotated classes included in the archive (ie having an @Entity annotation), all annotated packages and all Hibernate hbm.xml files included in the archive will be added to the persistence unit configuration, so by default, your persistence.xml will be quite minimalist:

<persistence>
   <persistence-unit>
      <jta-data-source>java:/DefaultDS</jta-data-source>
      <properties>
         <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
         <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
      </properties>
   </persistence-unit>
</persistence>

Here's a more complete example of a persistence.xml file

<persistence>
   <persistence-unit name="manager1" transaction-type="JTA">
      <provider>org.hibernate.ejb.HibernatePersistence</provider>
      <jta-data-source>java:/DefaultDS</jta-data-source>
      <mapping-file>ormap.xml</mapping-file>
      <jar-file>MyApp.jar</jar-file>
      <class>org.acme.Employee</class>
      <class>org.acme.Person</class>
      <class>org.acme.Address</class>
      <properties>
         <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
         <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
      </properties>
   </persistence-unit>
</persistence>
     

The EJB3 specification defines a bootstrap procedure to access the EntityManagerFactory and the EntityManager. The bootstrap class is javax.persistence.Persistence, e.g.

EntityManagerFactory emf = Persistence.createEntityManagerFactory("manager1");
//or
Map configOverrides = new HashMap();
configOverrides.put("hibernate.hbm2ddl.auto", "create-drop");
EntityManagerFactory programmaticEmf =
    Persistence.createEntityManagerFactory("manager1", configOverrides);

The first version is equivalent to the second with an empty map. The map version is a set of overrides that will take precedence over any properties defined in your persistence.xml files. There are a couple of EJB3 properties usable in the map:

When Persistence.createEntityManagerFactory() is called, the persistence implementation will search your classpath for any META-INF/persistence.xml files using the ClassLoader.getResource("META-INF/persistence.xml") method. From this list of resources, it will try to find an entity manager that matches the name you specify in the command line with what is specified in the persistence.xml file. If no persistence.xml with the correct name are found, a PersistenceException is raised. If there is only one persistence.xml in your classpath, you don't have to declare any entity manager factory name (however, if several files are found, a PersistenceException is raised).

EntityManagerFactory emf = Persistence.createEntityManagerFactory(null);

Apart from Hibernate system-level settings, all the properties available in Hibernate can be set in properties element of the persistence.xml file or as an override in the map you pass to createEntityManagerFactory(). Please refer to the Hibernate reference documentation for a complete listing. There are however a couple of properties available in the EJB3 provider only.

Note that you can mix XML <class> declaration and hibernate.ejb.cfgfile usage in the same configuration. Be aware of the potential clashed. The properties set in persistence.xml will override the one in the defined hibernate.cfg.xml.

Here is a typical configuration in a J2SE environment

<persistence>
   <persistence-unit name="manager1" transaction-type="RESOURCE_LOCAL">
      <class>org.hibernate.ejb.test.Cat</class>
      <class>org.hibernate.ejb.test.Distributor</class>
      <class>org.hibernate.ejb.test.Item</class>
      <properties>
         <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
         <property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver"/>
         <property name="hibernate.connection.username" value="sa"/>
         <property name="hibernate.connection.password" value=""/>
         <property name="hibernate.connection.url" value="jdbc:hsqldb:."/>
         <property name="hibernate.max_fetch_depth" value="3"/>
       
         <!-- cache configuration -->
         <property name="hibernate.ejb.classcache.org.hibernate.ejb.test.Item" value="read-write"/>
         <property name="hibernate.ejb.collectioncache.org.hibernate.ejb.test.Item.distributors" value="read-write, RegionName"/>

         <!-- alternatively to <class> and <property> declarations, you can use a regular hibernate.cfg.xml file -->
         <!-- property name="hibernate.ejb.cfgfile" value="/org/hibernate/ejb/test/hibernate.cfg.xml"/ -->
      </properties>
   <persistence-unit>
</persistence>

To ease the programmatic configuration, Hibernate Entity Manager provide a proprietary API. This API is very similar to the Configuration API and share the same concepts: Ejb3Configuration. Refer to the JavaDoc and the Hibernate reference guide for more detailed informations on how to use it.

TODO: me more descriptive on some APIs like setDatasource()

Ejb3Configuration cfg = new Ejb3Configuration();
EntityManagerFactory emf = 
  cfg.configure("/mypath/hibernate.cfg.xml") //add a regular hibernate.cfg.xml
     .addProperties( properties ) //add some properties
     .setInterceptor( myInterceptorImpl ) // set an interceptor
     .addAnnotatedClass( MyAnnotatedClass.class ) //add a class to be mapped
     .addClass( NonAnnotatedClass.class ) //add an hbm.xml file using the Hibernate convention
     .addFile( "/mypath/MyOtherCLass.hbm.xml ) //add an hbm.xml file
     .createEntityManagerFactory(); //Create the entity manager factory

Hibernate Entity Manager needs to enhance Hibernate core to implements all the EJB3 semantics. It does that through the event listener system of Hibernate. Be careful when you use the event system yourself, you might override some of the EJB3 semantics. A safe way is to add your event listeners to the list given below.

Note that the JACC*EventListeners are removed if the security is not enabled.

You can configure the event listeners either through the properties (see Configuration and bootstrapping) or through the ejb3configuration.getEventListeners() API.

An entity manager factory should be considered as an immutable configuration holder, it is defined to point to a single datasource and to map a defined set of entities. This is the entry point to create and manage EntityManagers. The Persistence class is bootstrap class to create an entity manager factory.

// Use persistence.xml configuration
EntityManagerFactory emf = Peristence.createEntityManagerFactory("manager1")
EntityManager em = emf.createEntityManager(); // Retrieve a transactional-scoped entity manager
// Work with the EM
em.close();
...
emf.close(); //close at application end

An entity manager factory is typically create at application initialization time and closed at application end. It's creation is an expensive process. For those who are familiar with Hibernate, an entity manager factory is very much like a session factory. Actually, an entity manager factory is a wrapper on top of a session factory.

There are two kinds of entity managers. The transaction-scoped entity manager (default) create and destroy a persistence context for each transaction: in other words, the managed entities are detached once the transaction ends. The extended entity manager keep the same persistence context for the lifetime of the entity manager: in other words, the entities are still managed between two transactions. emf.createEntityManager() creates a transaction-scoped entity manager and emf.createEntityManager(PersistenceContextType.EXTENDED) creates an extended entity manager. You can see an entity manager as a small wrapper on top of an Hibernate session.

Hibernate Entity Manager comes with Hibernate Validator configured out of the box. You don't have to override any event yourself. If you do not use Hibernate Validator annotations in your domain model, there will be no performance cost. For more information on Hibernate Validator, please refer to the Hibernate Annotations reference guide.