Chapter 6. Persistence
Prev | Part 2. Java Persistence API | Next

## Chapter 6. Persistence

| Note
Kodo also includes the `OpenJPAPersistence` helper class to provide additional utility methods.

Within a container, you will typically use injection to access an `EntityManagerFactory`. Applications operating of a container, however, can use the `Persistence` class to obtain `EntityManagerFactory` objects in a vendor-neutral fashion.

    public static EntityManagerFactory createEntityManagerFactory (String name);
    public static EntityManagerFactory createEntityManagerFactory (String name, Map props);

Each `createEntityManagerFactory` method searches the system for an `EntityManagerFactory` definition with the given name. Use `null` for an unnamed factory. The optional map contains vendor-specific property settings used to further configure the factory.

`persistence.xml` files define `EntityManagerFactories`. The `createEntityManagerFactory` methods search for `persistence.xml` files within the `META-INF` directory of any `CLASSPATH` element. For example, if your `CLASSPATH` contains the `conf` directory, you could place an `EntityManagerFactory` definition in `conf/META-INF/persistence.xml`.

## 6.1. persistence.xml

The `persistence.xml` file format obeys the following Document Type Descriptor (DTD):

    <!ELEMENT persistence (persistence-unit*)>
    <!ELEMENT persistence-unit (description?,provider?,jta-datasource?,
    	non-jta-datasource?,(class|jar-file|mapping-file)*,
    	exclude-unlisted-classes?,properties?)>
    <!ATTLIST persistence-unit name CDATA #REQUIRED>
    <!ATTLIST persistence-unit transaction-type (JTA|RESOURCE_LOCAL) "JTA">
    <!ELEMENT description (#PCDATA)>
    <!ELEMENT provider (#PCDATA)>
    <!ELEMENT jta-datasource (#PCDATA)>
    <!ELEMENT non-jta-datasource (#PCDATA)>
    <!ELEMENT mapping-file (#PCDATA)>
    <!ELEMENT jar-file (#PCDATA)>
    <!ELEMENT class (#PCDATA)>
    <!ELEMENT exclude-unlisted-classes EMPTY>
    <!ELEMENT properties (property*)>
    <!ELEMENT property EMPTY>
    <!ATTLIST property name CDATA #REQUIRED>
    <!ATTLIST property value CDATA #REQUIRED>

The root element of a `persistence.xml` file is `persistence`, which then contains one or more `persistence-unit` definitions. Each persistence unit describes the configuration for the entity managers created by the persistence unit's entity manager factory. The persistence unit can specify these elements and attribtues.

- `name`: This is the name you pass to the `Persistence.createEntityManagerFactory` methods described above. The name attribute is required.

- `transaction-type`: Whether to use managed (`JTA`) or local (`RESOURCE_LOCAL`) transaction management.

- `provider`: If you are using a third-party JPA vendor, this element names its implementation of the `PersistenceProvider` bootstrapping interface.

  | Note
  Set the `provider` to `org.apache.openjpa.persistence.PersistenceProviderImpl` to use Kodo.

- `jta-data-source`: The JNDI name of a JDBC `DataSource` that is automatically enlisted in JTA transactions. This may be an XA `DataSource`.

- `non-jta-data-source`: The JNDI name of a JDBC `DataSource` that is not enlisted in JTA transactions.

- `mapping-file`*: The resource names of XML mapping files for entities and embeddable classes. You can also specify mapping information in an `orm.xml` file in your `META-INF` directory. If present, the `orm.xml` mapping file will be read automatically.

- `jar-file`*: The names of jar files containing entities and embeddable classes. The implementation will scan the jar for annotated classes.

- `class`*: The class names of entities and embeddable classes.

- `properties`: This element contains nested `property` elements used to specify vendor-specific settings. Each `property` has a name attribute and a value attribute.

  | Note
  The Reference Guide's Chapter 2, Configuration describes Kodo's configuration properties.

Here is a typical `persistence.xml` file for a non-EE environment:

Example 6.1. persistence.xml

    <?xml version="1.0"?>
    <persistence>
    	<persistence-unit name="kodo">
    		<provider>
                org.apache.openjpa.persistence.PersistenceProviderImpl
            </provider>
    		<class>tutorial.Animal</class>
    		<class>tutorial.Dog</class>
    		<class>tutorial.Rabbit</class>
    		<class>tutorial.Snake</class>
    		<properties>
    			<property name="kodo.ConnectionURL" value="jdbc:hsqldb:tutorial_database"/>
    			<property name="kodo.ConnectionDriverName" value="org.hsqldb.jdbcDriver"/>
    			<property name="kodo.ConnectionUserName" value="sa"/>
    			<property name="kodo.ConnectionPassword" value=""/>
    			<property name="kodo.Log" value="DefaultLevel=WARN, Tool=INFO"/>
    		</properties>
    	</persistence-unit>
    </persistence>

Prev | Up | Next
5.4. Conclusion | Home | 6.2. Non-EE Use