Apache OpenJPA is released under the Apache Software License Version 2.0

Apache OpenJPA includes the persistence and orm schemas from the JPA specifications and elects to include this software in this distribution under the CDDL license.

Apache OpenJPA includes software developed by the SERP project, which uses the BSD license

This product includes software developed by The Apache Software Foundation (http://www.apache.org/).

The openjpa-all aggregate JAR includes software developed by the:

This document is intended for developers who want to learn about JPA in order to use it in their applications. It assumes that you have a strong knowledge of object-oriented concepts and Java, including annotations and generics. It also assumes some experience with relational databases and the Structured Query Language (SQL).

Persistent data is information that can outlive the program that creates it. The majority of complex programs use persistent data: GUI applications need to store user preferences across program invocations, web applications track user movements and orders over long periods of time, etc.

Lightweight persistence is the storage and retrieval of persistent data with little or no work from you, the developer. For example, Java serialization is a form of lightweight persistence because it can be used to persist Java objects directly to a file with very little effort. Serialization's capabilities as a lightweight persistence mechanism pale in comparison to those provided by JPA, however. The next chapter compares JPA to serialization and other available persistence mechanisms.

The diagram above depicts the JPA exception architecture. All exceptions are unchecked. JPA uses standard exceptions where appropriate, most notably IllegalArgumentExceptions and IllegalStateExceptions. The specification also provides a few JPA-specific exceptions in the javax.persistence package. These exceptions should be self-explanatory. See the Javadoc for additional details on JPA exceptions.

There are very few restrictions placed on persistent classes. Still, it never hurts to familiarize yourself with exactly what JPA does and does not support.

Java recognizes two forms of object identity: numeric identity and qualitative identity. If two references are numerically identical, then they refer to the same JVM instance in memory. You can test for this using the == operator. Qualitative identity, on the other hand, relies on some user-defined criteria to determine whether two objects are "equal". You test for qualitative identity using the equals method. By default, this method simply relies on numeric identity.

JPA introduces another form of object identity, called entity identity or persistent identity. Entity identity tests whether two persistent objects represent the same state in the datastore.

The entity identity of each persistent instance is encapsulated in its identity field(s). If two entities of the same type have the same identity field values, then the two entities represent the same state in the datastore. Each entity's identity field values must be unique among all other entities of the same type.

Identity fields must be primitives, primitive wrappers, Strings, Dates, Timestamps, or embeddable types.

If you are dealing with a single persistence context (see Section 3, “ Persistence Context ”), then you do not have to compare identity fields to test whether two entity references represent the same state in the datastore. There is a much easier way: the == operator. JPA requires that each persistence context maintain only one JVM object to represent each unique datastore record. Thus, entity identity is equivalent to numeric identity within a persistence context. This is referred to as the uniqueness requirement.

The uniqueness requirement is extremely important - without it, it would be impossible to maintain data integrity. Think of what could happen if two different objects in the same transaction were allowed to represent the same persistent data. If you made different modifications to each of these objects, which set of changes should be written to the datastore? How would your application logic handle seeing two different "versions" of the same data? Thanks to the uniqueness requirement, these questions do not have to be answered.

2.1.  Identity Class

2.1.1. Identity Hierarchies

If your entity has only one identity field, you can use the value of that field as the entity's identity object in all EntityManager APIs. Otherwise, you must supply an identity class to use for identity objects. Your identity class must meet the following criteria:

• The class must be public.

• The class must be serializable.

• The class must have a public no-args constructor.

• The names of the non-static fields or properties of the class must be the same as the names of the identity fields or properties of the corresponding entity class, and the types must be identical.

• The equals and hashCode methods of the class must use the values of all fields or properties corresponding to identity fields or properties in the entity class.

• If the class is an inner class, it must be static.

• All entity classes related by inheritance must use the same identity class, or else each entity class must have its own identity class whose inheritance hierarchy mirrors the inheritance hierarchy of the owning entity classes (see Section 2.1.1, “ Identity Hierarchies ”).

Note

Though you may still create identity classes by hand, OpenJPA provides the appidtool to automatically generate proper identity classes based on your identity fields. See Section 4.3, “ Application Identity Tool ” of the Reference Guide.

Example 4.2.  Identity Class

This example illustrates a proper identity class for an entity with multiple identity fields.

/**
 * Persistent class using application identity.
 */
public class Magazine {

    private String isbn;    // identity field
    private String title;   // identity field

    // rest of fields and methods omitted


    /**
     * Application identity class for Magazine.
     */
    public static class MagazineId {

        // each identity field in the Magazine class must have a
        // corresponding field in the identity class
        public String isbn;
        public String title;

        /**
         * Equality must be implemented in terms of identity field
         * equality, and must use instanceof rather than comparing 
         * classes directly (some JPA implementations may subclass the
         * identity class).
         */
        public boolean equals(Object other) {
            if (other == this)
                return true;
            if (!(other instanceof MagazineId))
                return false;
    
            MagazineId mi = (MagazineId) other;
            return (isbn == mi.isbn
                || (isbn != null && isbn.equals(mi.isbn)))
                && (title == mi.title
                || (title != null && title.equals(mi.title)));
        }
     
        /**
         * Hashcode must also depend on identity values.
         */
        public int hashCode() {
            return ((isbn == null) ? 0 : isbn.hashCode())
                ^ ((title == null) ? 0 : title.hashCode());
        } 

        public String toString() {
            return isbn + ":" + title;
        }
    }
}

2.1.1.  Identity Hierarchies

An alternative to having a single identity class for an entire inheritance hierarchy is to have one identity class per level in the inheritance hierarchy. The requirements for using a hierarchy of identity classes are as follows:

• The inheritance hierarchy of identity classes must exactly mirror the hierarchy of the persistent classes that they identify. In the example pictured above, abstract class Person is extended by abstract class Employee, which is extended by non-abstract class FullTimeEmployee, which is extended by non-abstract class Manager. The corresponding identity classes, then, are an abstract PersonId class, extended by an abstract EmployeeId class, extended by a non-abstract FullTimeEmployeeId class, extended by a non-abstract ManagerId class.

• Subclasses in the identity hierarchy may define additional identity fields until the hierarchy becomes non-abstract. In the aforementioned example, Person defines an identity field ssn, Employee defines additional identity field userName , and FullTimeEmployee adds a final identity field, empId. However, Manager may not define any additional identity fields, since it is a subclass of a non-abstract class. The hierarchy of identity classes, of course, must match the identity field definitions of the persistent class hierarchy.

• It is not necessary for each abstract class to declare identity fields. In the previous example, the abstract Person and Employee classes could declare no identity fields, and the first concrete subclass FullTimeEmployee could define one or more identity fields.

• All subclasses of a concrete identity class must be equals and hashCode-compatible with the concrete superclass. This means that in our example, a ManagerId instance and a FullTimeEmployeeId instance with the same identity field values should have the same hash code, and should compare equal to each other using the equals method of either one. In practice, this requirement reduces to the following coding practices:

  1. Use instanceof instead of comparing Class objects in the equals methods of your identity classes.

  2. An identity class that extends another non-abstract identity class should not override equals or hashCode.

It is often necessary to perform various actions at different stages of a persistent object's lifecycle. JPA includes a variety of callbacks methods for monitoring changes in the lifecycle of your persistent objects. These callbacks can be defined on the persistent classes themselves and on non-persistent listener classes.

/**
 * Example persistent class declaring our entity listener.
 */
@Entity
public class Magazine {

    @Transient 
    private byte[][] data;

    @ManyToMany
    private List<Photo> photos;

    @PostLoad
    public void convertPhotos() {
        data = new byte[photos.size()][];
        for (int i = 0; i < photos.size(); i++)
            data[i] = photos.get(i).toByteArray();
    }

    @PreDelete
    public void logMagazineDeletion() {
        getLog().debug("deleting magazine containing" + photos.size() 
            + " photos.");
    }
}

<entity class="Magazine">
    <pre-remove>logMagazineDeletion</pre-remove>
    <post-load>convertPhotos</post-load>
</entity>

/**
 * Example persistent class declaring our entity listener.
 */
@Entity
@EntityListeners({ MagazineLogger.class, ... })
public class Magazine {

    // ... //
}


/**
 * Example entity listener.
 */
public class MagazineLogger {

    @PostPersist
    public void logAddition(Object pc) {
        getLog().debug("Added new magazine:" + ((Magazine) pc).getTitle());
    }


    @PreRemove
    public void logDeletion(Object pc) {
        getLog().debug("Removing from circulation:" + 
            ((Magazine) pc).getTitle());
    }
}

<entity class="Magazine">
    <entity-listeners>
        <entity-listener class="MagazineLogger">
            <post-persist>logAddition</post-persist>
            <pre-remove>logDeletion</pre-remove>
        </entity-listener>
    </entity-listeners>
</entity>

This chapter covered everything you need to know to write persistent class definitions in JPA. JPA cannot use your persistent classes, however, until you complete one additional step: you must define the persistence metadata. The next chapter explores metadata in detail.

The following metadata annotations and XML elements apply to persistent class declarations.

package org.mag;

@Entity
@IdClass(Magazine.MagazineId.class)
public class Magazine {
    ...

    public static class MagazineId {
        ...
    }
}

@Entity
public class Article {
    ...
}


package org.mag.pub;

@Entity
public class Company {
    ...
}

@Entity
public class Author {
    ...
}

@Embeddable
public class Address {
    ...
}


package org.mag.subscribe;

@MappedSuperclass
public abstract class Document {
    ...
}

@Entity
public class Contract
    extends Document {
    ...
}

@Entity
public class Subscription {
    ...

    @Entity
    public static class LineItem
        extends Contract {
        ...
    }
}

@Entity(name="Lifetime")
public class LifetimeSubscription
    extends Subscription {
    ...
}

@Entity(name="Trial")
public class TrialSubscription
    extends Subscription {
    ...
}

<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
    version="1.0">
    <mapped-superclass class="org.mag.subscribe.Document">
        ...
    </mapped-superclass>
    <entity class="org.mag.Magazine">
        <id-class class="org.mag.Magazine$MagazineId"/>
        ...
    </entity>
    <entity class="org.mag.Article">
        ...
    </entity>
    <entity class="org.mag.pub.Company">
        ...
    </entity>
    <entity class="org.mag.pub.Author">
        ...
    </entity>
    <entity class="org.mag.subscribe.Contract">
        ...
    </entity>
    <entity class="org.mag.subscribe.LineItem">
        ...
    </entity>
    <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime">
        ...
    </entity>
    <entity class="org.mag.subscribe.TrialSubscription" name="Trial">
        ...
    </entity>
    <embeddable class="org.mag.pub.Address">
        ...
    </embeddable>
</entity-mappings>

The persistence implementation must be able to retrieve and set the persistent state of your entities, mapped superclasses, and embeddable types. JPA offers two modes of persistent state access: field access, and property access. The access type of a persistent attribute can be either set explicitly on a class or attribute level, inherited, or determined by the provider.

Under field access, the implementation injects state directly into your persistent fields, and retrieves changed state from your fields as well. To declare field access on an entire entity with XML metadata, set the access attribute of your entity XML element to FIELD. To use field access for an entire entity using annotation metadata, simply place your metadata and mapping annotations on your field declarations:

@ManyToOne
private Company publisher;

Property access, on the other hand, retrieves and loads state through JavaBean "getter" and "setter" methods. For a property p of type T, you must define the following getter method:

T getP();

For boolean properties, this is also acceptable:

boolean isP();

You must also define the following setter method:

void setP(T value);

To implicitly use property access for an entire class by default, set your entity element's access attribute to PROPERTY, or place your metadata and mapping annotations on the getter method:

@ManyToOne
private Company getPublisher() { ... }

private void setPublisher(Company publisher) { ... }

@Entity
@Access(AccessType.FIELD)
public class PaymentContract {

    @Id
    private String id;

    @Temporal(TemporalType.DATE)
    private String contractDate;
    
    @Transient
    private String terms;
    
    @Version
    private int version;
    
    @Lob
    @Access(AccessType.PROPERTY)
    public String getContractTerms() {
        return terms;
    }
    
    public void setContractTerms(String terms) {
        // Format string before persisting
        this.terms = formatTerms(terms);
    }
    ... 
}

<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_2_0.xsd"
    version="2.0">
    <entity class="org.xyz.PaymentContract" access="FIELD">
        <attributes>
            <id name="id"/>
             <basic name="contractTerms" access="PROPERTY"> 
                <lob/>
            </basic>
            <basic name="contractDate">
                <temporal>DATE</temporal>
            </basic>
            <version name="version"/>
            <transient name="terms"/>
       </attributes>
    </entity>
</entity-mappings>

The remainder of this document uses the term "persistent field" to refer to either a persistent field or a persistent property.

@ManyToOne(cascade={CascadeType.PERSIST,CascadeType.REMOVE,
    CascadeType.REFRESH,CascadeType.MERGE})
private Company publisher;

@ManyToOne(cascade=CascadeType.ALL)
private Company publisher;

<many-to-one name="publisher">
    <cascade>
        <cascade-persist/>
        <cascade-merge/>
        <cascade-remove/>
        <cascade-refresh/>
    </cascade>
</many-to-one>

<many-to-one name="publisher">
    <cascade>
        <cascade-all/>
    </cascade>
</many-to-one>

<field name>[ ASC|DESC][, ...]

The latest revision of the version 2.0 orm schema is presented below. Version 2.0 of the schema must be used if JPA 2.0 elements are specified as XML metadata. Many of the elements in the schema relate to object/relational mapping rather than metadata; these elements are discussed in Chapter 13, Mapping Metadata . Version 1.0 of the orm schema can be found at http://java.sun.com/xml/ns/persistence/orm_1_0.xsd.

<?xml version="1.0" encoding="UTF-8"?>
    <!-- Java Persistence API object/relational mapping file schema -->
<xsd:schema targetNamespace="http://java.sun.com/xml/ns/persistence/orm"
    xmlns:orm="http://java.sun.com/xml/ns/persistence/orm" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified" attributeFormDefault="unqualified"
    version="2.0">

    <xsd:annotation>
        <xsd:documentation>
            @(#)orm_2_0.xsd 2.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 object/relational
            mapping file.
            The file may be named "META-INF/orm.xml" in the persistence
            archive or it may be named some other name which would be
            used to locate the file as resource on the classpath.
            Object/relational mapping files must indicate the object/relational
            mapping file 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:
            <entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm
            http://java.sun.com/xml/ns/persistence/orm/orm_2_0.xsd"
            version="2.0">
            ...
            </entity-mappings>
        ]]>
        </xsd:documentation>
    </xsd:annotation>

    <xsd:complexType name="emptyType" />
    <xsd:simpleType name="versionType">
        <xsd:restriction base="xsd:token">
            <xsd:pattern value="[0-9]+(\.[0-9]+)*" />
        </xsd:restriction>
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:element name="entity-mappings">
        <xsd:complexType>
            <xsd:annotation>
                <xsd:documentation>
                    The entity-mappings element is the root element of a mapping
                    file. It contains the following four types of elements:
                    1. The persistence-unit-metadata element contains metadata
                    for the entire persistence unit. It is undefined if this element
                    occurs in multiple mapping files within the same
                    persistence unit.
                    2. The package, schema, catalog and access elements apply to all of
                    the entity, mapped-superclass and embeddable
                    elements defined in
                    the same file in which they occur.
                    3. The sequence-generator, table-generator, named-query,
                    named-native-query and sql-result-set-mapping
                    elements are global
                    to the persistence unit. It is undefined to have more than one
                    sequence-generator or table-generator of the same
                    name in the same
                    or different mapping files in a persistence unit. It is also
                    undefined to have more than one named-query,
                    named-native-query, or
                    result-set-mapping of the same name in the same or different mapping
                    files in a persistence unit.
                    4. The entity, mapped-superclass and embeddable elements each define
                    the mapping information for a managed persistent
                    class. The mapping
                    information contained in these elements may be complete or it may
                    be partial.
                </xsd:documentation>
            </xsd:annotation>
            <xsd:sequence>
                <xsd:element name="description" type="xsd:string"
                    minOccurs="0" />
                <xsd:element name="persistence-unit-metadata"
                    type="orm:persistence-unit-metadata" minOccurs="0" />
                <xsd:element name="package" type="xsd:string"
                    minOccurs="0" />
                <xsd:element name="schema" type="xsd:string"
                    minOccurs="0" />
                <xsd:element name="catalog" type="xsd:string"
                    minOccurs="0" />
                <xsd:element name="access" type="orm:access-type"
                    minOccurs="0" />
                <xsd:element name="sequence-generator" type="orm:sequence-generator"
                    minOccurs="0" maxOccurs="unbounded" />
                <xsd:element name="table-generator" type="orm:table-generator"
                    minOccurs="0" maxOccurs="unbounded" />
                <xsd:element name="named-query" type="orm:named-query"
                    minOccurs="0" maxOccurs="unbounded" />
                <xsd:element name="named-native-query" type="orm:named-native-query"
                    minOccurs="0" maxOccurs="unbounded" />
                <xsd:element name="sql-result-set-mapping"
                    type="orm:sql-result-set-mapping" minOccurs="0"
                    maxOccurs="unbounded" />
                <xsd:element name="mapped-superclass" type="orm:mapped-superclass"
                    minOccurs="0" maxOccurs="unbounded" />
                <xsd:element name="entity" type="orm:entity"
                    minOccurs="0" maxOccurs="unbounded" />
                <xsd:element name="embeddable" type="orm:embeddable"
                    minOccurs="0" maxOccurs="unbounded" />
            </xsd:sequence>
            <xsd:attribute name="version" type="orm:versionType"
                fixed="2.0" use="required" />
        </xsd:complexType>
    </xsd:element>
    <!-- **************************************************** -->
    <xsd:complexType name="persistence-unit-metadata">
        <xsd:annotation>
            <xsd:documentation>
                Metadata that applies to the persistence unit and not just to
                the mapping file in which it is contained.
                If the xml-mapping-metadata-complete element is specified,
                the complete set of mapping metadata for the persistence unit
                is contained in the XML mapping files for the persistence unit.
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="xml-mapping-metadata-complete"
                type="orm:emptyType" minOccurs="0" />
            <xsd:element name="persistence-unit-defaults"
                type="orm:persistence-unit-defaults" minOccurs="0" />
        </xsd:sequence>
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="persistence-unit-defaults">
        <xsd:annotation>
            <xsd:documentation>
                These defaults are applied to the persistence unit as a whole
                unless they are overridden by local annotation or XML
                element settings.
                schema - Used as the schema for all tables, secondary tables, join
                tables, collection tables, sequence generators, and table
                generators that apply to the persistence unit
                catalog - Used as the catalog for all tables, secondary tables, join
                tables, collection tables, sequence generators, and
                table generators that apply to the persistence unit
                delimited-identifiers - Used to treat database identifiers as
                delimited identifiers.
                access - Used as the access type for all managed classes in
                the persistence unit
                cascade-persist - Adds cascade-persist to the set of cascade options
                in all entity relationships of the persistence unit
                entity-listeners - List of default entity listeners to be invoked
                on each entity in the persistence unit.
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="schema" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="catalog" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="delimited-identifiers" type="orm:emptyType"
                minOccurs="0" />
            <xsd:element name="access" type="orm:access-type"
                minOccurs="0" />
            <xsd:element name="cascade-persist" type="orm:emptyType"
                minOccurs="0" />
            <xsd:element name="entity-listeners" type="orm:entity-listeners"
                minOccurs="0" />
        </xsd:sequence>
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="entity">
        <xsd:annotation>
            <xsd:documentation>
                Defines the settings and mappings for an entity. Is allowed to be
                sparsely populated and used in conjunction with the annotations.
                Alternatively, the metadata-complete attribute can be
                used to
                indicate that no annotations on the entity class (and its fields
                or properties) are to be processed. If this is the case then
                the defaulting rules for the entity and its subelements will
                be recursively applied.
                @Target(TYPE) @Retention(RUNTIME)
                public @interface Entity {
                String name() default "";
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="table" type="orm:table"
                minOccurs="0" />
            <xsd:element name="secondary-table" type="orm:secondary-table"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="primary-key-join-column"
                type="orm:primary-key-join-column" minOccurs="0"
                maxOccurs="unbounded" />
            <xsd:element name="id-class" type="orm:id-class"
                minOccurs="0" />
            <xsd:element name="inheritance" type="orm:inheritance"
                minOccurs="0" />
            <xsd:element name="discriminator-value" type="orm:discriminator-value"
                minOccurs="0" />
            <xsd:element name="discriminator-column" type="orm:discriminator-column"
                minOccurs="0" />
            <xsd:element name="sequence-generator" type="orm:sequence-generator"
                minOccurs="0" />
            <xsd:element name="table-generator" type="orm:table-generator"
                minOccurs="0" />
            <xsd:element name="named-query" type="orm:named-query"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="named-native-query" type="orm:named-native-query"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="sql-result-set-mapping" type="orm:sql-result-set-mapping"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="exclude-default-listeners"
                type="orm:emptyType" minOccurs="0" />
            <xsd:element name="exclude-superclass-listeners"
                type="orm:emptyType" minOccurs="0" />
            <xsd:element name="entity-listeners" type="orm:entity-listeners"
                minOccurs="0" />
            <xsd:element name="pre-persist" type="orm:pre-persist"
                minOccurs="0" />
            <xsd:element name="post-persist" type="orm:post-persist"
                minOccurs="0" />
            <xsd:element name="pre-remove" type="orm:pre-remove"
                minOccurs="0" />
            <xsd:element name="post-remove" type="orm:post-remove"
                minOccurs="0" />
            <xsd:element name="pre-update" type="orm:pre-update"
                minOccurs="0" />
            <xsd:element name="post-update" type="orm:post-update"
                minOccurs="0" />
            <xsd:element name="post-load" type="orm:post-load"
                minOccurs="0" />
            <xsd:element name="attribute-override" type="orm:attribute-override"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="association-override" type="orm:association-override"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="attributes" type="orm:attributes"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" />
        <xsd:attribute name="class" type="xsd:string" use="required" />
        <xsd:attribute name="access" type="orm:access-type" />
        <xsd:attribute name="cacheable" type="xsd:boolean" />
        <xsd:attribute name="metadata-complete" type="xsd:boolean" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:simpleType name="access-type">
        <xsd:annotation>
            <xsd:documentation>
                This element determines how the persistence provider accesses the
                state of an entity or embedded object.
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="xsd:token">
            <xsd:enumeration value="PROPERTY" />
            <xsd:enumeration value="FIELD" />
        </xsd:restriction>
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:complexType name="association-override">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
                public @interface AssociationOverride {
                String name();
                JoinColumn[] joinColumns() default{};
                JoinTable joinTable() default @JoinTable;
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string" minOccurs="0" />
            <xsd:choice>
                <xsd:element name="join-column" type="orm:join-column"
                    minOccurs="0" maxOccurs="unbounded" />
                <xsd:element name="join-table" type="orm:join-table"
                    minOccurs="0" />
            </xsd:choice>
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="attribute-override">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
                public @interface AttributeOverride {
                String name();
                Column column();
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="column" type="orm:column" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="attributes">
        <xsd:annotation>
            <xsd:documentation>
                This element contains the entity field or property mappings.
                It may be sparsely populated to include only a subset of the
                fields or properties. If metadata-complete for the entity is true
                then the remainder of the attributes will be defaulted according
                to the default rules.
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:choice>
                <xsd:element name="id" type="orm:id"
                    minOccurs="0" maxOccurs="unbounded" />
                <xsd:element name="embedded-id" type="orm:embedded-id"
                    minOccurs="0" />
            </xsd:choice>
            <xsd:element name="basic" type="orm:basic"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="version" type="orm:version"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="many-to-one" type="orm:many-to-one"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="one-to-many" type="orm:one-to-many"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="one-to-one" type="orm:one-to-one"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="many-to-many" type="orm:many-to-many"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="element-collection" type="orm:element-collection"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="embedded" type="orm:embedded"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="transient" type="orm:transient"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="basic">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface Basic {
                FetchType fetch() default EAGER;
                boolean optional() default true;
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="column" type="orm:column"
                minOccurs="0" />
            <xsd:choice>
                <xsd:element name="lob" type="orm:lob"
                    minOccurs="0" />
                <xsd:element name="temporal" type="orm:temporal"
                    minOccurs="0" />
                <xsd:element name="enumerated" type="orm:enumerated"
                    minOccurs="0" />
            </xsd:choice>
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="fetch" type="orm:fetch-type" />
        <xsd:attribute name="optional" type="xsd:boolean" />
        <xsd:attribute name="access" type="orm:access-type" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="cascade-type">
        <xsd:annotation>
            <xsd:documentation>
                public enum CascadeType { ALL, PERSIST, MERGE, REMOVE, REFRESH,
                DETACH};
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="cascade-all" type="orm:emptyType"
                minOccurs="0" />
            <xsd:element name="cascade-persist" type="orm:emptyType"
                minOccurs="0" />
            <xsd:element name="cascade-merge" type="orm:emptyType"
                minOccurs="0" />
            <xsd:element name="cascade-remove" type="orm:emptyType"
                minOccurs="0" />
            <xsd:element name="cascade-refresh" type="orm:emptyType"
                minOccurs="0" />
            <xsd:element name="cascade-detach" type="orm:emptyType"
                minOccurs="0" />
        </xsd:sequence>
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="collection-table">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface CollectionTable {
                String name() default "";
                String catalog() default "";
                String schema() default "";
                JoinColumn[] joinColumns() default {};
                UniqueConstraint[] uniqueConstraints() default {};
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="join-column" type="orm:join-column"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="unique-constraint" type="orm:unique-constraint"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" />
        <xsd:attribute name="catalog" type="xsd:string" />
        <xsd:attribute name="schema" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="column">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface Column {
                String name() default "";
                boolean unique() default false;
                boolean nullable() default true;
                boolean insertable() default true;
                boolean updatable() default true;
                String columnDefinition() default "";
                String table() default "";
                int length() default 255;
                int precision() default 0; // decimal precision
                int scale() default 0; // decimal scale
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="name" type="xsd:string" />
        <xsd:attribute name="unique" type="xsd:boolean" />
        <xsd:attribute name="nullable" type="xsd:boolean" />
        <xsd:attribute name="insertable" type="xsd:boolean" />
        <xsd:attribute name="updatable" type="xsd:boolean" />
        <xsd:attribute name="column-definition" type="xsd:string" />
        <xsd:attribute name="table" type="xsd:string" />
        <xsd:attribute name="length" type="xsd:int" />
        <xsd:attribute name="precision" type="xsd:int" />
        <xsd:attribute name="scale" type="xsd:int" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="column-result">
        <xsd:annotation>
            <xsd:documentation>
                @Target({}) @Retention(RUNTIME)
                public @interface ColumnResult {
                String name();
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="name" type="xsd:string" use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="discriminator-column">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE}) @Retention(RUNTIME)
                public @interface DiscriminatorColumn {
                String name() default "DTYPE";
                DiscriminatorType discriminatorType() default STRING;
                String columnDefinition() default "";
                int length() default 31;
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="name" type="xsd:string" />
        <xsd:attribute name="discriminator-type" type="orm:discriminator-type" />
        <xsd:attribute name="column-definition" type="xsd:string" />
        <xsd:attribute name="length" type="xsd:int" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:simpleType name="discriminator-type">
        <xsd:annotation>
            <xsd:documentation>
                public enum DiscriminatorType { STRING, CHAR, INTEGER };
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="xsd:token">
            <xsd:enumeration value="STRING" />
            <xsd:enumeration value="CHAR" />
            <xsd:enumeration value="INTEGER" />
        </xsd:restriction>
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:simpleType name="discriminator-value">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE}) @Retention(RUNTIME)
                public @interface DiscriminatorValue {
                String value();
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="xsd:string" />
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:complexType name="element-collection">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface ElementCollection {
                Class targetClass() default void.class;
                FetchType fetch() default LAZY;
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:choice>
                <xsd:element name="order-by" type="orm:order-by"
                    minOccurs="0" />
                <xsd:element name="order-column" type="orm:order-column"
                    minOccurs="0" />
            </xsd:choice>
            <xsd:choice>
                <xsd:element name="map-key" type="orm:map-key"
                    minOccurs="0" />
                <xsd:sequence>
                    <xsd:element name="map-key-class" type="orm:map-key-class"
                        minOccurs="0" />
                    <xsd:choice>
                        <xsd:element name="map-key-temporal"
                            type="orm:temporal" minOccurs="0" />
                        <xsd:element name="map-key-enumerated"
                            type="orm:enumerated" minOccurs="0" />
                        <xsd:element name="map-key-attribute-override"
                            type="orm:attribute-override" minOccurs="0"
                            maxOccurs="unbounded" />
                    </xsd:choice>
                    <xsd:choice>
                        <xsd:element name="map-key-column"
                            type="orm:map-key-column" minOccurs="0" />
                        <xsd:element name="map-key-join-column"
                            type="orm:map-key-join-column" minOccurs="0"
                            maxOccurs="unbounded" />
                    </xsd:choice>
                </xsd:sequence>
            </xsd:choice>
            <xsd:choice>
                <xsd:sequence>
                    <xsd:element name="column" type="orm:column"
                        minOccurs="0" />
                    <xsd:choice>
                        <xsd:element name="temporal" type="orm:temporal"
                            minOccurs="0" />
                        <xsd:element name="enumerated" type="orm:enumerated"
                            minOccurs="0" />
                        <xsd:element name="lob" type="orm:lob"
                            minOccurs="0" />
                    </xsd:choice>
                </xsd:sequence>
                <xsd:sequence>
                    <xsd:element name="attribute-override"
                        type="orm:attribute-override" minOccurs="0"
                        maxOccurs="unbounded" />
                    <xsd:element name="association-override"
                        type="orm:association-override" minOccurs="0"
                        maxOccurs="unbounded" />
                </xsd:sequence>
            </xsd:choice>
            <xsd:element name="collection-table" type="orm:collection-table"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="target-class" type="xsd:string" />
        <xsd:attribute name="fetch" type="orm:fetch-type" />
        <xsd:attribute name="access" type="orm:access-type" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="embeddable">
        <xsd:annotation>
            <xsd:documentation>
                Defines the settings and mappings for embeddable objects. Is
                allowed to be sparsely populated and used in conjunction with
                the annotations. Alternatively, the metadata-complete attribute
                can be used to indicate that no annotations are to be processed
                in the class. If this is the case then the defaulting rules will
                be recursively applied.
                @Target({TYPE}) @Retention(RUNTIME)
                public @interface Embeddable {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="attributes" type="orm:embeddable-attributes"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="class" type="xsd:string" use="required" />
        <xsd:attribute name="access" type="orm:access-type" />
        <xsd:attribute name="metadata-complete" type="xsd:boolean" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="embeddable-attributes">
        <xsd:sequence>
            <xsd:element name="basic" type="orm:basic"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="many-to-one" type="orm:many-to-one"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="one-to-many" type="orm:one-to-many"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="one-to-one" type="orm:one-to-one"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="many-to-many" type="orm:many-to-many"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="element-collection" type="orm:element-collection"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="embedded" type="orm:embedded"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="transient" type="orm:transient"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="embedded">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface Embedded {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="attribute-override" type="orm:attribute-override"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="association-override" type="orm:association-override"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="access" type="orm:access-type" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="embedded-id">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface EmbeddedId {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="attribute-override" type="orm:attribute-override"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="access" type="orm:access-type" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="entity-listener">
        <xsd:annotation>
            <xsd:documentation>
                Defines an entity listener to be invoked at lifecycle events
                for the entities that list this listener.
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="pre-persist" type="orm:pre-persist"
                minOccurs="0" />
            <xsd:element name="post-persist" type="orm:post-persist"
                minOccurs="0" />
            <xsd:element name="pre-remove" type="orm:pre-remove"
                minOccurs="0" />
            <xsd:element name="post-remove" type="orm:post-remove"
                minOccurs="0" />
            <xsd:element name="pre-update" type="orm:pre-update"
                minOccurs="0" />
            <xsd:element name="post-update" type="orm:post-update"
                minOccurs="0" />
            <xsd:element name="post-load" type="orm:post-load"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="class" type="xsd:string" use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="entity-listeners">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE}) @Retention(RUNTIME)
                public @interface EntityListeners {
                Class[] value();
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="entity-listener" type="orm:entity-listener"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="entity-result">
        <xsd:annotation>
            <xsd:documentation>
                @Target({}) @Retention(RUNTIME)
                public @interface EntityResult {
                Class entityClass();
                FieldResult[] fields() default {};
                String discriminatorColumn() default "";
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="field-result" type="orm:field-result"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="entity-class" type="xsd:string"
            use="required" />
        <xsd:attribute name="discriminator-column" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:simpleType name="enum-type">
        <xsd:annotation>
            <xsd:documentation>
                public enum EnumType {
                ORDINAL,
                STRING
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="xsd:token">
            <xsd:enumeration value="ORDINAL" />
            <xsd:enumeration value="STRING" />
        </xsd:restriction>
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:simpleType name="enumerated">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface Enumerated {
                EnumType value() default ORDINAL;
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="orm:enum-type" />
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:simpleType name="fetch-type">
        <xsd:annotation>
            <xsd:documentation>
                public enum FetchType { LAZY, EAGER };
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="xsd:token">
            <xsd:enumeration value="LAZY" />
            <xsd:enumeration value="EAGER" />
        </xsd:restriction>
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:complexType name="field-result">
        <xsd:annotation>
            <xsd:documentation>
                @Target({}) @Retention(RUNTIME)
                public @interface FieldResult {
                String name();
                String column();
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="column" type="xsd:string"
            use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="generated-value">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface GeneratedValue {
                GenerationType strategy() default AUTO;
                String generator() default "";
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="strategy" type="orm:generation-type" />
        <xsd:attribute name="generator" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:simpleType name="generation-type">
        <xsd:annotation>
            <xsd:documentation>
                public enum GenerationType { TABLE, SEQUENCE, IDENTITY, AUTO };
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="xsd:token">
            <xsd:enumeration value="TABLE" />
            <xsd:enumeration value="SEQUENCE" />
            <xsd:enumeration value="IDENTITY" />
            <xsd:enumeration value="AUTO" />
        </xsd:restriction>
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:complexType name="id">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface Id {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="column" type="orm:column"
                minOccurs="0" />
            <xsd:element name="generated-value" type="orm:generated-value"
                minOccurs="0" />
            <xsd:element name="temporal" type="orm:temporal"
                minOccurs="0" />
            <xsd:element name="table-generator" type="orm:table-generator"
                minOccurs="0" />
            <xsd:element name="sequence-generator" type="orm:sequence-generator"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="access" type="orm:access-type" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="id-class">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE}) @Retention(RUNTIME)
                public @interface IdClass {
                Class value();
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="class" type="xsd:string" use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="inheritance">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE}) @Retention(RUNTIME)
                public @interface Inheritance {
                InheritanceType strategy() default SINGLE_TABLE;
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="strategy" type="orm:inheritance-type" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:simpleType name="inheritance-type">
        <xsd:annotation>
            <xsd:documentation>
                public enum InheritanceType
                { SINGLE_TABLE, JOINED, TABLE_PER_CLASS};
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="xsd:token">
            <xsd:enumeration value="SINGLE_TABLE" />
            <xsd:enumeration value="JOINED" />
            <xsd:enumeration value="TABLE_PER_CLASS" />
        </xsd:restriction>
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:complexType name="join-column">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface JoinColumn {
                String name() default "";
                String referencedColumnName() default "";
                boolean unique() default false;
                boolean nullable() default true;
                boolean insertable() default true;
                boolean updatable() default true;
                String columnDefinition() default "";
                String table() default "";
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="name" type="xsd:string" />
        <xsd:attribute name="referenced-column-name" type="xsd:string" />
        <xsd:attribute name="unique" type="xsd:boolean" />
        <xsd:attribute name="nullable" type="xsd:boolean" />
        <xsd:attribute name="insertable" type="xsd:boolean" />
        <xsd:attribute name="updatable" type="xsd:boolean" />
        <xsd:attribute name="column-definition" type="xsd:string" />
        <xsd:attribute name="table" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="join-table">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface JoinTable {
                String name() default "";
                String catalog() default "";
                String schema() default "";
                JoinColumn[] joinColumns() default {};
                JoinColumn[] inverseJoinColumns() default {};
                UniqueConstraint[] uniqueConstraints() default {};
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="join-column" type="orm:join-column"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="inverse-join-column" type="orm:join-column"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="unique-constraint" type="orm:unique-constraint"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" />
        <xsd:attribute name="catalog" type="xsd:string" />
        <xsd:attribute name="schema" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="lob">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface Lob {}
            </xsd:documentation>
        </xsd:annotation>
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:simpleType name="lock-mode-type">
        <xsd:annotation>
            <xsd:documentation>
                public enum LockModeType { READ, WRITE, OPTIMISTIC,
                OPTIMISTIC_FORCE_INCREMENT, PESSIMISTIC_READ,
                PESSIMISTIC_WRITE,
                PESSIMISTIC_FORCE_INCREMENT, NONE};
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="xsd:token">
            <xsd:enumeration value="READ" />
            <xsd:enumeration value="WRITE" />
            <xsd:enumeration value="OPTIMISTIC" />
            <xsd:enumeration value="OPTIMISTIC_FORCE_INCREMENT" />
            <xsd:enumeration value="PESSIMISTIC_READ" />
            <xsd:enumeration value="PESSIMISTIC_WRITE" />
            <xsd:enumeration value="PESSIMISTIC_FORCE_INCREMENT" />
            <xsd:enumeration value="NONE" />
        </xsd:restriction>
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:complexType name="many-to-many">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface ManyToMany {
                Class targetEntity() default void.class;
                CascadeType[] cascade() default {};
                FetchType fetch() default LAZY;
                String mappedBy() default "";
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:choice>
                <xsd:element name="order-by" type="orm:order-by"
                    minOccurs="0" />
                <xsd:element name="order-column" type="orm:order-column"
                    minOccurs="0" />
            </xsd:choice>
            <xsd:choice>
                <xsd:element name="map-key" type="orm:map-key"
                    minOccurs="0" />
                <xsd:sequence>
                    <xsd:element name="map-key-class" type="orm:map-key-class"
                        minOccurs="0" />
                    <xsd:choice>
                        <xsd:element name="map-key-temporal"
                            type="orm:temporal" minOccurs="0" />
                        <xsd:element name="map-key-enumerated"
                            type="orm:enumerated" minOccurs="0" />
                        <xsd:element name="map-key-attribute-override"
                            type="orm:attribute-override" minOccurs="0"
                            maxOccurs="unbounded" />
                    </xsd:choice>
                    <xsd:choice>
                        <xsd:element name="map-key-column"
                            type="orm:map-key-column" minOccurs="0" />
                        <xsd:element name="map-key-join-column"
                            type="orm:map-key-join-column" minOccurs="0"
                            maxOccurs="unbounded" />
                    </xsd:choice>
                </xsd:sequence>
            </xsd:choice>
            <xsd:element name="join-table" type="orm:join-table"
                minOccurs="0" />
            <xsd:element name="cascade" type="orm:cascade-type"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="target-entity" type="xsd:string" />
        <xsd:attribute name="fetch" type="orm:fetch-type" />
        <xsd:attribute name="access" type="orm:access-type" />
        <xsd:attribute name="mapped-by" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="many-to-one">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface ManyToOne {
                Class targetEntity() default void.class;
                CascadeType[] cascade() default {};
                FetchType fetch() default EAGER;
                boolean optional() default true;
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:choice>
                <xsd:element name="join-column" type="orm:join-column"
                    minOccurs="0" maxOccurs="unbounded" />
                <xsd:element name="join-table" type="orm:join-table"
                    minOccurs="0" />
            </xsd:choice>
            <xsd:element name="cascade" type="orm:cascade-type"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="target-entity" type="xsd:string" />
        <xsd:attribute name="fetch" type="orm:fetch-type" />
        <xsd:attribute name="optional" type="xsd:boolean" />
        <xsd:attribute name="access" type="orm:access-type" />
        <xsd:attribute name="maps-id" type="xsd:string" />
        <xsd:attribute name="id" type="xsd:boolean" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="map-key">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface MapKey {
                String name() default "";
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="name" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="map-key-class">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface MapKeyClass {
                Class value();
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="class" type="xsd:string" use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="map-key-column">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface MapKeyColumn {
                String name() default "";
                boolean unique() default false;
                boolean nullable() default false;
                boolean insertable() default true;
                boolean updatable() default true;
                String columnDefinition() default "";
                String table() default "";
                int length() default 255;
                int precision() default 0; // decimal precision
                int scale() default 0; // decimal scale
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="name" type="xsd:string" />
        <xsd:attribute name="unique" type="xsd:boolean" />
        <xsd:attribute name="nullable" type="xsd:boolean" />
        <xsd:attribute name="insertable" type="xsd:boolean" />
        <xsd:attribute name="updatable" type="xsd:boolean" />
        <xsd:attribute name="column-definition" type="xsd:string" />
        <xsd:attribute name="table" type="xsd:string" />
        <xsd:attribute name="length" type="xsd:int" />
        <xsd:attribute name="precision" type="xsd:int" />
        <xsd:attribute name="scale" type="xsd:int" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="map-key-join-column">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface MapKeyJoinColumn {
                String name() default "";
                String referencedColumnName() default "";
                boolean unique() default false;
                boolean nullable() default false;
                boolean insertable() default true;
                boolean updatable() default true;
                String columnDefinition() default "";
                String table() default "";
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="name" type="xsd:string" />
        <xsd:attribute name="referenced-column-name" type="xsd:string" />
        <xsd:attribute name="unique" type="xsd:boolean" />
        <xsd:attribute name="nullable" type="xsd:boolean" />
        <xsd:attribute name="insertable" type="xsd:boolean" />
        <xsd:attribute name="updatable" type="xsd:boolean" />
        <xsd:attribute name="column-definition" type="xsd:string" />
        <xsd:attribute name="table" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="mapped-superclass">
        <xsd:annotation>
            <xsd:documentation>
                Defines the settings and mappings for a mapped superclass. Is
                allowed to be sparsely populated and used in conjunction with
                the annotations. Alternatively, the metadata-complete attribute
                can be used to indicate that no annotations are to be processed
                If this is the case then the defaulting rules will be recursively
                applied.
                @Target(TYPE) @Retention(RUNTIME)
                public @interface MappedSuperclass{}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="id-class" type="orm:id-class"
                minOccurs="0" />
            <xsd:element name="exclude-default-listeners"
                type="orm:emptyType" minOccurs="0" />
            <xsd:element name="exclude-superclass-listeners"
                type="orm:emptyType" minOccurs="0" />
            <xsd:element name="entity-listeners" type="orm:entity-listeners"
                minOccurs="0" />
            <xsd:element name="pre-persist" type="orm:pre-persist"
                minOccurs="0" />
            <xsd:element name="post-persist" type="orm:post-persist"
                minOccurs="0" />
            <xsd:element name="pre-remove" type="orm:pre-remove"
                minOccurs="0" />
            <xsd:element name="post-remove" type="orm:post-remove"
                minOccurs="0" />
            <xsd:element name="pre-update" type="orm:pre-update"
                minOccurs="0" />
            <xsd:element name="post-update" type="orm:post-update"
                minOccurs="0" />
            <xsd:element name="post-load" type="orm:post-load"
                minOccurs="0" />
            <xsd:element name="attributes" type="orm:attributes"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="class" type="xsd:string" use="required" />
        <xsd:attribute name="access" type="orm:access-type" />
        <xsd:attribute name="metadata-complete" type="xsd:boolean" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="named-native-query">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE}) @Retention(RUNTIME)
                public @interface NamedNativeQuery {
                String name();
                String query();
                QueryHint[] hints() default {};
                Class resultClass() default void.class;
                String resultSetMapping() default ""; //named SqlResultSetMapping
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="query" type="xsd:string" />
            <xsd:element name="hint" type="orm:query-hint"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="result-class" type="xsd:string" />
        <xsd:attribute name="result-set-mapping" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="named-query">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE}) @Retention(RUNTIME)
                public @interface NamedQuery {
                String name();
                String query();
                LockModeType lockMode() default NONE;
                QueryHint[] hints() default {};
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="query" type="xsd:string" />
            <xsd:element name="lock-mode" type="orm:lock-mode-type"
                minOccurs="0" />
            <xsd:element name="hint" type="orm:query-hint"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="one-to-many">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface OneToMany {
                Class targetEntity() default void.class;
                CascadeType[] cascade() default {};
                FetchType fetch() default LAZY;
                String mappedBy() default "";
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:choice>
                <xsd:element name="order-by" type="orm:order-by"
                    minOccurs="0" />
                <xsd:element name="order-column" type="orm:order-column"
                    minOccurs="0" />
            </xsd:choice>
            <xsd:choice>
                <xsd:element name="map-key" type="orm:map-key"
                    minOccurs="0" />
                <xsd:sequence>
                    <xsd:element name="map-key-class" type="orm:map-key-class"
                        minOccurs="0" />
                    <xsd:choice>
                        <xsd:element name="map-key-temporal"
                            type="orm:temporal" minOccurs="0" />
                        <xsd:element name="map-key-enumerated"
                            type="orm:enumerated" minOccurs="0" />
                        <xsd:element name="map-key-attribute-override"
                            type="orm:attribute-override" minOccurs="0"
                            maxOccurs="unbounded" />
                    </xsd:choice>
                    <xsd:choice>
                        <xsd:element name="map-key-column"
                            type="orm:map-key-column" minOccurs="0" />
                        <xsd:element name="map-key-join-column"
                            type="orm:map-key-join-column" minOccurs="0"
                            maxOccurs="unbounded" />
                    </xsd:choice>
                </xsd:sequence>
            </xsd:choice>
            <xsd:choice>
                <xsd:element name="join-table" type="orm:join-table"
                    minOccurs="0" />
                <xsd:element name="join-column" type="orm:join-column"
                    minOccurs="0" maxOccurs="unbounded" />
            </xsd:choice>
            <xsd:element name="cascade" type="orm:cascade-type"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="target-entity" type="xsd:string" />
        <xsd:attribute name="fetch" type="orm:fetch-type" />
        <xsd:attribute name="access" type="orm:access-type" />
        <xsd:attribute name="mapped-by" type="xsd:string" />
        <xsd:attribute name="orphan-removal" type="xsd:boolean" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="one-to-one">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface OneToOne {
                Class targetEntity() default void.class;
                CascadeType[] cascade() default {};
                FetchType fetch() default EAGER;
                boolean optional() default true;
                String mappedBy() default "";
                boolean orphanRemoval() default false;
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:choice>
                <xsd:element name="primary-key-join-column"
                    type="orm:primary-key-join-column" minOccurs="0"
                    maxOccurs="unbounded" />
                <xsd:element name="join-column" type="orm:join-column"
                    minOccurs="0" maxOccurs="unbounded" />
                <xsd:element name="join-table" type="orm:join-table"
                    minOccurs="0" />
            </xsd:choice>
            <xsd:element name="cascade" type="orm:cascade-type"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="target-entity" type="xsd:string" />
        <xsd:attribute name="fetch" type="orm:fetch-type" />
        <xsd:attribute name="optional" type="xsd:boolean" />
        <xsd:attribute name="access" type="orm:access-type" />
        <xsd:attribute name="mapped-by" type="xsd:string" />
        <xsd:attribute name="orphan-removal" type="xsd:boolean" />
        <xsd:attribute name="maps-id" type="xsd:string" />
        <xsd:attribute name="id" type="xsd:boolean" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:simpleType name="order-by">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface OrderBy {
                String value() default "";
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="xsd:string" />
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:complexType name="order-column">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface OrderColumn {
                String name() default "";
                boolean nullable() default true;
                boolean insertable() default true;
                boolean updatable() default true;
                String columnDefinition() default "";
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="name" type="xsd:string" />
        <xsd:attribute name="nullable" type="xsd:boolean" />
        <xsd:attribute name="insertable" type="xsd:boolean" />
        <xsd:attribute name="updatable" type="xsd:boolean" />
        <xsd:attribute name="column-definition" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="post-load">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD}) @Retention(RUNTIME)
                public @interface PostLoad {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="method-name" type="xsd:string"
            use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="post-persist">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD}) @Retention(RUNTIME)
                public @interface PostPersist {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="method-name" type="xsd:string"
            use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="post-remove">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD}) @Retention(RUNTIME)
                public @interface PostRemove {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="method-name" type="xsd:string"
            use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="post-update">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD}) @Retention(RUNTIME)
                public @interface PostUpdate {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="method-name" type="xsd:string"
            use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="pre-persist">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD}) @Retention(RUNTIME)
                public @interface PrePersist {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="method-name" type="xsd:string"
            use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="pre-remove">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD}) @Retention(RUNTIME)
                public @interface PreRemove {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="method-name" type="xsd:string"
            use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="pre-update">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD}) @Retention(RUNTIME)
                public @interface PreUpdate {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="method-name" type="xsd:string"
            use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="primary-key-join-column">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
                public @interface PrimaryKeyJoinColumn {
                String name() default "";
                String referencedColumnName() default "";
                String columnDefinition() default "";
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="name" type="xsd:string" />
        <xsd:attribute name="referenced-column-name" type="xsd:string" />
        <xsd:attribute name="column-definition" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="query-hint">
        <xsd:annotation>
            <xsd:documentation>
                @Target({}) @Retention(RUNTIME)
                public @interface QueryHint {
                String name();
                String value();
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="value" type="xsd:string" use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="secondary-table">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE}) @Retention(RUNTIME)
                public @interface SecondaryTable {
                String name();
                String catalog() default "";
                String schema() default "";
                PrimaryKeyJoinColumn[] pkJoinColumns() default {};
                UniqueConstraint[] uniqueConstraints() default {};
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="primary-key-join-column"
                type="orm:primary-key-join-column" minOccurs="0"
                maxOccurs="unbounded" />
            <xsd:element name="unique-constraint" type="orm:unique-constraint"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="catalog" type="xsd:string" />
        <xsd:attribute name="schema" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="sequence-generator">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
                public @interface SequenceGenerator {
                String name();
                String sequenceName() default "";
                String catalog() default "";
                String schema() default "";
                int initialValue() default 1;
                int allocationSize() default 50;
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="sequence-name" type="xsd:string" />
        <xsd:attribute name="catalog" type="xsd:string" />
        <xsd:attribute name="schema" type="xsd:string" />
        <xsd:attribute name="initial-value" type="xsd:int" />
        <xsd:attribute name="allocation-size" type="xsd:int" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="sql-result-set-mapping">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE}) @Retention(RUNTIME)
                public @interface SqlResultSetMapping {
                String name();
                EntityResult[] entities() default {};
                ColumnResult[] columns() default {};
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="entity-result" type="orm:entity-result"
                minOccurs="0" maxOccurs="unbounded" />
            <xsd:element name="column-result" type="orm:column-result"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="table">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE}) @Retention(RUNTIME)
                public @interface Table {
                String name() default "";
                String catalog() default "";
                String schema() default "";
                UniqueConstraint[] uniqueConstraints() default {};
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="unique-constraint" type="orm:unique-constraint"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" />
        <xsd:attribute name="catalog" type="xsd:string" />
        <xsd:attribute name="schema" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="table-generator">
        <xsd:annotation>
            <xsd:documentation>
                @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
                public @interface TableGenerator {
                String name();
                String table() default "";
                String catalog() default "";
                String schema() default "";
                String pkColumnName() default "";
                String valueColumnName() default "";
                String pkColumnValue() default "";
                int initialValue() default 0;
                int allocationSize() default 50;
                UniqueConstraint[] uniqueConstraints() default {};
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="description" type="xsd:string"
                minOccurs="0" />
            <xsd:element name="unique-constraint" type="orm:unique-constraint"
                minOccurs="0" maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="table" type="xsd:string" />
        <xsd:attribute name="catalog" type="xsd:string" />
        <xsd:attribute name="schema" type="xsd:string" />
        <xsd:attribute name="pk-column-name" type="xsd:string" />
        <xsd:attribute name="value-column-name" type="xsd:string" />
        <xsd:attribute name="pk-column-value" type="xsd:string" />
        <xsd:attribute name="initial-value" type="xsd:int" />
        <xsd:attribute name="allocation-size" type="xsd:int" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:simpleType name="temporal">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface Temporal {
                TemporalType value();
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="orm:temporal-type" />
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:simpleType name="temporal-type">
        <xsd:annotation>
            <xsd:documentation>
                public enum TemporalType {
                DATE, // java.sql.Date
                TIME, // java.sql.Time
                TIMESTAMP // java.sql.Timestamp
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:restriction base="xsd:token">
            <xsd:enumeration value="DATE" />
            <xsd:enumeration value="TIME" />
            <xsd:enumeration value="TIMESTAMP" />
        </xsd:restriction>
    </xsd:simpleType>
    <!-- **************************************************** -->
    <xsd:complexType name="transient">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface Transient {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:attribute name="name" type="xsd:string" use="required" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="unique-constraint">
        <xsd:annotation>
            <xsd:documentation>
                @Target({}) @Retention(RUNTIME)
                public @interface UniqueConstraint {
                String name() default "";
                String[] columnNames();
                }
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="column-name" type="xsd:string"
                maxOccurs="unbounded" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" />
    </xsd:complexType>
    <!-- **************************************************** -->
    <xsd:complexType name="version">
        <xsd:annotation>
            <xsd:documentation>
                @Target({METHOD, FIELD}) @Retention(RUNTIME)
                public @interface Version {}
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="column" type="orm:column"
                minOccurs="0" />
            <xsd:element name="temporal" type="orm:temporal"
                minOccurs="0" />
        </xsd:sequence>
        <xsd:attribute name="name" type="xsd:string" use="required" />
        <xsd:attribute name="access" type="orm:access-type" />
    </xsd:complexType>
</xsd:schema>

That exhausts persistence metadata annotations. We present the class definitions for our sample model below:

package org.mag;

@Entity
@IdClass(Magazine.MagazineId.class)
public class Magazine {

    @Id private String isbn;
    @Id private String title;
    @Version private int version;

    private double price;   // defaults to @Basic
    private int copiesSold; // defaults to @Basic

    @OneToOne(fetch=FetchType.LAZY, 
        cascade={CascadeType.PERSIST,CascadeType.REMOVE})
    private Article coverArticle;

    @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
    @OrderBy
    private Collection<Article> articles;

    @ManyToOne(fetch=FetchType.LAZY, cascade=CascadeType.PERSIST)
    private Company publisher; 

    @Transient private byte[] data;

    ...

    public static class MagazineId {
        ...
    }
}

@Entity
public class Article {

    @Id private long id;
    @Version private int version;
    
    private String title;   // defaults to @Basic
    private byte[] content; // defaults to @Basic

    @ManyToMany(cascade=CascadeType.PERSIST)
    @OrderBy("lastName, firstName")
    private Collection<Author> authors;

    ...
}


package org.mag.pub;

@Entity
public class Company {

    @Id private long id;
    @Version private int version;

    private String name;     // defaults to @Basic
    private double revenue;  // defaults to @Basic
    private Address address; // defaults to @Embedded
    
    @OneToMany(mappedBy="publisher", cascade=CascadeType.PERSIST)
    private Collection<Magazine> mags;

    @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
    private Collection<Subscription> subscriptions;

    ...
}

@Entity
public class Author {

    @Id private long id;
    @Version private int version;

    private String firstName; // defaults to @Basic
    private double lastName;  // defaults to @Basic
    private Address address;  // defaults to @Embedded
    
    @ManyToMany(mappedBy="authors", cascade=CascadeType.PERSIST)
    private Collection<Article> arts;

    ...
}

@Embeddable
public class Address {

    private String street; // defaults to @Basic
    private String city;   // defaults to @Basic
    private String state;  // defaults to @Basic
    private String zip;    // defaults to @Basic

    ...
}


package org.mag.subscribe;

@MappedSuperclass
public abstract class Document {

    @Id private long id;
    @Version private int version;

    ...
}

@Entity
public class Contract
    extends Document {

    private String terms; // defaults to @Basic

    ...
}

@Entity
public class Subscription {

    @Id private long id;
    @Version private int version;

    private Date startDate; // defaults to @Basic
    private double payment; // defaults to @Basic

    @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE})
    @MapKey(name="num")
    private Map<Long,LineItem> lineItems;

    ...

    @Entity
    public static class LineItem
        extends Contract {

        private String comments; // defaults to @Basic
        private double price;    // defaults to @Basic
        private long num;        // defaults to @Basic

        @ManyToOne
        private Magazine magazine;

        ...
    }
}

@Entity(name="Lifetime")
public class LifetimeSubscription
    extends Subscription {

    @Basic(fetch=FetchType.LAZY)
    private boolean getEliteClub() { ... }
    public void setEliteClub(boolean elite) { ... }

    ...
}

@Entity(name="Trial")
public class TrialSubscription
    extends Subscription {

    public Date getEndDate() { ... }
    public void setEndDate(Date end) { ... }

    ...
}

<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
    version="1.0">
    <!-- declares a default access type for all entities -->
    <access-type>FIELD</access-type>
    <mapped-superclass class="org.mag.subscribe.Document">
        <attributes>
            <id name="id">
                <generated-value strategy="IDENTITY"/>
            </id>
            <version name="version"/>
        </attributes>
    </mapped-superclass>
    <entity class="org.mag.Magazine">
        <id-class="org.mag.Magazine$MagazineId"/>
        <attributes>
            <id name="isbn"/>
            <id name="title"/>
            <basic name="name"/>
            <basic name="price"/>
            <basic name="copiesSold"/>
            <version name="version"/>
            <many-to-one name="publisher" fetch="LAZY">
                <cascade>
                    <cascade-persist/>
                </cascade>
            </many-to-one>
            <one-to-many name="articles">
                <order-by/>
                <cascade>
                    <cascade-persist/>
                    <cascade-remove/>
                </cascade>
            </one-to-many>
            <one-to-one name="coverArticle" fetch="LAZY">
                <cascade>
                    <cascade-persist/>
                    <cascade-remove/>
                </cascade>
            </one-to-one>
            <transient name="data"/>
        </attributes>
    </entity>
    <entity class="org.mag.Article">
        <attributes>
            <id name="id"/>
            <basic name="title"/>
            <basic name="content"/>
            <version name="version"/>
            <many-to-many name="articles">
                <order-by>lastName, firstName</order-by>
            </many-to-many>
        </attributes>
    </entity>
    <entity class="org.mag.pub.Company">
        <attributes>
            <id name="id"/>
            <basic name="name"/>
            <basic name="revenue"/>
            <version name="version"/>
            <one-to-many name="mags" mapped-by="publisher">
                <cascade>
                    <cascade-persist/>
                </cascade>
            </one-to-many>
            <one-to-many name="subscriptions">
                <cascade>
                    <cascade-persist/>
                    <cascade-remove/>
                </cascade>
            </one-to-many>
        </attributes>
    </entity>
    <entity class="org.mag.pub.Author">
        <attributes>
            <id name="id"/>
            <basic name="firstName"/>
            <basic name="lastName"/>
            <version name="version"/>
            <many-to-many name="arts" mapped-by="authors">
                <cascade>
                    <cascade-persist/>
                </cascade>
            </many-to-many>
        </attributes>
    </entity>
    <entity class="org.mag.subcribe.Contract">
        <attributes>
            <basic name="terms"/>
        </attributes>
    </entity>
    <entity class="org.mag.subcribe.Subscription">
        <attributes>
            <id name="id"/>
            <basic name="payment"/>
            <basic name="startDate"/>
            <version name="version"/>
            <one-to-many name="items">
                <map-key name="num">
                <cascade>
                    <cascade-persist/>
                    <cascade-remove/>
                </cascade>
            </one-to-many>
        </attributes>
    </entity>
    <entity class="org.mag.subscribe.Subscription.LineItem">
        <attributes>
            <basic name="comments"/>
            <basic name="price"/>
            <basic name="num"/>
            <many-to-one name="magazine"/>
        </attributes>
    </entity>
    <entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"
        access="PROPERTY">
        <attributes>
            <basic name="eliteClub" fetch="LAZY"/>
        </attributes>
    </entity>
    <entity class="org.mag.subscribe.TrialSubscription" name="Trial">
        <attributes>
            <basic name="endDate"/>
        </attributes>
    </entity>
    <embeddable class="org.mag.pub.Address">
        <attributes>
            <basic name="street"/>
            <basic name="city"/>
            <basic name="state"/>
            <basic name="zip"/>
        </attributes>
    </embeddable>
</entity-mappings>

Chapter 13, Mapping Metadata will show you how to map your persistent classes to the datastore using additional annotations and XML markup. First, however, we turn to the JPA runtime APIs.

With the introduction of JPA 2.0, there are two versions of the persistence.xml. The most current revision of the 2.0 persistence schema is presented below. Version 1.0 of the persistence schema can be found at http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd.

<?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>

The root element of a persistence.xml file is persistence, which then contains one or more persistence-unit definitions. The root element should include the version attribute with the appropriate version, 1.0 for a version 1.0 file and 2.0 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.

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

<?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>

The example below demonstrates the Persistence 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 EntityManagerFactories are typically injected.

// 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);

Within a container, you will typically use injection to access an EntityManagerFactory. There are, however, alternative mechanisms for EntityManagerFactory construction.

Some vendors may supply public constructors for their EntityManagerFactory implementations, but we recommend using the Java Connector Architecture (JCA) in a managed environment, or the Persistence class' createEntityManagerFactory methods in an unmanaged environment, as described in Chapter 6, Persistence . These strategies allow vendors to pool factories, cutting down on resource utilization.

JPA allows you to create and configure an EntityManagerFactory, then store it in a Java Naming and Directory Interface (JNDI) tree for later retrieval and use.

public EntityManager createEntityManager();
public EntityManager createEntityManager(Map map);

The two createEntityManager methods above create a new EntityManager each time they are invoked. The optional Map is used to supply vendor-specific settings. If you have configured your implementation for JTA transactions and a JTA transaction is active, the returned EntityManager will be synchronized with that transaction.

A persistence context is a set of entities such that for any persistent identity there is a unique entity instance. Within a persistence context, entities are managed. The EntityManager controls their lifecycle, and they can access datastore resources.

When a persistence context ends, previously-managed entities become detached. A detached entity is no longer under the control of the EntityManager, and no longer has access to datastore resources. We discuss detachment in detail in Section 2, “ Entity Lifecycle Management ”. For now, it is sufficient to know that detachment has two obvious consequences:

Injected EntityManagers have a transaction persistence context, while EntityManagers obtained through the EntityManagerFactory have an extended persistence context. We describe these persistence context types below.

EntityManager em; // injected
...

// outside a transaction:

// each operation occurs in a separate persistence context, and returns 
// a new detached instance
Magazine mag1 = em.find(Magazine.class, magId);
Magazine mag2 = em.find(Magazine.class, magId);
assertTrue(mag2 != mag1);
...

// transaction begins:

// within a transaction, a subsequent lookup doesn't return any of the
// detached objects.  however, two lookups within the same transaction
// return the same instance, because the persistence context spans the
// transaction
Magazine mag3 = em.find(Magazine.class, magId);
assertTrue(mag3 != mag1 && mag3 != mag2);
Magazine mag4 = em.find(Magazine.class, magId);
assertTrue(mag4 == mag3);
...

// transaction commits:

// once again, each operation returns a new instance
Magazine mag5 = em.find(Magazine.class, magId);
assertTrue(mag5 != mag3);

EntityManagerFactory emf = ...
EntityManager em = emf.createEntityManager();

// persistence context active for entire life of EM, so only one entity
// for a given persistent identity
Magazine mag1 = em.find(Magazine.class, magId);
Magazine mag2 = em.find(Magazine.class, magId);
assertTrue(mag2 == mag1);

em.getTransaction().begin();

// same persistence context active within the transaction
Magazine mag3 = em.find(Magazine.class, magId);
assertTrue(mag3 == mag1);
Magazine mag4 = em.find(Magazine.class, magId);
assertTrue(mag4 == mag1);

em.getTransaction.commit();

// when the transaction commits, instance still managed
Magazine mag5 = em.find(Magazine.class, magId);
assertTrue(mag5 == mag1);

// instance finally becomes detached when EM closes
em.close();

There are two sets of properties that may be specified: those that are specific to OpenJPA and those that have been defined by the JPA specification. In some cases, two properties may be equivalent, but have different keys. For example, openjpa.LockTimeout and javax.persistence.lock.timeout are two different keys for the same property.

There are two methods that can be used to retrieve information related to properties:

public Map<String,Object> getProperties();
public Set<String> getSupportedProperties();

public boolean isOpen();
public void close();

EntityManagerFactory instances are heavyweight objects. Each factory might maintain a metadata cache, object state cache, EntityManager pool, connection pool, and more. If your application no longer needs an EntityManagerFactory, you should close it to free these resources. When an EntityManagerFactory closes, all EntityManagers from that factory, and by extension all entities managed by those EntityManagers, become invalid. Attempting to close an EntityManagerFactory while one or more of its EntityManagers has an active transaction may result in an IllegalStateException.

Closing an EntityManagerFactory should not be taken lightly. It is much better to keep a factory open for a long period of time than to repeatedly create and close new factories. Thus, most applications will never close the factory, or only close it when the application is exiting. Only applications that require multiple factories with different configurations have an obvious reason to create and close multiple EntityManagerFactory instances. Once a factory is closed, all methods except isOpen throw an IllegalStateException.

public PersistenceUnitUtil getPersistenceUnitUtil();

The EntityManagerFactory method getPersistenceUnitUtil provides access to a PersistenceUnitUtil utility. PersistenceUnitUtil can be used to obtain the identity of a managed object and determine the load state of the entity or one of its attributes. If the object is not managed by one of the entity managers created from the entity manager factory from which the utility was obtained, the getIdentifier method will return null and the isLoaded methods will return false.

EntityManagerFactory emf = Persistence.createEntityManagerFactory();
PersistenceUnitUtil puUtil = emf.getPersistenceUnitUtil();

if (puUtil.getIdentifier(deptEntity) == null) {
    throw new Exception("Identity is not valid.");
}
if (!puUtil.isLoaded(deptEntity, "employees")) {
    throw new Exception("Employees not loaded.");
}

public EntityTransaction getTransaction();

Every EntityManager has a one-to-one relation with an EntityTransaction instance. In fact, many vendors use a single class to implement both the EntityManager and EntityTransaction interfaces. If your application requires multiple concurrent transactions, you will use multiple EntityManagers.

You can retrieve the EntityTransaction associated with an EntityManager through the getTransaction method. Note that most JPA implementations can integrate with an application server's managed transactions. If you take advantage of this feature, you will control transactions by declarative demarcation or through the Java Transaction API (JTA) rather than through the EntityTransaction.

EntityManagers perform several actions that affect the lifecycle state of entity instances.

public void persist(Object entity);

Transitions new instances to managed. On the next flush or commit, the newly persisted instances will be inserted into the datastore.

For a given entity A, the persist method behaves as follows:

This action can only be used in the context of an active transaction.

public void remove(Object entity);

Transitions managed instances to removed. The instances will be deleted from the datastore on the next flush or commit. Accessing a removed entity has undefined results.

For a given entity A, the remove method behaves as follows:

This action can only be used in the context of an active transaction.

public void refresh(Object entity);

Use the refresh action to make sure the persistent state of an instance is synchronized with the values in the datastore. refresh is intended for long-running optimistic transactions in which there is a danger of seeing stale data.

For a given entity A, the refresh method behaves as follows:

public Object merge(Object entity);

A common use case for an application running in a servlet or application server is to "detach" objects from all server resources, modify them, and then "attach" them again. For example, a servlet might store persistent data in a user session between a modification based on a series of web forms. Between each form request, the web container might decide to serialize the session, requiring that the stored persistent state be disassociated from any other resources. Similarly, a client/server application might transfer persistent objects to a client via serialization, allow the client to modify their state, and then have the client return the modified data in order to be saved. This is sometimes referred to as the data transfer object or value object pattern, and it allows fine-grained manipulation of data objects without incurring the overhead of multiple remote method invocations.

JPA provides support for this pattern by automatically detaching entities when they are serialized or when a persistence context ends (see Section 3, “ Persistence Context ” for an exploration of persistence contexts). The JPA merge API re-attaches detached entities. This allows you to detach a persistent instance, modify the detached instance offline, and merge the instance back into an EntityManager (either the same one that detached the instance, or a new one). The changes will then be applied to the existing instance from the datastore.

A detached entity maintains its persistent identity, but cannot load additional state from the datastore. Accessing any persistent field or property that was not loaded at the time of detachment has undefined results. Also, be sure not to alter the version or identity fields of detached instances if you plan on merging them later.

The merge method returns a managed copy of the given detached entity. Changes made to the persistent state of the detached entity are applied to this managed instance. Because merging involves changing persistent state, you can only merge within a transaction.

If you attempt to merge an instance whose representation has changed in the datastore since detachment, the merge operation will throw an exception, or the transaction in which you perform the merge will fail on commit, just as if a normal optimistic conflict were detected.

For a given entity A, the merge method behaves as follows:

The following diagram illustrates the lifecycle of an entity with respect to the APIs presented in this section.

The examples below demonstrate how to use the lifecycle methods presented in the previous section. The examples are appropriate for out-of-container use. Within a container, EntityManagers are usually injected, and transactions are usually managed. You would therefore omit the createEntityManager and close calls, as well as all transaction demarcation code.

// create some objects
Magazine mag = new Magazine("1B78-YU9L", "JavaWorld");

Company pub = new Company("Weston House");
pub.setRevenue(1750000D);
mag.setPublisher(pub);
pub.addMagazine(mag);

Article art = new Article("JPA Rules!", "Transparent Object Persistence");
art.addAuthor(new Author("Fred", "Hoyle"));
mag.addArticle(art);

// persist
EntityManager em = emf.createEntityManager();
em.getTransaction().begin();
em.persist(mag);
em.persist(pub);
em.persist(art);
em.getTransaction().commit();

// or we could continue using the EntityManager...
em.close();

Magazine.MagazineId mi = new Magazine.MagazineId();
mi.isbn = "1B78-YU9L";
mi.title = "JavaWorld";

// updates should always be made within transactions; note that
// there is no code explicitly linking the magazine or company
// with the transaction; JPA automatically tracks all changes
EntityManager em = emf.createEntityManager();
em.getTransaction().begin();
Magazine mag = em.find(Magazine.class, mi);
mag.setPrice(5.99);
Company pub = mag.getPublisher();
pub.setRevenue(1750000D);
em.getTransaction().commit();

// or we could continue using the EntityManager...
em.close();

// assume we have an object id for the company whose subscriptions
// we want to delete
Object oid = ...;

// deletes should always be made within transactions
EntityManager em = emf.createEntityManager();
em.getTransaction().begin();
Company pub = (Company) em.find(Company.class, oid);
for (Subscription sub : pub.getSubscriptions())
    em.remove(sub);
pub.getSubscriptions().clear();
em.getTransaction().commit();

// or we could continue using the EntityManager...
em.close();

// CLIENT:
// requests an object with a given oid
Record detached = (Record) getFromServer(oid);

...

// SERVER:
// send object to client; object detaches on EM close
Object oid = processClientRequest();
EntityManager em = emf.createEntityManager();
Record record = em.find(Record.class, oid);
em.close();
sendToClient(record);

...

// CLIENT:
// makes some modifications and sends back to server
detached.setSomeField("bar");
sendToServer(detached);

...

// SERVER:
// merges the instance and commit the changes
Record modified = (Record) processClientRequest();
EntityManager em = emf.createEntityManager();
em.getTransaction().begin();
Record merged = (Record) em.merge(modified);
merged.setLastModified(System.currentTimeMillis());
merged.setModifier(getClientIdentityCode());
em.getTransaction().commit();
em.close();

Each EntityManager is responsible for managing the persistent identities of the managed objects in the persistence context. The following methods allow you to interact with the management of persistent identities. The behavior of these methods is deeply affected by the persistence context type of the EntityManager; see Section 3, “ Persistence Context ” for an explanation of persistence contexts.

public <T> T find(Class<T> cls, Object oid);

This method returns the persistent instance of the given type with the given persistent identity. If the instance is already present in the current persistence context, the cached version will be returned. Otherwise, a new instance will be constructed and loaded with state from the datastore. If no entity with the given type and identity exists in the datastore, this method returns null.

public <T> T getReference(Class<T> cls, Object oid);

This method is similar to find, but does not necessarily go to the database when the entity is not found in cache. The implementation may construct a hollow entity and return it to you instead. Hollow entities do not have any state loaded. The state only gets loaded when you attempt to access a persistent field. At that time, the implementation may throw an EntityNotFoundException if it discovers that the entity does not exist in the datastore. The implementation may also throw an EntityNotFoundException from the getReference method itself. Unlike find, getReference does not return null.

public boolean contains(Object entity);

Returns true if the given entity is part of the current persistence context, and false otherwise. Removed entities are not considered part of the current persistence context.

public void flush();

The flush method writes any changes that have been made in the current transaction to the datastore. If the EntityManager does not already have a connection to the datastore, it obtains one for the flush and retains it for the duration of the transaction. Any exceptions during flush cause the transaction to be marked for rollback. See Chapter 9, Transaction .

Flushing requires an active transaction. If there isn't a transaction in progress, the flush method throws a TransactionRequiredException.

public FlushModeType getFlushMode();
public void setFlushMode(FlushModeType flushMode);

The EntityManager's FlushMode property controls whether to flush transactional changes before executing queries. This allows the query results to take into account changes you have made during the current transaction. Available javax.persistence.FlushModeType constants are:

You can also set the flush mode on individual Query instances.

public void clear();

Clearing the EntityManager effectively ends the persistence context. All entities managed by the EntityManager become detached.

public Query createQuery(String query);

Query objects are used to find entities matching certain criteria. The createQuery method creates a query using the given Java Persistence Query Language (JPQL) string. See Chapter 10, JPA Query for details.

public Query createNamedQuery(String name);

This method retrieves a query defined in metadata by name. The returned Query instance is initialized with the information declared in metadata. For more information on named queries, read Section 1.11, “ Named Queries ”.

public Query createNativeQuery(String sql);
public Query createNativeQuery(String sql, Class resultCls);
public Query createNativeQuery(String sql, String resultMapping);

Native queries are queries in the datastore's native language. For relational databases, this is the Structured Query Language (SQL). Chapter 12, SQL Queries elaborates on JPA's native query support.

In the area of concurrency control, the JPA specification supports optimistic and pessimistic locking.

public void lock(Object entity, LockModeType mode);

This method locks the given entity using the named mode. The javax.persistence.LockModeType enum defines eight modes:

Entities can also be locked at the time when entity state gets loaded from the datastore. This is achieved by supplying a lock mode to the respective versions of find and refresh methods. If an entity state is to be loaded by a query, a lock mode can be passed to the Query.setLockMode and TypedQuery.setLockMode methods.

public LockModeType getLockMode(Object entity);

Returns the lock mode currently held by the given entity.

There are two sets of properties that may be specified: those that are specific to OpenJPA and those that have been defined by the JPA specification. In some cases, two properties may be equivalent, but have different keys. For example, openjpa.LockTimeout and javax.persistence.lock.timeout are two different keys for the same property.

There are two methods that can be used to retrieve information related to properties:

public Map<String,Object> getProperties();
public Set<String> getSupportedProperties();

public boolean isOpen();
public void close();

When an EntityManager is no longer needed, you should call its close method. Closing an EntityManager releases any resources it is using. The persistence context ends, and the entities managed by the EntityManager become detached. Any Query instances the EntityManager created become invalid. Calling any method other than isOpen on a closed EntityManager results in an IllegalStateException. You cannot close a EntityManager that is in the middle of a transaction.

If you are in a managed environment using injected entity managers, you should not close them.

There are two major types of transactions: pessimistic transactions and optimistic transactions. Each type has both advantages and disadvantages.

Pessimistic transactions generally lock the datastore records they act on, preventing other concurrent transactions from using the same data. This avoids conflicts between transactions, but consumes database resources. Additionally, locking records can result in deadlock, a situation in which two transactions are both waiting for the other to release its locks before completing. The results of a deadlock are datastore-dependent; usually one transaction is forcefully rolled back after some specified timeout interval, and an exception is thrown.

This document will often use the term datastore transaction in place of pessimistic transaction. This is to acknowledge that some datastores do not support pessimistic semantics, and that the exact meaning of a non-optimistic JPA transaction is dependent on the datastore. Most of the time, a datastore transaction is equivalent to a pessimistic transaction.

Optimistic transactions consume less resources than pessimistic/datastore transactions, but only at the expense of reliability. Because optimistic transactions do not lock datastore records, two transactions might change the same persistent information at the same time, and the conflict will not be detected until the second transaction attempts to flush or commit. At this time, the second transaction will realize that another transaction has concurrently modified the same records (usually through a timestamp or versioning system), and will throw an appropriate exception. Note that optimistic transactions still maintain data integrity; they are simply more likely to fail in heavily concurrent situations.

Despite their drawbacks, optimistic transactions are the best choice for most applications. They offer better performance, better scalability, and lower risk of hanging due to deadlock.

JPA integrates with your container's managed transactions, allowing you to use the container's declarative transaction demarcation and its Java Transaction API (JTA) implementation for transaction management. Outside of a container, though, you must demarcate transactions manually through JPA. The EntityTransaction interface controls unmanaged transactions in JPA.

public void begin();
public void commit();
public void rollback();

The begin, commit, and rollback methods demarcate transaction boundaries. The methods should be self-explanatory: begin starts a transaction, commit attempts to commit the transaction's changes to the datastore, and rollback aborts the transaction, in which case the datastore is "rolled back" to its previous state. JPA implementations will automatically roll back transactions if any exception is thrown during the commit process.

Unless you are using an extended persistence context, committing or rolling back also ends the persistence context. All managed entities will be detached from the EntityManager.

public boolean isActive();

Finally, the isActive method returns true if the transaction is in progress (begin has been called more recently than commit or rollback), and false otherwise.

public void transferFunds(EntityManager em, User from, User to, double amnt) {
    // note: it would be better practice to move the transaction demarcation
    // code out of this method, but for the purposes of example...
    Transaction trans = em.getTransaction();
    trans.begin();
    try
    {
        from.decrementAccount(amnt);
        to.incrementAccount(amnt);
        trans.commit();
    }
    catch (RuntimeException re)
    {
        if (trans.isActive())
            trans.rollback();   // or could attempt to fix error and retry
        throw re;
    }
}