| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Chapter 6. Persistence</title><link rel="stylesheet" href="css/docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><link rel="start" href="manual.html" title="Apache OpenJPA 1.2 User's Guide"><link rel="up" href="jpa_overview.html" title="Part 2. Java Persistence API"><link rel="prev" href="jpa_overview_meta_complete.html" title="4. Conclusion"><link rel="next" href="jpa_overview_persistence_use.html" title="2. Non-EE Use"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. |
| Persistence |
| </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_meta_complete.html">Prev</a> </td><th width="60%" align="center">Part 2. Java Persistence API</th><td width="20%" align="right"> <a accesskey="n" href="jpa_overview_persistence_use.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en" id="jpa_overview_persistence"><div class="titlepage"><div><div><h2 class="title"><a name="jpa_overview_persistence"></a>Chapter 6. |
| Persistence |
| </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="jpa_overview_persistence.html#jpa_overview_persistence_xml">1. |
| persistence.xml |
| </a></span></dt><dt><span class="section"><a href="jpa_overview_persistence_use.html">2. |
| Non-EE Use |
| </a></span></dt></dl></div><a class="indexterm" name="d0e3912"></a><a class="indexterm" name="d0e3915"></a><a class="indexterm" name="d0e3920"></a><a class="indexterm" name="d0e3925"></a><div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="285"><tr><td><img src="img/persistence.png"></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| OpenJPA also includes the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAPersistence.html" target="_top"> |
| <code class="classname">OpenJPAPersistence</code></a> helper class to provide |
| additional utility methods. |
| </p></div><p> |
| Within a container, you will typically use <span class="emphasis"><em>injection</em></span> to |
| access an <code class="classname">EntityManagerFactory</code>. Applications operating |
| of a container, however, can use the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/Persistence.html" target="_top"> |
| <code class="classname">Persistence</code></a> class to obtain <code class="classname"> |
| EntityManagerFactory</code> objects in a vendor-neutral fashion. |
| </p><pre class="programlisting"> |
| public static EntityManagerFactory createEntityManagerFactory(String name); |
| public static EntityManagerFactory createEntityManagerFactory(String name, Map props); |
| </pre><p> |
| Each <code class="methodname">createEntityManagerFactory</code> method searches the |
| system for an <code class="classname">EntityManagerFactory</code> definition with the |
| given name. Use <code class="literal">null</code> for an unnamed factory. The optional map |
| contains vendor-specific property settings used to further configure the |
| factory. |
| </p><p> |
| <code class="filename">persistence.xml</code> files define <code class="classname"> |
| EntityManagerFactories</code>. The <code class="methodname">createEntityManagerFactory |
| </code> methods search for <code class="filename">persistence.xml</code> files |
| within the <code class="filename">META-INF</code> directory of any <code class="literal">CLASSPATH |
| </code> element. For example, if your <code class="literal">CLASSPATH</code> contains |
| the <code class="filename">conf</code> directory, you could place an <code class="classname"> |
| EntityManagerFactory</code> definition in <code class="filename"> |
| conf/META-INF/persistence.xml</code>. |
| </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jpa_overview_persistence_xml"></a>1. |
| persistence.xml |
| </h2></div></div></div><p> |
| The <code class="filename">persistence.xml</code> file format obeys the following |
| Document Type Descriptor (DTD): |
| </p><pre class="programlisting"> |
| <!ELEMENT persistence (persistence-unit*)> |
| <!ELEMENT persistence-unit (description?,provider?,jta-data-source?, |
| non-jta-data-source?,(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-data-source (#PCDATA)> |
| <!ELEMENT non-jta-data-source (#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> |
| </pre><p> |
| The root element of a <code class="filename">persistence.xml</code> file is <code class="literal"> |
| persistence</code>, which then contains one or more <code class="literal"> |
| persistence-unit</code> 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. |
| </p><div class="itemizedlist"><ul type="disc"><li><p> |
| <code class="literal">name</code>: This is the name you pass to the <code class="methodname"> |
| Persistence.createEntityManagerFactory</code> methods described above. The |
| name attribute is required. |
| </p></li><li><p> |
| <code class="literal">transaction-type</code>: Whether to use managed |
| (<code class="literal">JTA</code>) or local (<code class="literal">RESOURCE_LOCAL</code>) |
| transaction management. |
| </p></li><li><p> |
| <code class="literal">provider</code>: If you are using a third-party JPA vendor, this |
| element names its implementation of the |
| <a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://java.sun.com/javaee/5/docs/api/javax/persistence/spi/PersistenceProvider.html" target="_top"> |
| <code class="classname">PersistenceProvider</code></a> bootstrapping interface. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| Set the <code class="literal">provider</code> to <code class="classname"> |
| org.apache.openjpa.persistence.PersistenceProviderImpl</code> to use |
| OpenJPA. |
| </p></div></li><li><p> |
| <code class="literal">jta-data-source</code>: The JNDI name of a JDBC <code class="classname"> |
| DataSource</code> that is automatically enlisted in JTA transactions. This |
| may be an XA <code class="classname">DataSource</code>. |
| </p></li><li><p> |
| <code class="literal">non-jta-data-source</code>: The JNDI name of a JDBC <code class="classname"> |
| DataSource</code> that is not enlisted in JTA transactions. |
| </p></li><li><p> |
| <code class="literal">mapping-file</code>*: The resource names of XML mapping files for |
| entities and embeddable classes. You can also specify mapping information in an |
| <code class="filename">orm.xml</code> file in your <code class="filename">META-INF</code> |
| directory. If present, the <code class="filename">orm.xml</code> mapping file will be |
| read automatically. |
| </p></li><li><p> |
| <code class="literal">jar-file</code>*: The names of jar files containing entities and |
| embeddable classes. The implementation will scan the jar for annotated classes. |
| </p></li><li><p> |
| <code class="literal">class</code>*: The class names of entities and embeddable classes. |
| </p></li><li><p> |
| <code class="literal">properties</code>: This element contains nested <code class="literal">property |
| </code> elements used to specify vendor-specific settings. Each <code class="literal"> |
| property</code> has a name attribute and a value attribute. |
| </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| The Reference Guide's <a href="ref_guide_conf.html" title="Chapter 2. Configuration">Chapter 2, <i xmlns:xlink="http://www.w3.org/1999/xlink"> |
| Configuration |
| </i></a> describes OpenJPA's |
| configuration properties. |
| </p></div></li></ul></div><p> |
| Here is a typical <code class="filename">persistence.xml</code> file for a non-EE |
| environment: |
| </p><div class="example"><a name="jpa_overview_persistence_xmlex"></a><p class="title"><b>Example 6.1. |
| persistence.xml |
| </b></p><div class="example-contents"><pre class="programlisting"> |
| <?xml version="1.0"?> |
| <persistence> |
| <persistence-unit name="openjpa"> |
| <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="openjpa.ConnectionURL" value="jdbc:hsqldb:tutorial_database"/> |
| <property name="openjpa.ConnectionDriverName" value="org.hsqldb.jdbcDriver"/> |
| <property name="openjpa.ConnectionUserName" value="sa"/> |
| <property name="openjpa.ConnectionPassword" value=""/> |
| <property name="openjpa.Log" value="DefaultLevel=WARN, Tool=INFO"/> |
| </properties> |
| </persistence-unit> |
| </persistence> |
| </pre></div></div><br class="example-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jpa_overview_meta_complete.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jpa_overview.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jpa_overview_persistence_use.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. |
| Conclusion |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2. |
| Non-EE Use |
| </td></tr></table></div></body></html> |
