![[Note]](img/note.gif) | Note |
|---|---|
Kodo also includes the KodoPersistence 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.
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|mapp ing-file)*, execlude-unlisted-classes?,properties?)> <!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 persistence-unit name CDATA #REQUIRED> <!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.
provider: If you are using a third-party EJB persistence vendor, this element names its implementation of the PersistenceProvider bootstrapping interface.
Note Set the provider to kodo.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.
jar-file*: The names of jar files containing entities and embeddable 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>kodo.persistence.PersistenceProviderImpl</provider> <class>tutorial.Animal</class> <class>tutorial.Dog</class> <class>tutorial.Rabbit</class> <class>tutorial.Snake</class> <properties> <property name="kodo.LicenseKey" value="XXXX"/> <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>