openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mprud...@apache.org
Subject svn commit: r433761 [3/18] - in /incubator/openjpa/trunk/openjpa-project: ./ src/doc/manual/
Date Tue, 22 Aug 2006 21:28:55 GMT
Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml Tue Aug 22 14:28:53 2006
@@ -0,0 +1,3519 @@
+
+    <chapter id="jpa_overview_meta">
+      <title>Metadata</title>
+      <indexterm zone="jpa_overview_meta">
+        <primary>metadata</primary>
+      </indexterm>
+      <indexterm zone="jpa_overview_meta">
+        <primary>JPA</primary>
+        <secondary>metadata</secondary>
+        <seealso>metadata</seealso>
+      </indexterm>
+      <para>
+  JPA requires that you accompany each persistent class with
+  persistence metadata.  This metadata serves three primary purposes:
+  </para>
+      <orderedlist>
+        <listitem>
+          <para>To identify persistent classes.</para>
+        </listitem>
+        <listitem>
+          <para>To override default JPA behavior.</para>
+        </listitem>
+        <listitem>
+          <para>
+      To provide the JPA implementation with information that
+      it cannot glean from simply reflecting on the persistent class.
+      </para>
+        </listitem>
+      </orderedlist>
+      <para><indexterm><primary>annotations</primary></indexterm>
+  Persistence metadata is specified using either the Java 5 annotations 
+  defined in the <literal>javax.persistence</literal> package, XML
+  mapping files, or a mixture of both.  In the latter case, XML declarations
+  override conflicting annotations.  If you choose to use XML metadata, the 
+  XML files must be available at development and runtime, and must be 
+  discoverable via either of two strategies:
+  </para>
+      <orderedlist>
+        <listitem>
+          <para>
+      In a resource named <filename>orm.xml</filename> placed in
+      the <filename>META-INF</filename> directory of the classpath
+      or the jar archive containing your persistent classes.
+      </para>
+        </listitem>
+        <listitem>
+          <para>
+      Declared in your <link linkend="jpa_overview_persistence_xml"><filename>persistence.xml</filename></link> configuration file.  
+      In this case, each XML metadata file must be 
+      listed in a <literal>mapping-file</literal> element whose 
+      content is either a path to the given file or a resource 
+      location available to the class' class loader.
+      </para>
+        </listitem>
+      </orderedlist>
+      <para>
+  We describe the standard metadata annotations and XML equivalents throughout
+  this chapter.  The full schema for XML mapping files is available in
+  <xref linkend="jpa_overview_meta_xml"/>.
+  JPA also standardizes relational mapping metadata and named 
+  query metadata, which we discuss in <xref linkend="jpa_overview_mapping"/>
+  and <xref linkend="jpa_overview_query_named"/> respectively. 
+  </para>
+      <note>
+        <para>
+    OpenJPA defines many useful annotations beyond the standard set.  See
+    <xref linkend="ref_guide_meta_ejb"/> and 
+    <xref linkend="ref_guide_meta_ext"/> in the Reference Guide for details.
+    <!-- ### EJB -->
+    There are currently no XML equivalents for these extension annotations.
+    </para>
+      </note>
+      <mediaobject>
+        <imageobject>
+<!-- PNG image data, 553 x 580 (see README) -->
+          <imagedata fileref="img/jpa-meta-model.png" width="369"/>
+        </imageobject>
+      </mediaobject>
+      <para>
+  Through the course of this chapter, we will create the persistent object 
+  model above.
+  </para>
+      <section id="jpa_overview_meta_class">
+        <title>Class Metadata</title>
+        <para>
+    The following metadata annotations and XML elements apply to persistent
+    class declarations.
+    </para>
+        <section id="jpa_overview_meta_entity">
+          <title>Entity</title>
+          <indexterm zone="jpa_overview_meta_entity">
+            <primary>Entity</primary>
+            <secondary>annotation</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_entity">
+            <primary>metadata</primary>
+            <secondary>Entity</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_entity">
+            <primary>annotations</primary>
+            <secondary>Entity</secondary>
+          </indexterm>
+          <para>
+      The <classname>Entity</classname> annotation denotes an entity 
+      class.  All entity classes must have this annotation.  The 
+      <classname>Entity</classname> annotation takes one optional 
+      property:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: Name used to refer to the 
+          entity in queries. Must not be a reserved literal 
+          in JPQL.  Defaults to the unqualified name of the entity 
+          class.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      The equivalent XML element is <literal>entity</literal>.  It has
+      the following attributes:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>class</literal>: The entity class.  This attribute
+          is required.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>name</literal>: Named used to refer to the class in
+          queries.  See the name property above.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>access</literal>: The access type to use for the
+          class.  Must either be <literal>FIELD</literal> or
+          <literal>PROPERTY</literal>.  For details on access 
+          types, see <xref linkend="jpa_overview_meta_field"/>.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+        OpenJPA uses a process called <emphasis>enhancement</emphasis> to
+        modify the bytecode of entities for transparent
+        lazy loading and immediate dirty tracking.  See 
+        <xref linkend="ref_guide_pc_enhance"/> in the Reference Guide
+        for details on enhancement.
+        </para>
+          </note>
+        </section>
+        <section id="jpa_overview_meta_idclass">
+          <title>Id Class</title>
+          <indexterm zone="jpa_overview_meta_idclass">
+            <primary>IdClass</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_idclass">
+            <primary>metadata</primary>
+            <secondary>IdClass</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_idclass">
+            <primary>annotations</primary>
+            <secondary>IdClass</secondary>
+          </indexterm>
+          <para>
+      As we discussed in <xref linkend="jpa_overview_pc_identitycls"/>,
+      entities with multiple identity fields must use an <emphasis>
+      identity class</emphasis> to encapsulate their persistent identity.
+      The <classname>IdClass</classname> annotation specifies this class.
+      It accepts a single <classname>java.lang.Class</classname> value.
+      </para>
+          <para>
+      The equivalent XML element is <literal>id-class</literal>, which has
+      a single attribute:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>class</literal>: This required attribute lists
+          the class name for the identity class.
+          </para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_embeddablesuper">
+          <title>Mapped Superclass</title>
+          <indexterm zone="jpa_overview_meta_embeddablesuper">
+            <primary>MappedSuperclass</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embeddablesuper">
+            <primary>metadata</primary>
+            <secondary>MappedSuperclass</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embeddablesuper">
+            <primary>annotations</primary>
+            <secondary>MappedSuperclass</secondary>
+          </indexterm>
+          <para>
+      A <emphasis>mapped superclass</emphasis> is a non-entity
+      class that can define persistent state and mapping information for
+      entity subclasses.  Mapped superclasses are usually abstract.
+      Unlike true entities, you cannot query a mapped superclass, 
+      pass a mapped superclass instance to any 
+      <classname>EntityManager</classname> or <classname>Query</classname>
+      methods, or declare a persistent relation with a mapped 
+      superclass target.  
+      You denote a mapped superclass with the <classname>MappedSuperclass
+      </classname> marker annotation.
+      </para>
+          <para>  
+      The equivalent XML element is <literal>mapped-superclass</literal>.
+      It expects the following attributes:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>class</literal>: The entity class.  This attribute
+          is required.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>access</literal>: The access type to use for the
+          class.  Must either be <literal>FIELD</literal> or
+          <literal>PROPERTY</literal>.  For details on access 
+          types, see <xref linkend="jpa_overview_meta_field"/>.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+        OpenJPA allows you to query on mapped superclasses.  A
+        query on a mapped superclass will return all matching
+        subclass instances.  OpenJPA also allows you to declare relations
+        to mapped superclass types; however, you cannot query across
+        these relations.
+        </para>
+          </note>
+        </section>
+        <section id="jpa_overview_meta_embeddable">
+          <title>Embeddable</title>
+          <indexterm zone="jpa_overview_meta_embeddable">
+            <primary>Embeddable</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embeddable">
+            <primary>metadata</primary>
+            <secondary>Embeddable</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embeddable">
+            <primary>annotations</primary>
+            <secondary>Embeddable</secondary>
+          </indexterm>
+          <para>
+      The <classname>Embeddable</classname> annotation designates an 
+      embeddable persistent class.  Embeddable instances are stored as
+      part of the record of their owning instance.  All embeddable 
+      classes must have this annotation.
+      </para>
+          <para>
+      A persistent class can either be an entity or an embeddable class,
+      but not both.
+      </para>
+          <para>
+      The equivalent XML element is <literal>embeddable</literal>.
+      It understands the following attributes:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>class</literal>: The entity class.  This attribute
+          is required.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>access</literal>: The access type to use for the
+          class.  Must either be <literal>FIELD</literal> or
+          <literal>PROPERTY</literal>.  For details on access 
+          types, see <xref linkend="jpa_overview_meta_field"/>.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+        OpenJPA allows a persistent class to be both an entity and
+        an embeddable class.  Instances of the class will act as 
+        entites when persisted explicitly or assigned to non-embedded
+        fields of entities.  Instances will act as embedded values
+        when assigned to embedded fields of entities.
+        </para>
+            <para>
+        To signal that a class is both an entity and an embeddable class
+        in OpenJPA, simply add both the <literal>@Entity</literal> and the
+        <literal>@Embeddable</literal> annotations to the class.
+        </para>
+          </note>
+        </section>
+        <section id="jpa_overview_meta_entity_listeners">
+          <title>EntityListeners</title>
+          <indexterm zone="jpa_overview_meta_entity_listeners">
+            <primary>EntityListeners</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_entity_listeners">
+            <primary>entity-listeners</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_entity_listeners">
+            <primary>metadata</primary>
+            <secondary>EntityListeners</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_entity_listeners">
+            <primary>annotations</primary>
+            <secondary>EntityListeners</secondary>
+          </indexterm>
+          <para>
+      An entity may list its lifecycle event listeners
+      in the <classname>EntityListeners</classname> annotation.
+      This value of this annotation is an array of the listener 
+      <classname>Class</classname>es for the entity.
+      The equivalent XML element is <literal>entity-listeners</literal>.
+      For more details on entity listeners, see
+      <xref linkend="jpa_overview_pc_callbacks"/>.
+      </para>
+        </section>
+        <section id="jpa_overview_meta_classex">
+          <title>Example</title>
+          <para>
+      Here are the class declarations for our persistent object model,
+      annotated with the appropriate persistence metadata.  Note that
+      <classname>Magazine</classname> declares an identity class, and
+      that <classname>Document</classname> and <classname>Address
+      </classname> are a mapped superclass and an embeddable class, 
+      respectively. <classname>LifetimeSubscription</classname> and
+      <classname>TrialSubscription</classname> override the default
+      entity name to supply a shorter alias for use in queries.
+      </para>
+          <example id="jpa_overview_meta_classlisting">
+            <title>Class Metadata</title>
+            <programlisting format="linespecific">
+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
+{
+    ...
+}
+</programlisting>
+            <para>
+        The equivalent declarations in XML:
+        </para>
+            <programlisting format="linespecific">
+&lt;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"&gt;
+    &lt;mapped-superclass class="org.mag.subscribe.Document"&gt;
+        ...
+    &lt;/mapped-superclass&gt;
+    &lt;entity class="org.mag.Magazine"&gt;
+        &lt;id-class class="org.mag.Magazine$MagazineId"/&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.Article"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Company"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.pub.Author"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.Contract"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.LineItem"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.LifetimeSubscription" name="Lifetime"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;entity class="org.mag.subscribe.TrialSubscription" name="Trial"&gt;
+        ...
+    &lt;/entity&gt;
+    &lt;embeddable class="org.mag.pub.Address"&gt;
+        ...
+    &lt;/embeddable&gt;
+&lt;/entity-mappings&gt;
+</programlisting>
+          </example>
+        </section>
+      </section>
+      <section id="jpa_overview_meta_field">
+        <title>Field and Property Metadata</title>
+        <para>
+    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: <emphasis>field access</emphasis>, and
+    <emphasis>property access</emphasis>.  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 entity with XML metadata, set the <literal>access
+    </literal> attribute of your <literal>entity</literal> XML element to 
+    <literal>FIELD</literal>.  To use field access for an entity using
+    annotation metadata, simply place your metadata and mapping annotations
+    on your field declarations:
+    </para>
+        <programlisting format="linespecific">
+@ManyToOne
+private Company publisher;
+</programlisting>
+        <para><indexterm><primary>metadata</primary><secondary>property access</secondary></indexterm><indexterm><primary>persistent classes</primary><secondary>property access</secondary></indexterm><indexterm><primary>persistent properties</primary><seealso>persistent fields</seealso></indexterm>
+    Property access, on the other hand, retrieves and loads state through 
+    JavaBean "getter" and "setter" methods.  For a property 
+    <literal>p</literal> of type <literal>T</literal>, you must define the 
+    following getter method:
+    </para>
+        <programlisting format="linespecific">
+T getP ();
+</programlisting>
+        <para>
+    For boolean properties, this is also acceptable:
+    </para>
+        <programlisting format="linespecific">
+boolean isP ();
+</programlisting>
+        <para>
+    You must also define the following setter method:
+    </para>
+        <programlisting format="linespecific">
+void setP (T value);
+</programlisting>
+        <para>
+    To use property access, set your <literal>entity</literal> element's 
+    <literal>access</literal> attribute to <literal>PROPERTY</literal>, or
+    place your metadata and mapping annotations on the getter method:
+    </para>
+        <programlisting format="linespecific">
+@ManyToOne
+private Company getPublisher () { ... }
+
+private void setPublisher (Company publisher) { ... }
+</programlisting>
+        <warning>
+          <para>
+      When using property access, only the getter and setter method for
+      a property should ever access the underlying persistent field
+      directly.  Other methods, including internal business methods in
+      the persistent class, should go through the getter and setter 
+      methods when manipulating persistent state.
+      </para>
+          <para>
+      Also, take care when adding business logic to your 
+      getter and setter methods.  Consider that they are invoked by the 
+      persistence implementation to load and retrieve all persistent 
+      state; other side effects might not be desirable.
+      </para>
+        </warning>
+        <para>
+    Each class must use either field access or property access for all 
+    state; you cannot use both access types within the same class.  
+    Additionally, a subclass must use the same access type as its 
+    superclass.  
+    </para>
+        <para>
+    The remainder of this document uses the term
+    "persistent field" to refer to either a persistent field or a 
+    persistent property.
+    </para>
+        <section id="jpa_overview_meta_transient">
+          <title>Transient</title>
+          <indexterm zone="jpa_overview_meta_transient">
+            <primary>Transient</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_transient">
+            <primary>metadata</primary>
+            <secondary>Transient</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_transient">
+            <primary>annotations</primary>
+            <secondary>Transient</secondary>
+          </indexterm>
+          <para>
+      The <classname>Transient</classname> annotation specifies that a
+      field is non-persistent.  Use it to exclude fields from management
+      that would otherwise be persistent.  <classname>
+      Transient</classname> is a marker annotation only; it has no
+      properties.
+      </para>
+          <para>
+      The equivalent XML element is <literal>transient</literal>.  It
+      has a single attribute:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The transient field or property 
+          name.  This attribute is required.
+          </para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_id">
+          <title>Id</title>
+          <indexterm zone="jpa_overview_meta_id">
+            <primary>Id</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_id">
+            <primary>metadata</primary>
+            <secondary>Id</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_id">
+            <primary>annotations</primary>
+            <secondary>Id</secondary>
+          </indexterm>
+          <para>
+      Annotate your simple identity fields with <classname>Id</classname>.
+      This annotation has no properties.  We explore entity identity and 
+      identity fields in <xref linkend="jpa_overview_pc_id"/>.  
+      </para>
+          <para>
+      The equivalent XML element is <literal>id</literal>.  It has one 
+      required attribute:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the identity field or
+          property.
+          </para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_gen">
+          <title>Generated Value</title>
+          <indexterm zone="jpa_overview_meta_gen">
+            <primary>GeneratedValue</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_gen">
+            <primary>metadata</primary>
+            <secondary>GeneratedValue</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_gen">
+            <primary>annotations</primary>
+            <secondary>GeneratedValue</secondary>
+          </indexterm>
+          <para>
+      The previous section showed you how to declare your identity
+      fields with the <classname>Id</classname> annotation.  It is often
+      convenient to allow the persistence implementation to assign a 
+      unique value to your identity fields automatically.  JPA 
+      includes the the <classname>GeneratedValue</classname> 
+      annotation for this purpose.  You can only apply the <classname>
+      GeneratedValue</classname> annotation to numeric fields.  It has 
+      the following properties:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>GenerationType strategy</literal>: Enum value
+          specifying how to auto-generate the field value.
+          The <classname>GenerationType</classname> enum has the 
+          following values:
+          </para>
+              <itemizedlist>
+                <listitem>
+                  <para><literal>GeneratorType.AUTO</literal>: The default.
+              Assign the field a generated value, leaving the 
+              details to the JPA vendor.
+              </para>
+                </listitem>
+                <listitem>
+                  <para><literal>GenerationType.IDENTITY</literal>: The
+              database will assign an identity value on insert.
+              </para>
+                </listitem>
+                <listitem>
+                  <para><literal>GenerationType.SEQUENCE</literal>: Use a
+              datastore sequence to generate a field value.
+              </para>
+                </listitem>
+                <listitem>
+                  <para><literal>GenerationType.TABLE</literal>: Use a
+              sequence table to generate a field value.
+              </para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+            <listitem>
+              <para><literal>String generator</literal>: The name of a 
+          generator defined in mapping metadata.  We show you how
+          to define named generators in 
+          <xref linkend="jpa_overview_mapping_sequence"/>.
+          If the <classname>GenerationType</classname> is set but 
+          this property is unset, the JPA implementation 
+          uses appropriate defaults for the selected generation type.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      The equivalent XML element is <literal>generated-value</literal>,
+      which includes the following attributes:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>strategy</literal>: One of <literal>
+          TABLE</literal>, <literal>SEQUENCE</literal>, <literal>
+          IDENTITY</literal>, or <literal>AUTO</literal>, defaulting 
+          to <literal>AUTO</literal>.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>generator</literal>: Equivalent to the generator
+          property listed above.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <note>
+            <para>
+        OpenJPA allows you to use the <classname>GeneratedValue</classname>
+        annotation on any field, not just identity fields.
+        Before using the <literal>IDENTITY</literal> generation 
+        strategy, however, read 
+        <xref linkend="ref_guide_pc_oid_pkgen_autoinc"/>
+        in the Reference Guide.  
+        </para>
+            <para>
+        OpenJPA also offers two additional 
+        generator strategies for non-numeric fields, which you can 
+        access by setting <literal>strategy</literal> to 
+        <literal>AUTO</literal> (the default), and setting
+        the <literal>generator</literal> string to:
+        </para>
+            <itemizedlist>
+              <listitem>
+                <para><indexterm><primary>mapping metadata</primary><secondary>uuid-string</secondary></indexterm><indexterm><primary>uuid-string</primary></indexterm><literal>uuid-string</literal>: OpenJPA will generate a 
+            128-bit UUID unique
+            within the network, represented as a 16-character 
+            string.  For more information on UUIDs, see the IETF 
+            UUID draft specification at:
+            <ulink url="http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/"> 
+            http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/
+            </ulink></para>
+              </listitem>
+              <listitem>
+                <para><indexterm><primary>mapping metadata</primary><secondary>uuid-hex</secondary></indexterm><indexterm><primary>uuid-hex</primary></indexterm><literal>uuid-hex</literal>: Same as <literal>
+            uuid-string</literal>, but represents the UUID as
+            a 32-character hexadecimal string.
+            </para>
+              </listitem>
+            </itemizedlist>
+            <para>
+        These string constants are defined in
+        <ulink url="../../api/openjpa/persistence/Generator.html"><classname>org.apache.openjpa.persistence.Generator</classname></ulink>.
+        </para>
+          </note>
+        </section>
+        <section id="jpa_overview_meta_embedid">
+          <title>Embedded Id</title>
+          <indexterm zone="jpa_overview_meta_embedid">
+            <primary>EmbeddedId</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embedid">
+            <primary>metadata</primary>
+            <secondary>EmbeddedId</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embedid">
+            <primary>annotations</primary>
+            <secondary>EmbeddedId</secondary>
+          </indexterm>
+          <para>
+      If your entity has multiple identity values, you may declare 
+      multiple <literal>@Id</literal> fields, or you may declare a single 
+      <literal>@EmbeddedId</literal> field.  The type of a field 
+      annotated with <classname>EmbeddedId</classname> must be an
+      embeddable entity class.  The fields of this embeddable class are 
+      considered the identity values of the owning entity.  We explore 
+      entity identity and identity fields in 
+      <xref linkend="jpa_overview_pc_id"/>.  
+      </para>
+          <para>
+      The <classname>EmbeddedId</classname> annotation has no properties.
+      </para>
+          <para>
+      The equivalent XML element is <literal>embedded-id</literal>.  It 
+      has one required attribute:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the identity field or
+          property.
+          </para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_version">
+          <title>Version</title>
+          <indexterm zone="jpa_overview_meta_version">
+            <primary>Version</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_version">
+            <primary>metadata</primary>
+            <secondary>Version</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_version">
+            <primary>annotations</primary>
+            <secondary>Version</secondary>
+          </indexterm>
+          <para>
+      Use the <classname>Version</classname> annotation to designate a
+      version field.  <xref linkend="jpa_overview_pc_version"/> 
+      explained the importance of version fields to JPA.
+      This is a marker annotation; it has no properties.
+      </para>
+          <para>
+      The equivalent XML element is <literal>version</literal>, which 
+      has a single attribute:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the version field or
+          property.  This attribute is required.
+          </para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_basic">
+          <title>Basic</title>
+          <indexterm zone="jpa_overview_meta_basic">
+            <primary>Basic</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_basic">
+            <primary>metadata</primary>
+            <secondary>Basic</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_basic">
+            <primary>annotations</primary>
+            <secondary>Basic</secondary>
+          </indexterm>
+          <para><classname>Basic</classname> signifies a standard value persisted
+      as-is to the datastore.  You can use the <classname>Basic
+      </classname> annotation on persistent fields of the following types:
+      primitives, primitive wrappers,
+      <classname>java.lang.String</classname>,
+      <classname>byte[]</classname>, 
+      <classname>Byte[]</classname>,
+      <classname>char[]</classname>, 
+      <classname>Character[]</classname>,
+      <classname>java.math.BigDecimal</classname>,
+      <classname>java.math.BigInteger</classname>,
+      <classname>java.util.Date</classname>,
+      <classname>java.util.Calendar</classname>,
+      <classname>java.sql.Date</classname>, 
+      <classname>java.sql.Timestamp</classname>,
+      <classname>Enum</classname>s, and 
+      <classname>Serializable</classname> types.
+      </para>
+          <para><classname>Basic</classname> declares these properties:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+          field eagerly (<literal>FetchType.EAGER</literal>) or 
+          lazily (<literal>FetchType.LAZY</literal>).
+          Defaults to <literal>FetchType.EAGER</literal>.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean optional</literal>: Whether the datastore
+          allows null values.  Defaults to true.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      The equivalent XML element is <literal>basic</literal>.  It has
+      the following attributes:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+          This attribute is required.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>fetch</literal>: One of <literal>EAGER</literal>
+          or<literal>LAZY</literal>.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>optional</literal>: Boolean indicating whether the
+          field value may be null.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <section id="jpa_overview_meta_fetch">
+            <title>Fetch Type</title>
+            <indexterm zone="jpa_overview_meta_fetch">
+              <primary>eager fetching</primary>
+              <secondary>FetchType</secondary>
+            </indexterm>
+            <indexterm zone="jpa_overview_meta_fetch">
+              <primary>FetchType</primary>
+              <seealso>eager fetching</seealso>
+            </indexterm>
+            <indexterm zone="jpa_overview_meta_fetch">
+              <primary>metadata</primary>
+              <secondary>FetchType</secondary>
+            </indexterm>
+            <para>
+        Many metadata annotations in JPA have a 
+        <literal>fetch</literal> property.  This property can take
+        on one of two values: <literal>FetchType.EAGER</literal> or
+        <literal>FetchType.LAZY</literal>.  <literal>FetchType.EAGER
+        </literal> means that the field is loaded by the JPA
+        implementation before it returns the persistent object to you.
+        Whenever you retrieve an entity from a query or from the
+        <classname>EntityManager</classname>, you are guaranteed that
+        all of its eager fields are populated with datastore data.
+        </para>
+            <para><literal>FetchType.LAZY</literal> is a hint to the JPA runtime
+        that you want to defer loading of the field until you access it.
+        This is called <emphasis>lazy loading</emphasis>.  Lazy loading
+        is completely transparent; when you attempt to read the field
+        for the first time, the JPA runtime will load the value from the
+        datastore and populate the field automatically.  Lazy loading
+        is only a hint and not a directive because some JPA
+        implementations cannot lazy-load certain field types.
+        </para>
+            <para>
+        With a mix of eager and lazily-loaded fields, you can ensure
+        that commonly-used fields load efficiently, and that other
+        state loads transparently when accessed.  As you will see
+        in <xref linkend="jpa_overview_emfactory_perscontext"/>, 
+        you can also use eager fetching to ensure that entites have
+        all needed data loaded before they become <emphasis>detached
+        </emphasis> at the end of a persistence context. 
+        </para>
+            <note>
+              <para>
+          OpenJPA can lazy-load any field type.  OpenJPA also allows you
+          to dynamically change which fields are eagerly or lazily
+          loaded at runtime.  See <xref linkend="ref_guide_fetch"/>
+          in the Reference Guide for details.
+          </para>
+              <para>
+          The Reference Guide details OpenJPA's eager fetching
+          behavior in <xref linkend="ref_guide_perfpack_eager"/>.
+          </para>
+            </note>
+          </section>
+        </section>
+        <section id="jpa_overview_meta_embedded">
+          <title>Embedded</title>
+          <indexterm zone="jpa_overview_meta_embedded">
+            <primary>Embedded</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embedded">
+            <primary>metadata</primary>
+            <secondary>Embedded</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_embedded">
+            <primary>annotations</primary>
+            <secondary>Embedded</secondary>
+          </indexterm>
+          <para>
+      Use the <classname>Embedded</classname> marker annotation on 
+      embeddable field types.  Embedded fields are mapped as part of the 
+      datastore record of the declaring entity.  In our sample model, 
+      <classname>Author</classname> and <classname>Company</classname> 
+      each embed their <classname>Address</classname>, rather than 
+      forming a relation to an <classname>Address</classname> as a 
+      separate entity.
+      </para>
+          <para>
+      The equivalent XML element is <literal>embedded</literal>, which
+      expects a single attribute:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+          This attribute is required.
+          </para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_manytoone">
+          <title>Many To One</title>
+          <indexterm zone="jpa_overview_meta_manytoone">
+            <primary>ManyToOne</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_manytoone">
+            <primary>metadata</primary>
+            <secondary>ManyToOne</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_manytoone">
+            <primary>annotations</primary>
+            <secondary>ManyToOne</secondary>
+          </indexterm>
+          <para>
+      When an entity <literal>A</literal> references a single entity
+      <literal>B</literal>, and other <literal>A</literal>s might also
+      reference the same <literal>B</literal>, we say there is a 
+      <emphasis>many to one</emphasis> relation from 
+      <literal>A</literal> to <literal>B</literal>.
+      In our sample model, for example, each magazine has a reference to 
+      its publisher.  Multiple magazines might have the same publisher.
+      We say, then, that the <literal>Magazine.publisher</literal> field
+      is a many to one relation from magazines to publishers.
+      </para>
+          <para>
+      JPA indicates many to one relations between 
+      entities with the <classname>ManyToOne</classname> annotation.
+      This annotation has the following properties:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>Class targetEntity</literal>: The class of the
+          related entity type.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] cascade</literal>: Array of enum
+          values defining cascade behavior for this field.  We
+          explore cascades below.  Defaults to an empty array.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+          field eagerly (<literal>FetchType.EAGER</literal>) or 
+          lazily (<literal>FetchType.LAZY</literal>).
+          Defaults to <literal>FetchType.EAGER</literal>.
+          See <xref linkend="jpa_overview_meta_fetch"/> above
+          for details on fetch types.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean optional</literal>:  Whether the related
+          object must exist.  If <literal>false</literal>, this
+          field cannot be null.  Defaults to <literal>true</literal>.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      The equivalent XML element is <literal>many-to-one</literal>.  It
+      accepts the following attributes:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+          This attribute is required.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>target-entity</literal>: The class of the related
+          type.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>fetch</literal>: One of <literal>EAGER</literal>
+          or<literal>LAZY</literal>.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>optional</literal>: Boolean indicating whether the
+          field value may be null.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <section id="jpa_overview_meta_cascade">
+            <title>Cascade Type</title>
+            <indexterm zone="jpa_overview_meta_cascade">
+              <primary>CascadeType</primary>
+            </indexterm>
+            <indexterm zone="jpa_overview_meta_cascade">
+              <primary>metadata</primary>
+              <secondary>CascadeType</secondary>
+            </indexterm>
+            <para>
+        We introduce the JPA <classname>EntityManager
+        </classname> in <xref linkend="jpa_overview_em"/>.
+        The <classname>EntityManager</classname> has APIs to persist
+        new entities, remove (delete) existing entities,
+        refresh entity state from the datastore, and merge <emphasis>
+        detached</emphasis> entity state back into the persistence
+        context.  We explore all of these APIs in detail later in the 
+        overview.
+        </para>
+            <para>
+        When the <classname>EntityManager</classname> is performing the
+        above operations, you can instruct it to automatically cascade 
+        the operation to the entities held in a persistent field with
+        the <literal>cascade</literal> property of your metadata 
+        annotation.  This process is recursive.  The <literal>cascade
+        </literal> property accepts an array of <classname>CascadeType
+        </classname> enum values. 
+        </para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>CascadeType.PERSIST</literal>: When persisting
+            an entity, also persist the entities held in this field.
+            We suggest liberal application of this cascade rule, 
+            because if the <classname>EntityManager</classname>
+            finds a field that references a new entity
+            during flush, and the field does not use
+            <literal>CascadeType.PERSIST</literal>, it is an error.
+            </para>
+              </listitem>
+              <listitem>
+                <para><literal>CascadeType.REMOVE</literal>: When deleting
+            an entity, also delete the entities held in this field.
+            </para>
+              </listitem>
+              <listitem>
+                <para><literal>CascadeType.REFRESH</literal>: When refreshing
+            an entity, also refresh the entities held in this field.
+            </para>
+              </listitem>
+              <listitem>
+                <para><literal>CascadeType.MERGE</literal>: When merging
+            entity state, also merge the entities held in this 
+            field.
+            </para>
+              </listitem>
+            </itemizedlist>
+            <para><classname>CascadeType</classname> defines one additional value,
+        <literal>CascadeType.ALL</literal>, that acts as a shortcut for
+        all of the values above.  The following annotations are 
+        equivalent:
+        </para>
+            <programlisting format="linespecific">
+@ManyToOne(cascade={CascadeType.PERSIST,CascadeType.REMOVE,
+    CascadeType.REFRESH,CascadeType.MERGE})
+private Company publisher;
+</programlisting>
+            <programlisting format="linespecific">
+@ManyToOne(cascade=CascadeType.ALL)
+private Company publisher;
+</programlisting>
+            <para>
+        In XML, these enumeration constants are available as child 
+        elements of the <literal>cascade</literal> element.  The
+        <literal>cascade</literal> element is itself a child of  
+        <literal>many-to-one</literal>.  The following examples are 
+        equivalent:
+        </para>
+            <programlisting format="linespecific">
+&lt;many-to-one name="publisher"&gt;
+    &lt;cascade&gt;
+        &lt;cascade-persist/&gt;
+        &lt;cascade-merge/&gt;
+        &lt;cascade-remove/&gt;
+        &lt;cascade-refresh/&gt;
+    &lt;/cascade&gt;
+&lt;/many-to-one&gt;
+</programlisting>
+            <programlisting format="linespecific">
+&lt;many-to-one name="publisher"&gt;
+    &lt;cascade&gt;
+        &lt;cascade-all/&gt;
+    &lt;/cascade&gt;
+&lt;/many-to-one&gt;
+</programlisting>
+          </section>
+        </section>
+        <section id="jpa_overview_meta_onetomany">
+          <title>One To Many</title>
+          <indexterm zone="jpa_overview_meta_onetomany">
+            <primary>OneToMany</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_onetomany">
+            <primary>metadata</primary>
+            <secondary>OneToMany</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_onetomany">
+            <primary>annotations</primary>
+            <secondary>OneToMany</secondary>
+          </indexterm>
+          <para>
+      When an entity <literal>A</literal> references multiple
+      <literal>B</literal> entities, and no two <literal>A</literal>s 
+      reference the same <literal>B</literal>, we say there is a 
+      <emphasis>one to many</emphasis> relation from 
+      <literal>A</literal> to <literal>B</literal>.
+      </para>
+          <para>
+      One to many relations are the exact inverse of the many to one
+      relations we detailed in the preceding section.  In that
+      section, we said that the <literal>Magazine.publisher</literal> 
+      field is a many to one relation from magazines to publishers.  
+      Now, we see that the <literal>Company.mags</literal> field is 
+      the inverse - a one to many relation from publishers to 
+      magazines.  Each company may publish multiple magazines, but each
+      magazine can have only one publisher.
+      </para>
+          <para>
+      JPA indicates one to many relations between 
+      entities with the <classname>OneToMany</classname> annotation.
+      This annotation has the following properties:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>Class targetEntity</literal>: The class of the
+          related entity type.  This information is usually taken 
+          from the parameterized collection or map element type.  
+          You must supply it explicitly, however, if your field isn't
+          a parameterized type.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>String mappedBy</literal>: Names the many to one
+          field in the related entity that maps this bidirectional 
+          relation.  We explain bidirectional relations below.
+          Leaving this property unset signals that this is a standard 
+          unidirectional relation.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] cascade</literal>: Array of enum
+          values defining cascade behavior for the collection 
+          elements.  We explore cascades above in
+          <xref linkend="jpa_overview_meta_cascade"/>.  Defaults to 
+          an empty array.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+          field eagerly (<literal>FetchType.EAGER</literal>) or 
+          lazily (<literal>FetchType.LAZY</literal>).
+          Defaults to <literal>FetchType.LAZY</literal>.
+          See <xref linkend="jpa_overview_meta_fetch"/> above
+          for details on fetch types.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      The equivalent XML element is <literal>one-to-many</literal>, which
+      includes the following attributes:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+          This attribute is required.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>target-entity</literal>: The class of the related
+          type.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>fetch</literal>: One of <literal>EAGER</literal>
+          or<literal>LAZY</literal>.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>mapped-by</literal>: The name of the field or 
+          property that owns the relation.  See 
+          <xref linkend="jpa_overview_meta_field"/>.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      You may also nest the <literal>cascade</literal> element within
+      a <literal>one-to-many</literal> element.
+      </para>
+          <section id="jpa_overview_meta_mappedby">
+            <title>Bidirectional Relations</title>
+            <indexterm zone="jpa_overview_meta_mappedby">
+              <primary>bidirectional relations</primary>
+            </indexterm>
+            <indexterm zone="jpa_overview_meta_mappedby">
+              <primary>mappedBy</primary>
+              <seealso>mapping metadata</seealso>
+            </indexterm>
+            <indexterm zone="jpa_overview_meta_mappedby">
+              <primary>mapping metadata</primary>
+              <seealso>mappedBy property</seealso>
+            </indexterm>
+            <para>
+        When two fields are logical inverses of each other, they form 
+        a <emphasis>bidirectional relation</emphasis>.  Our model 
+        contains two bidirectional relations: 
+        <literal>Magazine.publisher</literal> and 
+        <literal>Company.mags</literal> form one bidirectional relation,
+        and <literal>Article.authors</literal> and 
+        <literal>Author.articles</literal> form the other.  In both
+        cases, there is a clear link between the two fields that form
+        the relationship.  A magazine refers to its publisher while 
+        the publisher refers to all its published magazines.  An
+        article refers to its authors while each author refers to her
+        written articles.
+        </para>
+            <para>
+        When the two fields of a bidirectional relation share the same 
+        datastore mapping, JPA formalizes the 
+        connection with the <literal>mappedBy</literal> property. 
+        Marking <literal>Company.mags</literal> as <literal>mappedBy
+        </literal> <literal>Magazine.publisher</literal> means two
+        things:
+        </para>
+            <orderedlist>
+              <listitem>
+                <para><literal>Company.mags</literal> uses the datastore
+            mapping for <literal>Magazine.publisher</literal>, but
+            inverses it.  In fact, it is illegal to specify 
+            any additional mapping information when you use the
+            <literal>mappedBy</literal> property.  All mapping
+            information is read from the referenced field.
+            We explore mapping in depth in 
+            <xref linkend="jpa_overview_mapping"/>.
+            </para>
+              </listitem>
+              <listitem>
+                <para><literal>Magazine.publisher</literal> is the
+            "owner" of the relation.  The field that specifies the
+            mapping data is always the owner.  This means that
+            changes to the <literal>Magazine.publisher</literal>
+            field are reflected in the datastore, while changes to
+            the <literal>Company.mags</literal> field alone are
+            not.  Changes to <literal>Company.mags</literal> may
+            still affect the JPA implementation's 
+            cache, however.  Thus, it is very important that you 
+            keep your object model consistent by properly 
+            maintaining both sides of your bidirectional relations 
+            at all times.
+            </para>
+              </listitem>
+            </orderedlist>
+            <para>
+        You should always take advantage of the <literal>mappedBy
+        </literal> property rather than mapping each field of a 
+        bidirectional relation independently.  Failing to do so may
+        result in the JPA implementation trying to update 
+        the database with conflicting data.  Be careful to only mark 
+        one side of the relation as <literal>mappedBy</literal>, 
+        however.  One side has to actually do the mapping!
+        </para>
+            <note>
+              <para>
+          You can configure OpenJPA to automatically synchronize both
+          sides of a bidirectional relation, or to perform various
+          actions when it detects inconsistent relations.  See
+          <xref linkend="ref_guide_inverses"/> in the Reference Guide
+          for details.
+          </para>
+            </note>
+          </section>
+        </section>
+        <section id="jpa_overview_meta_onetoone">
+          <title>One To One</title>
+          <indexterm zone="jpa_overview_meta_onetoone">
+            <primary>OneToOne</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_onetoone">
+            <primary>metadata</primary>
+            <secondary>OneToOne</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_onetoone">
+            <primary>annotations</primary>
+            <secondary>OneToOne</secondary>
+          </indexterm>
+          <para>
+      When an entity <literal>A</literal> references a single entity
+      <literal>B</literal>, and no other <literal>A</literal>s can 
+      reference the same <literal>B</literal>, we say there is a 
+      <emphasis>one to one</emphasis> relation between  
+      <literal>A</literal> and <literal>B</literal>.
+      In our sample model, <classname>Magazine</classname> has a one to
+      one relation to <classname>Article</classname> through the 
+      <literal>Magazine.coverArticle</literal> field.
+      No two magazines can have the same cover article.
+      </para>
+          <para>
+      JPA indicates one to one relations between 
+      entities with the <classname>OneToOne</classname> annotation.
+      This annotation has the following properties:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>Class targetEntity</literal>: The class of the
+          related entity type.  This information is usually taken 
+          from the field type.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>String mappedBy</literal>: Names the field in the
+          related entity that maps this bidirectional relation.  We
+          explain bidirectional relations in
+          <xref linkend="jpa_overview_meta_mappedby"/> above.  
+          Leaving this property unset signals that this is a standard 
+          unidirectional relation.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] cascade</literal>: Array of enum
+          values defining cascade behavior for this field.  We
+          explore cascades in 
+          <xref linkend="jpa_overview_meta_cascade"/> above.  
+          Defaults to an empty array.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+          field eagerly (<literal>FetchType.EAGER</literal>) or 
+          lazily (<literal>FetchType.LAZY</literal>).
+          Defaults to <literal>FetchType.EAGER</literal>.
+          See <xref linkend="jpa_overview_meta_fetch"/> above
+          for details on fetch types.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>boolean optional</literal>:  Whether the related
+          object must exist.  If <literal>false</literal>, this
+          field cannot be null.  Defaults to <literal>true</literal>.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      The equivalent XML element is <literal>one-to-one</literal> which
+      understands the following attributes:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+          This attribute is required.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>target-entity</literal>: The class of the related
+          type.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>fetch</literal>: One of <literal>EAGER</literal>
+          or<literal>LAZY</literal>.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>mapped-by</literal>: The field that owns the 
+          relation.  See <xref linkend="jpa_overview_meta_field"/>.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      You may also nest the <literal>cascade</literal> element within
+      a <literal>one-to-one</literal> element.
+      </para>
+        </section>
+        <section id="jpa_overview_meta_manytomany">
+          <title>Many To Many</title>
+          <indexterm zone="jpa_overview_meta_manytomany">
+            <primary>ManyToMany</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_manytomany">
+            <primary>metadata</primary>
+            <secondary>ManyToMany</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_manytomany">
+            <primary>annotations</primary>
+            <secondary>ManyToMany</secondary>
+          </indexterm>
+          <para>
+      When an entity <literal>A</literal> references multiple 
+      <literal>B</literal> entities, and other <literal>A</literal>s 
+      might reference some of the same <literal>B</literal>s, we say 
+      there is a <emphasis>many to many</emphasis> relation between 
+      <literal>A</literal> and <literal>B</literal>.
+      In our sample model, for example, each article has a reference to 
+      all the authors that contributed to the article.  Other articles
+      might have some of the same authors.
+      We say, then, that <classname>Article</classname> and 
+      <classname>Author</classname> have a many to many relation
+      through the <literal>Article.authors</literal> field.  
+      </para>
+          <para>
+      JPA indicates many to many relations between 
+      entities with the <classname>ManyToMany</classname> annotation.
+      This annotation has the following properties:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>Class targetEntity</literal>: The class of the
+          related entity type.  This information is usually taken 
+          from the parameterized collection or map element type.  
+          You must supply it explicitly, however, if your field 
+          isn't a parameterized type.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>String mappedBy</literal>: Names the many to many
+          field in the related entity that maps this 
+          bidirectional relation.  
+          We explain bidirectional relations in
+          <xref linkend="jpa_overview_meta_mappedby"/> above.  
+          Leaving this property unset signals that this is a standard 
+          unidirectional relation.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>CascadeType[] cascade</literal>: Array of enum
+          values defining cascade behavior for the collection 
+          elements.  We explore cascades above in
+          <xref linkend="jpa_overview_meta_cascade"/>.  Defaults to 
+          an empty array.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>FetchType fetch</literal>: Whether to load the
+          field eagerly (<literal>FetchType.EAGER</literal>) or 
+          lazily (<literal>FetchType.LAZY</literal>).
+          Defaults to <literal>FetchType.LAZY</literal>.
+          See <xref linkend="jpa_overview_meta_fetch"/> above
+          for details on fetch types.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      The equivalent XML element is <literal>many-to-many</literal>.  It
+      accepts the following attributes:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field or property.
+          This attribute is required.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>target-entity</literal>: The class of the related
+          type.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>fetch</literal>: One of <literal>EAGER</literal>
+          or<literal>LAZY</literal>.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>mapped-by</literal>: The field that owns the 
+          relation.  See <xref linkend="jpa_overview_meta_field"/>.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      You may also nest the <literal>cascade</literal> element within
+      a <literal>many-to-many</literal> element.
+      </para>
+        </section>
+        <section id="jpa_overview_meta_orderby">
+          <title>Order By</title>
+          <indexterm zone="jpa_overview_meta_orderby">
+            <primary>OrderBy</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_orderby">
+            <primary>metadata</primary>
+            <secondary>OrderBy</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_orderby">
+            <primary>annotations</primary>
+            <secondary>OrderBy</secondary>
+          </indexterm>
+          <para>
+      Datastores such as relational databases do not preserve the order
+      of records.  Your persistent <classname>List</classname> fields 
+      might be ordered one way the first time you retrieve an object from
+      the datastore, and a completely different way the next.  To ensure 
+      consistent ordering of collection fields, you must use the 
+      <classname>OrderBy</classname> annotation.  The <classname>OrderBy
+      </classname> annotation's value is a string defining the order of 
+      the collection elements.  An empty value means to sort on the
+      identity value(s) of the elements in ascending order.  Any 
+      other value must be of the form:  
+      </para>
+          <programlisting format="linespecific">
+&lt;field name&gt;[ ASC|DESC][, ...]
+</programlisting>
+          <para>
+      Each <literal>&lt;field name&gt;</literal> is the name of a 
+      persistent field in the collection's element type.  You can 
+      optionally follow each field by the keyword <literal>ASC</literal>
+      for ascending order, or <literal>DESC</literal> for descending 
+      order.  If the direction is omitted, it defaults to ascending.
+      </para>
+          <para>
+      The equivalent XML element is <literal>order-by</literal> which
+      can be listed as a sub-element of the <literal>one-to-many</literal>
+      or <literal>many-to-many</literal> elements.  The text within this
+      element is parsed as the order by string.
+      </para>
+          <note>
+            <para>
+        OpenJPA expands the available ordering syntax.  See
+        <xref linkend="order-by"/> in the Reference Guide for details.
+        </para>
+          </note>
+        </section>
+        <section id="jpa_overview_meta_mapkey">
+          <title>Map Key</title>
+          <indexterm zone="jpa_overview_meta_mapkey">
+            <primary>MapKey</primary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_mapkey">
+            <primary>metadata</primary>
+            <secondary>MapKey</secondary>
+          </indexterm>
+          <indexterm zone="jpa_overview_meta_mapkey">
+            <primary>annotations</primary>
+            <secondary>MapKey</secondary>
+          </indexterm>
+          <para>
+      JPA supports persistent <classname>Map</classname> fields through
+      either a <link linkend="jpa_overview_meta_onetomany"><classname>
+      OneToMany</classname></link> or
+      <link linkend="jpa_overview_meta_manytomany"><classname>ManyToMany
+      </classname></link> association.  The related entities form the
+      map values.  JPA derives the map keys by extracting a field 
+      from each entity value.  The <classname>MapKey</classname> 
+      annotation designates the field that is used as the key.
+      It has the following properties:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>String name</literal>: The name of a field in
+          the related entity class to use as the map key.  If no
+          name is given, defaults to the identity field of the
+          related entity class.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      The equivalent XML element is <literal>map-key</literal> which
+      can be listed as a sub-element of the <literal>one-to-many</literal>
+      or <literal>many-to-many</literal> elements.  The <literal>map-key
+      </literal> element has the following attributes:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>name</literal>: The name of the field in
+                    the related entity class to use as the map key.
+          </para>
+            </listitem>
+          </itemizedlist>
+        </section>
+        <section id="jpa_overview_meta_fielddefaults">
+          <title>Persistent Field Defaults</title>
+          <para>
+      In the absence of any of the annotations above, JPA
+      defines the following default behavior for declared fields:
+      </para>
+          <orderedlist>
+            <listitem>
+              <para>
+          Fields declared <literal>static, transient</literal>, 
+          or <literal>final</literal> default to non-persistent.
+          </para>
+            </listitem>
+            <listitem>
+              <para>
+          Fields of any primitive type, primitive wrapper type,
+          <classname>java.lang.String</classname>,
+          <classname>byte[]</classname>,
+          <classname>Byte[]</classname>,
+          <classname>char[]</classname>,
+          <classname>Character[]</classname>,
+          <classname>java.math.BigDecimal</classname>,
+          <classname>java.math.BigInteger</classname>,
+          <classname>java.util.Date</classname>,
+          <classname>java.util.Calendar</classname>,
+          <classname>java.sql.Date</classname>,
+          <classname>java.sql.Timestamp</classname>,
+          or any <classname>Serializable</classname> type
+          default to persistent, as 
+          if annotated with <link linkend="jpa_overview_meta_basic"><literal>@Basic</literal></link>.
+          </para>
+            </listitem>
+            <listitem>
+              <para>
+          Fields of an embeddable type default to persistent, as
+          if annotated with 
+          <link linkend="jpa_overview_meta_embedded"><literal>
+          @Embedded</literal></link>.
+          </para>
+            </listitem>
+            <listitem>
+              <para>All other fields default to non-persistent.</para>
+            </listitem>
+          </orderedlist>
+          <para>
+      Note that according to these defaults, all relations between
+      entities must be annotated explicitly.  Without an annotation,
+      a relation field will default to serialized storage if the
+      related entity type is serializable, or will default to being 
+      non-persistent if not.
+      </para>
+        </section>
+      </section>
+      <section id="jpa_overview_meta_xml">
+        <title>XML Schema</title>
+        <indexterm>
+          <primary>metadata</primary>
+          <secondary>XSD</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>JPA</primary>
+          <secondary>metadata</secondary>
+          <tertiary>XML</tertiary>
+          <seealso>metadata</seealso>
+        </indexterm>
+        <para>
+    We present the complete XML schema below.  Many of the elements relate
+    to object/relational mapping rather than metadata; these elements are
+    discussed in <xref linkend="jpa_overview_mapping"/>.
+    </para>
+        <programlisting format="linespecific">
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;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="1.0"&gt;
+
+  &lt;xsd:annotation&gt;
+    &lt;xsd:documentation&gt;
+      @(#)orm_1_0.xsd 1.0  Feb 14 2006
+    &lt;/xsd:documentation&gt;
+  &lt;/xsd:annotation&gt;
+  &lt;xsd:annotation&gt;
+     &lt;xsd:documentation&gt;
+
+       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.
+
+     &lt;/xsd:documentation&gt;
+  &lt;/xsd:annotation&gt;
+
+  &lt;xsd:complexType name="emptyType"/&gt;
+
+  &lt;xsd:simpleType name="versionType"&gt;
+    &lt;xsd:restriction base="xsd:token"&gt;
+      &lt;xsd:pattern value="[0-9]+(\.[0-9]+)*"/&gt;
+    &lt;/xsd:restriction&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:element name="entity-mappings"&gt;
+    &lt;xsd:complexType&gt;
+      &lt;xsd:annotation&gt;
+        &lt;xsd:documentation&gt;
+
+        The entity-mappings element is the root element of an 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 or named-native-query
+        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.
+
+        &lt;/xsd:documentation&gt;
+      &lt;/xsd:annotation&gt;
+      &lt;xsd:sequence&gt;
+        &lt;xsd:element name="description" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="persistence-unit-metadata" 
+                     type="orm:persistence-unit-metadata"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="package" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="schema" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="catalog" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="access" type="orm:access-type"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="sequence-generator" type="orm:sequence-generator"
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="table-generator" type="orm:table-generator" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="named-query" type="orm:named-query" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="named-native-query" type="orm:named-native-query"
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="sql-result-set-mapping" 
+                     type="orm:sql-result-set-mapping" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="mapped-superclass" type="orm:mapped-superclass" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="entity" type="orm:entity" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="embeddable" type="orm:embeddable" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;/xsd:sequence&gt;
+      &lt;xsd:attribute name="version" type="orm:versionType" 
+                     fixed="1.0" use="required"/&gt;
+    &lt;/xsd:complexType&gt;
+  &lt;/xsd:element&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="persistence-unit-metadata"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        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 then 
+        the complete set of mapping metadata for the persistence unit 
+        is contained in the XML mapping files for the persistence unit.
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="xml-mapping-metadata-complete" type="orm:emptyType"
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="persistence-unit-defaults" 
+                   type="orm:persistence-unit-defaults"
+                   minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="persistence-unit-defaults"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        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 or secondary tables
+            that apply to the persistence unit
+        catalog - Used as the catalog for all tables or secondary tables
+            that apply to the persistence unit
+        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 entity relationships of the persistence unit
+        entity-listeners - List of default entity listeners to be invoked 
+            on each entity in the persistence unit. 
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+        &lt;xsd:element name="schema" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="catalog" type="xsd:string"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="access" type="orm:access-type"
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="cascade-persist" type="orm:emptyType" 
+                     minOccurs="0"/&gt;
+        &lt;xsd:element name="entity-listeners" type="orm:entity-listeners"
+                     minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="entity"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        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 "";
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="description" type="xsd:string" minOccurs="0"/&gt;
+      &lt;xsd:element name="table" type="orm:table" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="secondary-table" type="orm:secondary-table" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="primary-key-join-column" 
+                   type="orm:primary-key-join-column" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="id-class" type="orm:id-class" minOccurs="0"/&gt;
+      &lt;xsd:element name="inheritance" type="orm:inheritance" minOccurs="0"/&gt;
+      &lt;xsd:element name="discriminator-value" type="orm:discriminator-value" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="discriminator-column" 
+                   type="orm:discriminator-column" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="sequence-generator" type="orm:sequence-generator" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="table-generator" type="orm:table-generator" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="named-query" type="orm:named-query" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="named-native-query" type="orm:named-native-query" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="sql-result-set-mapping" 
+                   type="orm:sql-result-set-mapping" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="exclude-default-listeners" type="orm:emptyType" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="exclude-superclass-listeners" type="orm:emptyType" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="entity-listeners" type="orm:entity-listeners" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-persist" type="orm:post-persist" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-update" type="orm:post-update" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-load" type="orm:post-load" minOccurs="0"/&gt;
+      &lt;xsd:element name="attribute-override" type="orm:attribute-override" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="association-override" 
+                   type="orm:association-override"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="attributes" type="orm:attributes" minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="name" type="xsd:string"/&gt;
+    &lt;xsd:attribute name="class" type="xsd:string" use="required"/&gt;
+    &lt;xsd:attribute name="access" type="orm:access-type"/&gt;
+    &lt;xsd:attribute name="metadata-complete" type="xsd:boolean"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="attributes"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        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.
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:choice&gt;
+        &lt;xsd:element name="id" type="orm:id" 
+                     minOccurs="0" maxOccurs="unbounded"/&gt;
+        &lt;xsd:element name="embedded-id" type="orm:embedded-id" 
+                     minOccurs="0"/&gt;
+      &lt;/xsd:choice&gt;
+      &lt;xsd:element name="basic" type="orm:basic"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="version" type="orm:version"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="many-to-one" type="orm:many-to-one"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="one-to-many" type="orm:one-to-many"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="one-to-one" type="orm:one-to-one"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="many-to-many" type="orm:many-to-many" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="embedded" type="orm:embedded"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+      &lt;xsd:element name="transient" type="orm:transient"
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:simpleType name="access-type"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        This element determines how the persistence provider accesses the
+        state of an entity or embedded object.
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:restriction base="xsd:token"&gt;
+      &lt;xsd:enumeration value="PROPERTY"/&gt;
+      &lt;xsd:enumeration value="FIELD"/&gt;
+    &lt;/xsd:restriction&gt;
+  &lt;/xsd:simpleType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="entity-listeners"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({TYPE}) @Retention(RUNTIME)
+        public @interface EntityListeners {
+          Class[] value();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="entity-listener" type="orm:entity-listener" 
+                   minOccurs="0" maxOccurs="unbounded"/&gt;
+    &lt;/xsd:sequence&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="entity-listener"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        Defines an entity listener to be invoked at lifecycle events
+        for the entities that list this listener.
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:sequence&gt;
+      &lt;xsd:element name="pre-persist" type="orm:pre-persist" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-persist" type="orm:post-persist" 
+                   minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-remove" type="orm:pre-remove" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-remove" type="orm:post-remove" minOccurs="0"/&gt;
+      &lt;xsd:element name="pre-update" type="orm:pre-update" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-update" type="orm:post-update" minOccurs="0"/&gt;
+      &lt;xsd:element name="post-load" type="orm:post-load" minOccurs="0"/&gt;
+    &lt;/xsd:sequence&gt;
+    &lt;xsd:attribute name="class" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="pre-persist"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PrePersist {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="post-persist"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PostPersist {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="pre-remove"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PreRemove {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="post-remove"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PostRemove {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="pre-update"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PreUpdate {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="post-update"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PostUpdate {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="post-load"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({METHOD}) @Retention(RUNTIME)
+        public @interface PostLoad {}
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;
+    &lt;xsd:attribute name="method-name" type="xsd:string" use="required"/&gt;
+  &lt;/xsd:complexType&gt;
+
+  &lt;!-- **************************************************** --&gt;
+
+  &lt;xsd:complexType name="query-hint"&gt;
+    &lt;xsd:annotation&gt;
+      &lt;xsd:documentation&gt;
+
+        @Target({}) @Retention(RUNTIME) 
+        public @interface QueryHint {
+          String name();
+          String value();
+        }
+
+      &lt;/xsd:documentation&gt;
+    &lt;/xsd:annotation&gt;

[... 1389 lines stripped ...]


Mime
View raw message