| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Chapter 6. Persistence</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.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" title="Chapter 6. Persistence" id="jpa_overview_persistence"><div class="titlepage"><div><div><h2 class="title">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="d5e1988"></a> |
| <a class="indexterm" name="d5e1990"></a> |
| <a class="indexterm" name="d5e1993"></a> |
| <a class="indexterm" name="d5e1996"></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" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> |
| <p> |
| OpenJPA also includes the |
| <a class="ulink" 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 |
| outside of a container, however, can use the |
| <a class="ulink" href="http://download.oracle.com/javaee/6/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); |
| public static PersistenceUtil getPersistenceUtil(); |
| </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> |
| <p> |
| The <code class="methodname">getPersistenceUtil</code> method returns a PersistenceUtil |
| interface that can be used to determine whether an entity or attribute of an |
| entity is loaded. |
| </p> |
| <pre class="programlisting"> |
| PersistenceUtil pUtil = Persistence.getPersistenceUtil(); |
| |
| if (!pUtil.isLoaded(myEntity)) { |
| loadEntity(myEntity); |
| } |
| </pre> |
| <div class="section" title="1. persistence.xml"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_persistence_xml">1. |
| persistence.xml |
| </h2></div></div></div> |
| |
| <p> |
| With the introduction of JPA 2.0, there are two versions of the |
| <code class="filename">persistence.xml</code>. The most current revision of the |
| 2.0 persistence schema is presented below. Version 1.0 of the persistence |
| schema can be found at |
| <a class="ulink" href="http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" target="_top">http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd</a>. |
| </p> |
| <pre class="programlisting"> |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- persistence.xml schema --> |
| <xsd:schema targetNamespace="http://java.sun.com/xml/ns/persistence" |
| xmlns:xsd="http://www.w3.org/2001/XMLSchema" |
| xmlns:persistence="http://java.sun.com/xml/ns/persistence" |
| elementFormDefault="qualified" attributeFormDefault="unqualified" |
| version="2.0"> |
| |
| <xsd:annotation> |
| <xsd:documentation> |
| @(#)persistence_2_0.xsd 1.0 October 1 2009 |
| </xsd:documentation> |
| </xsd:annotation> |
| |
| <xsd:annotation> |
| <xsd:documentation> |
| |
| DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
| |
| Copyright 2005-2009 Sun Microsystems, Inc. All rights reserved. |
| |
| The contents of this file are subject to the terms of either the |
| GNU General Public License Version 2 only ("GPL") or the Common |
| Development and Distribution License("CDDL") (collectively, the |
| "License"). You may not use this file except in compliance with |
| the License. You can obtain a copy of the License at |
| https://glassfish.dev.java.net/public/CDDL+GPL.html or |
| glassfish/bootstrap/legal/LICENSE.txt. See the License for the |
| specific language governing permissions and limitations under the |
| License. |
| |
| When distributing the software, include this License Header |
| Notice in each file and include the License file at |
| glassfish/bootstrap/legal/LICENSE.txt. Sun designates this |
| particular file as subject to the "Classpath" exception as |
| provided by Sun in the GPL Version 2 section of the License file |
| that accompanied this code. If applicable, add the following |
| below the License Header, with the fields enclosed by brackets [] |
| replaced by your own identifying information: |
| "Portions Copyrighted [year] [name of copyright owner]" |
| |
| Contributor(s): |
| |
| If you wish your version of this file to be governed by only the |
| CDDL or only the GPL Version 2, indicate your decision by adding |
| "[Contributor] elects to include this software in this |
| distribution under the [CDDL or GPL Version 2] license." If you |
| don't indicate a single choice of license, a recipient has the |
| option to distribute your version of this file under either the |
| CDDL, the GPL Version 2 or to extend the choice of license to its |
| licensees as provided above. However, if you add GPL Version 2 |
| code and therefore, elected the GPL Version 2 license, then the |
| option applies only if the new code is made subject to such |
| option by the copyright holder. |
| |
| </xsd:documentation> |
| </xsd:annotation> |
| |
| <xsd:annotation> |
| <xsd:documentation> |
| <![CDATA[ |
| This is the XML Schema for the persistence configuration file. |
| The file must be named "META-INF/persistence.xml" in the |
| persistence archive. |
| Persistence configuration files must indicate |
| the persistence schema by using the persistence namespace: |
| http://java.sun.com/xml/ns/persistence |
| and indicate the version of the schema by |
| using the version element as shown below: |
| <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> |
| ]]> |
| </xsd:documentation> |
| </xsd:annotation> |
| |
| <xsd:simpleType name="versionType"> |
| <xsd:restriction base="xsd:token"> |
| <xsd:pattern value="[0-9]+(\.[0-9]+)*" /> |
| </xsd:restriction> |
| </xsd:simpleType> |
| <!-- **************************************************** --> |
| <xsd:element name="persistence"> |
| <xsd:complexType> |
| <xsd:sequence> |
| <!-- **************************************************** --> |
| <xsd:element name="persistence-unit" |
| minOccurs="1" maxOccurs="unbounded"> |
| <xsd:complexType> |
| <xsd:annotation> |
| <xsd:documentation> |
| Configuration of a persistence unit. |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:sequence> |
| <!-- **************************************************** --> |
| <xsd:element name="description" |
| type="xsd:string" minOccurs="0"> |
| <xsd:annotation> |
| <xsd:documentation> |
| Description of this persistence unit. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:element> |
| <!-- **************************************************** --> |
| <xsd:element name="provider" |
| type="xsd:string" minOccurs="0"> |
| <xsd:annotation> |
| <xsd:documentation> |
| Provider class that supplies EntityManagers for this |
| persistence unit. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:element> |
| <!-- **************************************************** --> |
| <xsd:element name="jta-data-source" |
| type="xsd:string" minOccurs="0"> |
| <xsd:annotation> |
| <xsd:documentation> |
| The container-specific name of the JTA datasource to use. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:element> |
| <!-- **************************************************** --> |
| <xsd:element name="non-jta-data-source" |
| type="xsd:string" minOccurs="0"> |
| <xsd:annotation> |
| <xsd:documentation> |
| The container-specific name of a non-JTA datasource to use. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:element> |
| <!-- **************************************************** --> |
| <xsd:element name="mapping-file" |
| type="xsd:string" minOccurs="0" |
| maxOccurs="unbounded"> |
| <xsd:annotation> |
| <xsd:documentation> |
| File containing mapping information. Loaded as a resource |
| by the persistence provider. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:element> |
| <!-- **************************************************** --> |
| <xsd:element name="jar-file" |
| type="xsd:string" minOccurs="0" |
| maxOccurs="unbounded"> |
| <xsd:annotation> |
| <xsd:documentation> |
| Jar file that is to be scanned for managed classes. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:element> |
| <!-- **************************************************** --> |
| <xsd:element name="class" type="xsd:string" |
| minOccurs="0" maxOccurs="unbounded"> |
| <xsd:annotation> |
| <xsd:documentation> |
| Managed class to be included in the persistence unit and |
| to scan for annotations. It should be annotated |
| with either @Entity, @Embeddable or @MappedSuperclass. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:element> |
| <!-- **************************************************** --> |
| <xsd:element name="exclude-unlisted-classes" |
| type="xsd:boolean" default="true" |
| minOccurs="0"> |
| <xsd:annotation> |
| <xsd:documentation> |
| When set to true then only listed classes and jars will |
| be scanned for persistent classes, otherwise the |
| enclosing jar or directory will also be scanned. |
| Not applicable to Java SE persistence units. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:element> |
| <!-- **************************************************** --> |
| <xsd:element name="shared-cache-mode" |
| type="persistence:persistence-unit-caching-type" |
| minOccurs="0"> |
| <xsd:annotation> |
| <xsd:documentation> |
| Defines whether caching is enabled for the |
| persistence unit if caching is supported by the |
| persistence provider. When set to ALL, all entities |
| will be cached. When set to NONE, no entities will |
| be cached. When set to ENABLE_SELECTIVE, only entities |
| specified as cacheable will be cached. When set to |
| DISABLE_SELECTIVE, entities specified as not cacheable |
| will not be cached. When not specified or when set to |
| UNSPECIFIED, provider defaults may apply. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:element> |
| <!-- **************************************************** --> |
| <xsd:element name="validation-mode" |
| type="persistence:persistence-unit-validation-mode-type" |
| minOccurs="0"> |
| <xsd:annotation> |
| <xsd:documentation> |
| The validation mode to be used for the persistence unit. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:element> |
| <!-- **************************************************** --> |
| <xsd:element name="properties" |
| minOccurs="0"> |
| <xsd:annotation> |
| <xsd:documentation> |
| A list of standard and vendor-specific properties |
| and hints. |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:complexType> |
| <xsd:sequence> |
| <xsd:element name="property" |
| minOccurs="0" maxOccurs="unbounded"> |
| <xsd:annotation> |
| <xsd:documentation> |
| A name-value pair. |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:complexType> |
| <xsd:attribute |
| name="name" type="xsd:string" |
| use="required" /> |
| <xsd:attribute |
| name="value" type="xsd:string" |
| use="required" /> |
| </xsd:complexType> |
| </xsd:element> |
| </xsd:sequence> |
| </xsd:complexType> |
| </xsd:element> |
| </xsd:sequence> |
| <!-- **************************************************** --> |
| <xsd:attribute name="name" type="xsd:string" |
| use="required"> |
| <xsd:annotation> |
| <xsd:documentation> |
| Name used in code to reference this persistence unit. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:attribute> |
| <!-- **************************************************** --> |
| <xsd:attribute name="transaction-type" |
| type="persistence:persistence-unit-transaction-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| Type of transactions used by EntityManagers from this |
| persistence unit. |
| </xsd:documentation> |
| </xsd:annotation> |
| </xsd:attribute> |
| </xsd:complexType> |
| </xsd:element> |
| </xsd:sequence> |
| <xsd:attribute name="version" type="persistence:versionType" |
| fixed="2.0" use="required" /> |
| </xsd:complexType> |
| </xsd:element> |
| <!-- **************************************************** --> |
| <xsd:simpleType name="persistence-unit-transaction-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| public enum PersistenceUnitTransactionType {JTA, RESOURCE_LOCAL}; |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:token"> |
| <xsd:enumeration value="JTA" /> |
| <xsd:enumeration value="RESOURCE_LOCAL" /> |
| </xsd:restriction> |
| </xsd:simpleType> |
| <!-- **************************************************** --> |
| <xsd:simpleType name="persistence-unit-caching-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| public enum SharedCacheMode { ALL, NONE, ENABLE_SELECTIVE, |
| DISABLE_SELECTIVE, UNSPECIFIED}; |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:token"> |
| <xsd:enumeration value="ALL" /> |
| <xsd:enumeration value="NONE" /> |
| <xsd:enumeration value="ENABLE_SELECTIVE" /> |
| <xsd:enumeration value="DISABLE_SELECTIVE" /> |
| <xsd:enumeration value="UNSPECIFIED" /> |
| </xsd:restriction> |
| </xsd:simpleType> |
| <!-- **************************************************** --> |
| <xsd:simpleType name="persistence-unit-validation-mode-type"> |
| <xsd:annotation> |
| <xsd:documentation> |
| public enum ValidationMode { AUTO, CALLBACK, NONE}; |
| </xsd:documentation> |
| </xsd:annotation> |
| <xsd:restriction base="xsd:token"> |
| <xsd:enumeration value="AUTO" /> |
| <xsd:enumeration value="CALLBACK" /> |
| <xsd:enumeration value="NONE" /> |
| </xsd:restriction> |
| </xsd:simpleType> |
| </xsd:schema> |
| </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. The root element should include the |
| version attribute with the appropriate version, <code class="literal">1.0</code> for a |
| version 1.0 file and <code class="literal">2.0</code> for a version 2.0 file. 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 attributes. |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> |
| <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 class="listitem"> |
| <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 class="listitem"> |
| <p> |
| <code class="literal">provider</code>: If you are using a third-party JPA vendor, this |
| element names its implementation of the |
| <a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/spi/PersistenceProvider.html" target="_top"> |
| <code class="classname">PersistenceProvider</code></a> bootstrapping interface. |
| </p> |
| <div class="note" title="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 class="listitem"> |
| <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 class="listitem"> |
| <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 class="listitem"> |
| <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 class="listitem"> |
| <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 class="listitem"> |
| <p> |
| <code class="literal">class</code>*: The class names of entities and embeddable classes. |
| </p> |
| </li><li class="listitem"> |
| <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" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> |
| <p> |
| The Reference Guide's <a class="xref" href="ref_guide_conf.html" title="Chapter 2. Configuration">Chapter 2, <i> |
| 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 version="1.0"> |
| <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> |
