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). 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 do not 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 provide 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>
). Specifying a package in the<class>
element will include only the annotated classes. 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 performed.
<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">