Hibernate.orgCommunity Documentation
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>
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>
<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
<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>
nametransaction-typeproviderjta-data-source,
non-jta-data-sourcemapping-filejar-file<jar-file>file:/home/turin/work/local/lab8/build/classes</jar-file>
exclude-unlisted-classesclassYou can fine-tune that if needed:
<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>
propertiesThe following properties can only be used in a SE environment where no datasource/JNDI is available:
<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">
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.
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.
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
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.
Copyright © 2005 Red Hat Inc. and the various authors