| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <chapter id="jpa_overview_persistence"> |
| <title> |
| Persistence |
| </title> |
| <indexterm zone="jpa_overview_persistence"> |
| <primary> |
| Persistence |
| </primary> |
| </indexterm> |
| <indexterm zone="jpa_overview_persistence"> |
| <primary> |
| EntityManagerFactory |
| </primary> |
| <secondary> |
| construction |
| </secondary> |
| </indexterm> |
| <indexterm zone="jpa_overview_persistence"> |
| <primary> |
| Persistence |
| </primary> |
| <secondary> |
| getEntityManagerFactory |
| </secondary> |
| </indexterm> |
| <indexterm zone="jpa_overview_persistence"> |
| <primary> |
| getEntityManagerFactory |
| </primary> |
| <seealso> |
| Persistence |
| </seealso> |
| </indexterm> |
| <mediaobject> |
| <imageobject> |
| <!-- PNG image data, 427 x 121 (see README) --> |
| <imagedata fileref="img/persistence.png" width="285px"/> |
| </imageobject> |
| </mediaobject> |
| <note> |
| <para> |
| OpenJPA also includes the |
| <ulink url="../javadoc/org/apache/openjpa/persistence/OpenJPAPersistence.html"> |
| <classname>OpenJPAPersistence</classname></ulink> helper class to provide |
| additional utility methods. |
| </para> |
| </note> |
| <para> |
| Within a container, you will typically use <emphasis>injection</emphasis> to |
| access an <classname>EntityManagerFactory</classname>. Applications operating |
| outside of a container, however, can use the |
| <ulink url="http://download.oracle.com/javaee/6/api/javax/persistence/Persistence.html"> |
| <classname>Persistence</classname></ulink> class to obtain <classname> |
| EntityManagerFactory</classname> objects in a vendor-neutral fashion. |
| </para> |
| <programlisting> |
| public static EntityManagerFactory createEntityManagerFactory(String name); |
| public static EntityManagerFactory createEntityManagerFactory(String name, Map props); |
| public static PersistenceUtil getPersistenceUtil(); |
| </programlisting> |
| <para> |
| Each <methodname>createEntityManagerFactory</methodname> method searches the |
| system for an <classname>EntityManagerFactory</classname> definition with the |
| given name. Use <literal>null</literal> for an unnamed factory. The optional map |
| contains vendor-specific property settings used to further configure the |
| factory. |
| </para> |
| <para> |
| <filename>persistence.xml</filename> files define <classname> |
| EntityManagerFactories</classname>. The <methodname>createEntityManagerFactory |
| </methodname> methods search for <filename>persistence.xml</filename> files |
| within the <filename>META-INF</filename> directory of any <literal>CLASSPATH |
| </literal> element. For example, if your <literal>CLASSPATH</literal> contains |
| the <filename>conf</filename> directory, you could place an <classname> |
| EntityManagerFactory</classname> definition in <filename> |
| conf/META-INF/persistence.xml</filename>. |
| </para> |
| <para> |
| The <methodname>getPersistenceUtil</methodname> method returns a PersistenceUtil |
| interface that can be used to determine whether an entity or attribute of an |
| entity is loaded. |
| </para> |
| <programlisting> |
| PersistenceUtil pUtil = Persistence.getPersistenceUtil(); |
| |
| if (!pUtil.isLoaded(myEntity)) { |
| loadEntity(myEntity); |
| } |
| </programlisting> |
| <section id="jpa_overview_persistence_xml"> |
| <title> |
| persistence.xml |
| </title> |
| <para> |
| With the introduction of JPA 2.0, there are two versions of the |
| <filename>persistence.xml</filename>. The most current revision of the |
| 2.0 persistence schema is presented below. Version 1.0 of the persistence |
| schema can be found at |
| <ulink url="http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"/>. |
| </para> |
| <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> |
| </programlisting> |
| <para> |
| The root element of a <filename>persistence.xml</filename> file is <literal> |
| persistence</literal>, which then contains one or more <literal> |
| persistence-unit</literal> definitions. The root element should include the |
| version attribute with the appropriate version, <literal>1.0</literal> for a |
| version 1.0 file and <literal>2.0</literal> 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. |
| </para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| <literal>name</literal>: This is the name you pass to the <methodname> |
| Persistence.createEntityManagerFactory</methodname> methods described above. The |
| name attribute is required. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <literal>transaction-type</literal>: Whether to use managed |
| (<literal>JTA</literal>) or local (<literal>RESOURCE_LOCAL</literal>) |
| transaction management. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <literal>provider</literal>: If you are using a third-party JPA vendor, this |
| element names its implementation of the |
| <ulink url="http://download.oracle.com/javaee/6/api/javax/persistence/spi/PersistenceProvider.html"> |
| <classname>PersistenceProvider</classname></ulink> bootstrapping interface. |
| </para> |
| <note> |
| <para> |
| Set the <literal>provider</literal> to <classname> |
| org.apache.openjpa.persistence.PersistenceProviderImpl</classname> to use |
| OpenJPA. |
| </para> |
| </note> |
| </listitem> |
| <listitem> |
| <para> |
| <literal>jta-data-source</literal>: The JNDI name of a JDBC <classname> |
| DataSource</classname> that is automatically enlisted in JTA transactions. This |
| may be an XA <classname>DataSource</classname>. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <literal>non-jta-data-source</literal>: The JNDI name of a JDBC <classname> |
| DataSource</classname> that is not enlisted in JTA transactions. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <literal>mapping-file</literal>*: The resource names of XML mapping files for |
| entities and embeddable classes. You can also specify mapping information in an |
| <filename>orm.xml</filename> file in your <filename>META-INF</filename> |
| directory. If present, the <filename>orm.xml</filename> mapping file will be |
| read automatically. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <literal>jar-file</literal>*: The names of jar files containing entities and |
| embeddable classes. The implementation will scan the jar for annotated classes. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <literal>class</literal>*: The class names of entities and embeddable classes. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| <literal>properties</literal>: This element contains nested <literal>property |
| </literal> elements used to specify vendor-specific settings. Each <literal> |
| property</literal> has a name attribute and a value attribute. |
| </para> |
| <note> |
| <para> |
| The Reference Guide's <xref linkend="ref_guide_conf"/> describes OpenJPA's |
| configuration properties. |
| </para> |
| </note> |
| </listitem> |
| </itemizedlist> |
| <para> |
| Here is a typical <filename>persistence.xml</filename> file for a non-EE |
| environment: |
| </para> |
| <example id="jpa_overview_persistence_xmlex"> |
| <title> |
| persistence.xml |
| </title> |
| <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> |
| </programlisting> |
| </example> |
| </section> |
| <section id="jpa_overview_persistence_use"> |
| <title> |
| Non-EE Use |
| </title> |
| <para> |
| The example below demonstrates the <classname>Persistence</classname> class in |
| action. You will typically execute code like this on application startup, then |
| cache the resulting factory for future use. This bootstrapping code is only |
| necessary in non-EE environments; in an EE environment <classname> |
| EntityManagerFactories</classname> are typically injected. |
| </para> |
| <example id="jpa_overview_persistence_getemfactory"> |
| <title> |
| Obtaining an EntityManagerFactory |
| </title> |
| <programlisting> |
| // if your persistence.xml file does not contain all settings already, you |
| // can add vendor settings to a map |
| Properties props = new Properties(); |
| ... |
| |
| // create the factory defined by the "openjpa" entity-manager entry |
| EntityManagerFactory emf = Persistence.createEntityManagerFactory("openjpa", props); |
| </programlisting> |
| </example> |
| </section> |
| </chapter> |
