Hibernate.orgCommunity Documentation

Chapter 2. Setup and configuration

2.1. Setup
2.2. Configuration and bootstrapping
2.2.1. Packaging
2.2.2. Bootstrapping
2.3. Event listeners
2.4. Obtaining an EntityManager in a Java SE environment
2.5. Various

2.1. Setup

The JPA 2.0 compatible Hibernate EntityManager is built on top of the core of Hibernate and Hibernate Annotations. Starting from version 3.5, we have bundled in a single Hibernate distribution all the necessary modules:

Download the Hibernate Core distribution. Set up your classpath (after you have created a new project in your favorite IDE):

What is hibernate-jpa-2.0-api-x.y.z.jar?

This is the JAR containing the JPA 2.0 API, it provides all the interfaces and concrete classes that the specification defines as public API. Said otherwise, you can use this JAR to bootstrap any JPA provider implementation. Note that you typically don't need it when you deploy your application in a Java EE 6 application server (like JBoss AS 6 for example).

Alternatively, if you use Maven, add the following dependencies


<project ...>

  ...

  <dependencies>

    <dependency>

      <groupId>org.hibernate</groupId>

      <artifactId>hibernate-entitymanager</artifactId>

      <version>${hibernate-core-version}</version>

    </dependency>

  </dependencies>

</project>

All the required dependencies like hibernate-core and hibernate-annotations will be dragged transitively.

We recommend you use Hibernate Validator and the Bean Validation specification capabilities as its integration with Java Persistence 2 has been standardized. Download Hibernate Validator 4 or above from the Hibernate website and add hibernate-validator.jar and validation-api.jar in your classpath. Alternatively add the following dependency in your pom.xml.


<project>

  ...

  <dependencies>

    <dependency>

      <groupId>org.hibernate</groupId>

      <artifactId>hibernate-validator</artifactId>

      <version>${hibernate-validator-version}</version>

    </dependency>

    ...

  </dependencies>

  ...

</project>

If you wish to use Hibernate Search (full-text search for Hibernate aplications), download it from the Hibernate website and add hibernate-search.jar and its dependencies in your classpath. Alternatively add the following dependency in your pom.xml.


<project>

  ...

  <dependencies>

    <dependency>

      <groupId>org.hibernate</groupId>

      <artifactId>hibernate-search</artifactId>

      <version>${hibernate-search-version}</version>

    </dependency>

    ...

  </dependencies>

  ...

</project>

2.2. Configuration and bootstrapping

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_2_0.xsd"

             version="2.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_2_0.xsd"

             version="2.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>

      <shared-cache-mode>ENABLE_SELECTOVE</shared-cache-mode>

      <validation-mode>CALLBACK</validation-mode>

      <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). When a jta-datasource is used, the default is JTA, if non-jta-datasource is used, RESOURCE_LOCAL is used.

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. You can alternatively point to a directory (This is especially useful when in your test environment, the persistence.xml file is not under the same root directory or jar than your domain model).


        <jar-file>file:/home/turin/work/local/lab8/build/classes</jar-file>
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>). Caution, the package will include the metadata defined at the package level (ie in package-info.java), it will not include all the classes of a given package.

shared-cache-mode

By default, entities are elected for second-level cache if annotated with @Cacheable. You can however:

See Hibernate Annotation's documentation for more details.

validation-mode

By default, Bean Validation (and Hibernate Validator) is activated. When an entity is created, updated (and optionally deleted), it is validated before being sent to the database. The database schema generated by Hibernate also reflects the constraints declared on the entity.

You can fine-tune that if needed:

Unfortunately, DDL is not standard mode (though extremely useful) and you will not be able to put it in <validation-mode>. To use it, add a regular property


<property name="javax.persistence.validation.mode">

  ddl

</property>

With this approach, you can mix ddl and callback modes:


<property name="javax.persistence.validation.mode">

  ddl, callback

</property>
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.

Here is a list of JPA 2 standard properties. Be sure to also Hibernate Core's documentation to see Hibernate specific properties.

Note

To know more about Bean Validation and Hibernate Validator, check out Hibernate Validator's reference documentation as well as Hibernate Annotations's documentation on Bean Validation.

The following properties can only be used in a SE environment where no datasource/JNDI is available:

Be sure to define the grammar definition in the persistence element since the JPA specification requires schema validation. If the systemId ends with persistence_2_0.xsd, Hibernate entityManager will use the version embedded in the hibernate-entitymanager.jar. It won't fetch the resource from the internet.


<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_2_0.xsd"

             version="2.0">

The JPA 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<String, Object> configOverrides = new HashMap<String, Object>();

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. All the properties defined in Section 2.2.1, “Packaging” can be passed to the createEntityManagerFactory method and there are a few additional ones:

  • 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

  • javax.persistence.lock.timeout pessimistic lock timeout in milliseconds (Integer or String)

  • javax.persistence.query.timeout query timeout in milliseconds (Integer or String)

  • javax.persistence.sharedCache.mode corresponds to the share-cache-mode element defined in Section 2.2.1, “Packaging”.

  • javax.persistence.validation.mode corresponds to the validation-mode element defined in Section 2.2.1, “Packaging”.

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 nameDescription
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.cfgfileXML configuration file to use to configure Hibernate (eg. /hibernate.cfg.xml).
hibernate.archive.autodetectionDetermine which element is auto discovered by Hibernate Entity Manager while parsing the .par archive. (default to class,hbm).
hibernate.ejb.interceptorAn optional Hibernate interceptor. The interceptor instance is shared by all Session instances. This interceptor has to implement org.hibernate.Interceptor and have a no-arg constructor. This property can not be combined with hibernate.ejb.interceptor.session_scoped.
hibernate.ejb.interceptor.session_scopedAn optional Hibernate interceptor. The interceptor instance is specific to a given Session instance (and hence can be non thread-safe). This interceptor has to implement org.hibernate.Interceptor and have a no-arg constructor. This property can not be combined with hibernate.ejb.interceptor.
hibernate.ejb.naming_strategyAn 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_enhancerWhether or not use Application server class enhancement at deployment time (default to false)
hibernate.ejb.discard_pc_on_closeIf 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 synchronized with the database (default to false, ie wait the transaction completion)
hibernate.ejb.resource_scanner

By default, Hibernate EntityManager scans itself the list of resources for annotated classes and persistence deployment descriptors (like orm.xml and hbm.xml files).

You can customize this scanning strategy by implementing org.hibernate.ejb.packaging.Scanner. This property is used by container implementors to improve integration with Hibernate.

Accepts an instance of Scanner or the file name of a no-arg constructor class implementing Scanner.


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 Java SE 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="javax.persistence.jdbc.driver" value="org.hsqldb.jdbcDriver"/>

         <property name="javax.persistence.jdbc.user" value="sa"/>

         <property name="javax.persistence.jdbc.password" value=""/>

         <property name="javax.persistence.jdbc.url" value="jdbc:hsqldb:."/>

         <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/

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

     .configure("/mypath/hibernate.cfg.xml") //add a regular hibernate.cfg.xml

     .buildEntityManagerFactory(); //Create the entity manager factory

2.3. Event listeners

Hibernate Entity Manager needs to enhance Hibernate core to implements all the JPA 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 JPA semantics. A safe way is to add your event listeners to the list given below.

Table 2.2. Hibernate Entity Manager default event listeners

EventListeners
flushorg.hibernate.ejb.event.EJB3FlushEventListener
auto-flushorg.hibernate.ejb.event.EJB3AutoFlushEventListener
deleteorg.hibernate.ejb.event.EJB3DeleteEventListener
flush-entityorg.hibernate.ejb.event.EJB3FlushEntityEventListener
mergeorg.hibernate.ejb.event.EJB3MergeEventListener
createorg.hibernate.ejb.event.EJB3PersistEventListener
create-onflushorg.hibernate.ejb.event.EJB3PersistOnFlushEventListener
saveorg.hibernate.ejb.event.EJB3SaveEventListener
save-updateorg.hibernate.ejb.event.EJB3SaveOrUpdateEventListener
pre-insertorg.hibernate.secure.JACCPreInsertEventListener
pre-insertorg.hibernate.secure.JACCPreUpdateEventListener
pre-deleteorg.hibernate.secure.JACCPreDeleteEventListener
pre-loadorg.hibernate.secure.JACCPreLoadEventListener
post-deleteorg.hibernate.ejb.event.EJB3PostDeleteEventListener
post-insertorg.hibernate.ejb.event.EJB3PostInsertEventListener
post-loadorg.hibernate.ejb.event.EJB3PostLoadEventListener
post-updateorg.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 Java SE 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 EntityManagers. 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.

Copyright © 2005 Red Hat Inc. and the various authors