Chapter 2. Setup and configuration
Prev |  | Next

## Chapter 2. Setup and configuration

## 2.1. Setup

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.2.0.CR2 and Hibernate Annotations 3.2.0.CR1. 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).

## 2.2. Configuration and bootstrapping

### 2.2.1. Packaging

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 xmlns="http://java.sun.com/xml/ns/persistence"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
       version="1.0">
       <persistence-unit name="sample">
          <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 xmlns="http://java.sun.com/xml/ns/persistence"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
       version="1.0">
       <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>

`name`

  (attribute) Every entity manager must have a name.

`transaction-type`

  (attribute) Transaction type used. Either JTA or RESOURCE_LOCAL (default to JTA in a JavaEE environment and to RESOURCE_LOCAL in a JavaSE environment).

`provider`

  The provider is a fully-qualified class name of the EJB Persistence provider. You do not have to define it if you don't work with several EJB3 implementations. This is needed when you are using multiple vendor implementations of EJB Persistence.

`jta-data-source`, `non-jta-data-source`

  This is the JNDI name of where the javax.sql.DataSource is located. When running without a JNDI available Datasource, you must specify JDBC connections with Hibernate specific properties (see below).

`mapping-file`

  The class element specifies a EJB3 compliant XML mapping file that you will map. The file has to be in the classpath. As per the EJB3 specification, Hibernate EntityManager will try to load the mapping file located in the jar file at `META_INF/orm.xml`. Of course any explicit mapping file will be loaded too. As a matter of fact, you can provides any XML file in the mapping file element ie. either hbm files or EJB3 deployment descriptor.

`jar-file`

  The jar-file elements specifies a jar to analyse. All properly annotated classes, annotated packages and all hbm.xml files part of this jar file will be added to the persistence unit configuration. This element is mainly used in Java EE environment. Use of this one in Java SE should be considered as non portable, in this case a absolute url is needed.

`exclude-unlisted-classes`

  Do not check the main jar file for annotated classes. Only explicit classes will be part of the persistence unit.

`class`

  The class element specifies a fully qualified class name that you will map. By default all properly annotated classes and all hbm.xml files found inside the archive are added to the persistence unit configuration. You can add some external entity through the class element though. As an extension to the specification, you can add a package name in the `<class>` element (eg `<class>org.hibernate.eg</class>`).

`properties`

  The properties element is used to specify vendor specific properties. This is where you will define your Hibernate specific configurations. This is also where you will have to specify JDBC connection information as well.

Be sure to define the grammar definition in the `persistence` element since the EJB3 specification requires the schema validation. If the systemId ends with `persistence_1_0.xsd`, Hibernate entityManager will use the version embedded in the hibernate-entitymanager.jar. No internet access will be processed.

    <persistence xmlns="http://java.sun.com/xml/ns/persistence"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
       version="1.0">

### 2.2.2. Bootstrapping

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:

- javax.persistence.provider to define the provider class used

- javax.persistence.transactionType to define the transaction type used (either JTA or RESOURCE_LOCAL)

- javax.persistence.jtaDataSource to define the JTA datasource name in JNDI

- javax.persistence.nonJtaDataSource to define the non JTA datasource name in JNDI

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. Actually the `Persistence` class will look at all the Persistence Providers available in the classpath and ask each of them if they are responsible for the creation of the entity manager factory `manager1`. Each provider, 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 (of course the provider `element` must match the current persistent provider). If no persistence.xml with the correct name are found or if the expected persistence provider is not found, a `PersistenceException` is raised.

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.

Table 2.1. Hibernate Entity Manager specific properties

Property name | Description
--- | ---
hibernate.ejb.classcache.<classname> | class cache strategy [comma cache region] of the class Default to no cache, and default region cache to fully.qualified.classname (eg. hibernate.ejb.classcache.com.acme.Cat read-write or hibernate.ejb.classcache.com.acme.Cat read-write, MyRegion).
hibernate.ejb.collectioncache.<collectionrole> | collection cache strategy [comma cache region] of the class Default to no cache, and default region cache to fully.qualified.classname.role (eg. hibernate.ejb.classcache.com.acme.Cat read-write or hibernate.ejb.classcache.com.acme.Cat read-write, MyRegion).
hibernate.ejb.cfgfile | XML configuration file to use to configure Hibernate (eg. `/hibernate.cfg.xml`).
hibernate.archive.autodetection | Determine which element is auto discovered by Hibernate Entity Manager while parsing the .par archive. (default to `class,hbm`).
hibernate.ejb.interceptor | An optional Hibernate interceptor. This interceptor has to implement `org.hibernate.Interceptor` and have a no-arg constructor.
hibernate.ejb.naming_strategy | An optional naming strategy. The default naming strategy used is `EJB3NamingStrategy`. You also might want to consider the `DefaultComponentSafeNamingStrategy`.
hibernate.ejb.event.<eventtype> | Event listener list for a given eventtype. The list of event listeners is a comma separated fully qualified class name list (eg. hibernate.ejb.event.pre-load com.acme.SecurityListener, com.acme.AuditListener)
hibernate.ejb.use_class_enhancer | Whether or not use Application server class enhancement at deployment time (default to false)
hibernate.ejb.discard_pc_on_close | If true, the persistence context will be discarded (think clear() when the method is called. Otherwise the persistence context will stay alive till the transaction completion: all objects will remain managed, and any change will be sy,chronized with the database (default to false, ie wait the transaction completion)

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

### Note

It is important that you do not override `hibernate.transaction.factory_class`, Hibernate EntityManager automatically set the appropriate transaction factory depending on the EntityManager type (ie `JTA` versus `RESOURSE_LOCAL`). If you are working in a Java EE environment, you might want to set the `hibernate.transaction.manager_lookup_class` though.

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
         .addRerousce( "mypath/MyOtherCLass.hbm.xml ) //add an hbm.xml file
         .addRerousce( "mypath/orm.xml ) //add an EJB3 deployment descriptor
         .createEntityManagerFactory(); //Create the entity manager factory

## 2.3. Event listeners

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.

Table 2.2. Hibernate Entity Manager default event listeners

Event | Listeners
--- | ---
flush | org.hibernate.ejb.event.EJB3FlushEventListener
auto-flush | org.hibernate.ejb.event.EJB3AutoFlushEventListener
delete | org.hibernate.ejb.event.EJB3DeleteEventListener
flush-entity | org.hibernate.ejb.event.EJB3FlushEntityEventListener
merge | org.hibernate.ejb.event.EJB3MergeEventListener
create | org.hibernate.ejb.event.EJB3PersistEventListener
create-onflush | org.hibernate.ejb.event.EJB3PersistOnFlushEventListener
save | org.hibernate.ejb.event.EJB3SaveEventListener
save-update | org.hibernate.ejb.event.EJB3SaveOrUpdateEventListener
pre-insert | org.hibernate.secure.JACCPreInsertEventListener, org.hibernate.valitator.event.ValidateEventListener
pre-insert | org.hibernate.secure.JACCPreUpdateEventListener, org.hibernate.valitator.event.ValidateEventListener
pre-delete | org.hibernate.secure.JACCPreDeleteEventListener
pre-load | org.hibernate.secure.JACCPreLoadEventListener
post-delete | org.hibernate.ejb.event.EJB3PostDeleteEventListener
post-insert | org.hibernate.ejb.event.EJB3PostInsertEventListener
post-load | org.hibernate.ejb.event.EJB3PostLoadEventListener
post-update | org.hibernate.ejb.event.EJB3PostUpdateEventListener

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.

## 2.4. Obtaining an EntityManager in a J2SE environment

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 `EntityManager`s. The `Persistence` class is bootstrap class to create an entity manager factory.

    // Use persistence.xml configuration
    EntityManagerFactory emf = Persistence.createEntityManagerFactory("manager1")
    EntityManager em = emf.createEntityManager(); // Retrieve an application managed 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. Calls to the entityManagerFactory are thread safe.

Thanks to the EntityManagerFactory, you can retrieve an extended entity manager. 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 (unless you call entityManager.clear() in between). You can see an entity manager as a small wrapper on top of an Hibernate session.

TODO explains emf.createEntityManager(Map)

## 2.5. Various

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.

Prev | Up | Next
Chapter 1. Architecture | Home | Chapter 3. Working with objects