openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From awh...@apache.org
Subject svn commit: r434517 [18/23] - in /incubator/openjpa/trunk: openjpa-kernel/src/main/java/org/apache/openjpa/meta/ openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/ openjpa-project/src/doc/manual/
Date Thu, 24 Aug 2006 20:41:14 GMT
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_meta.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_meta.xml?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_meta.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_meta.xml Thu Aug 24 13:41:12 2006
@@ -1,953 +1,1054 @@
-
-    <chapter id="ref_guide_meta">
-      <title>Metadata</title>
-      <para>
-  The JPA Overview covers JPA metadata in 
-  <xref linkend="jpa_overview_meta"/>.
-  This chapter discusses OpenJPA's extensions to standard JPA metadata.
-  </para>
-      <section id="ref_guide_meta_factory">
-        <title>Metadata Factory</title>
+<chapter id="ref_guide_meta">
+    <title>
+        Metadata
+    </title>
+    <para>
+The JPA Overview covers JPA metadata in <xref linkend="jpa_overview_meta">
+</xref>. This chapter discusses OpenJPA's extensions to standard JPA metadata.
+    </para>
+    <section id="ref_guide_meta_factory">
+        <title>
+            Metadata Factory
+        </title>
         <indexterm zone="ref_guide_meta_factory">
-          <primary>metadata</primary>
-          <secondary>loading and storing</secondary>
-          <see>MetaDataFactory</see>
+            <primary>
+                metadata
+            </primary>
+            <secondary>
+                loading and storing
+            </secondary>
+            <see>
+                MetaDataFactory
+            </see>
         </indexterm>
         <para>
-    The <link linkend="openjpa.MetaDataFactory"><literal>openjpa.MetaDataFactory
-    </literal></link> configuration property controls metadata loading and
-    storing.  This property takes a plugin string (see 
-    <xref linkend="ref_guide_conf_plugins"/>) describing
-    a concrete <ulink url="../apidocs/org/apache/openjpa/meta/MetaDataFactory.html"><classname>org.apache.openjpa.meta.MetaDataFactory</classname></ulink> implementation.
-    A metadata factory can load mapping information as well as persistence 
-    metadata, or it can leave mapping information to a separate 
-    <emphasis>mapping factory</emphasis> (see 
-    <xref linkend="ref_guide_mapping_factory"/>).  
-    OpenJPA recognizes the following built-in metadata factories:
-    </para>
-        <itemizedlist>
-          <listitem>
-            <para><literal>jpa</literal>: Standard JPA metadata.  
-        This is an alias for the 
-        <ulink url="../apidocs/org/apache/openjpa/persistence/PersistenceMetaDataFactory.html"><classname>
-        org.apache.openjpa.persistence.PersistenceMetaDataFactory</classname></ulink>.
+The <link linkend="openjpa.MetaDataFactory"><literal>openjpa.MetaDataFactory
+</literal></link> configuration property controls metadata loading and storing.
+This property takes a plugin string (see <xref linkend="ref_guide_conf_plugins">
+</xref>) describing a concrete
+<ulink url="../apidocs/org/apache/openjpa/meta/MetaDataFactory.html">
+<classname>org.apache.openjpa.meta.MetaDataFactory</classname></ulink>
+implementation. A metadata factory can load mapping information as well as
+persistence metadata, or it can leave mapping information to a separate
+<emphasis>mapping factory</emphasis> (see
+<xref linkend="ref_guide_mapping_factory"></xref> ). OpenJPA recognizes the
+following built-in metadata factories:
         </para>
-          </listitem>
+        <itemizedlist>
+            <listitem>
+                <para>
+<literal>jpa</literal>: Standard JPA metadata. This is an alias for the
+<ulink url="../apidocs/org/apache/openjpa/persistence/PersistenceMetaDataFactory.html">
+<classname> org.apache.openjpa.persistence.PersistenceMetaDataFactory
+</classname></ulink>.
+                </para>
+            </listitem>
         </itemizedlist>
         <para>
-    The standard metadata factories all accept the following properties for
-    locating persistent classes.  Each property represents a different 
-    mechanism for locating persistent types; you can choose the mechanism or
-    combination of mechanisms that are most convenient.  See 
-    <xref linkend="ref_guide_pc_pcclasses"/> for a discussion of when it
-    is necessary to list your persistent classes. 
-    </para>
-        <itemizedlist>
-          <listitem>
-            <para><literal>Types</literal>: A semicolon-separated list of 
-        fully-qualified persistent class names.
-        </para>
-          </listitem>
-          <listitem>
-            <para><literal>Resources</literal>: A semicolon-separated list of
-        resource paths to metadata files or jar archives.  
-        Each jar archive will be scanned for 
-        <phrase>annotated JPA entities</phrase>
-        
-        
-        .
+The standard metadata factories all accept the following properties for locating
+persistent classes. Each property represents a different mechanism for locating
+persistent types; you can choose the mechanism or combination of mechanisms that
+are most convenient. See <xref linkend="ref_guide_pc_pcclasses"></xref> for a
+discussion of when it is necessary to list your persistent classes.
         </para>
-          </listitem>
-          <listitem>
-            <para><literal>URLs</literal>: A semicolon-separated list of URLs
-        of metadata files or jar archives.  
-        Each jar archive will be scanned for 
-        <phrase>annotated JPA entities</phrase>
-        
-        
-        .
-        </para>
-          </listitem>
-          <listitem>
-            <para><literal>ClasspathScan</literal>: A semicolon-separated list of
-        directories or jar archives listed in your classpath.
-        Each directory and jar archive will be scanned for 
-        <phrase>annotated JPA entities</phrase>
-        
-        
-        .
-        </para>
-          </listitem>
+        <itemizedlist>
+            <listitem>
+                <para>
+<literal>Types</literal>: A semicolon-separated list of fully-qualified
+persistent class names.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+<literal>Resources</literal>: A semicolon-separated list of resource paths to
+metadata files or jar archives. Each jar archive will be scanned for <phrase>
+annotated JPA entities</phrase>.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+<literal>URLs</literal>: A semicolon-separated list of URLs of metadata files
+or jar archives. Each jar archive will be scanned for <phrase>annotated JPA
+entities</phrase>.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+<literal>ClasspathScan</literal>: A semicolon-separated list of directories or
+jar archives listed in your classpath. Each directory and jar archive will be
+scanned for <phrase>annotated JPA entities</phrase>.
+                </para>
+            </listitem>
         </itemizedlist>
         <example id="ref_guide_meta_stdfactoryex">
-          <title>Setting a Standard Metadata Factory</title>
-          <programlisting format="linespecific">
+            <title>
+                Setting a Standard Metadata Factory
+            </title>
+<programlisting>
 &lt;property name="openjpa.MetaDataFactory" value="jpa"/&gt;
 </programlisting>
         </example>
         <example id="ref_guide_meta_customfactoryex">
-          <title>Setting a Custom Metadata Factory</title>
-          <programlisting format="linespecific">
+            <title>
+                Setting a Custom Metadata Factory
+            </title>
+<programlisting>
 &lt;property name="openjpa.MetaDataFactory" value="com.xyz.CustomMetaDataFactory"/&gt;
 </programlisting>
         </example>
-      </section>
-      <section id="ref_guide_meta_ejb">
-        <title>Additional JPA Metadata</title>
-        <indexterm zone="ref_guide_meta_ejb">
-          <primary>metadata</primary>
-          <secondary>JPA additions</secondary>
+    </section>
+    <section id="ref_guide_meta_jpa">
+        <title>
+            Additional JPA Metadata
+        </title>
+        <indexterm zone="ref_guide_meta_jpa">
+            <primary>
+                metadata
+            </primary>
+            <secondary>
+                JPA additions
+            </secondary>
         </indexterm>
         <para>
-    This section describes OpenJPA's core additions to standard entity
-    metadata.  We present the object-relational mapping syntax to
-    support these additions in <xref linkend="ref_guide_mapping_ejb"/>.
-    Finally, <xref linkend="ref_guide_meta_ext"/> covers additional 
-    extensions to  JPA metadata that allow you to access auxiliary
-    OpenJPA features.
-    </para>
+This section describes OpenJPA's core additions to standard entity metadata. We
+present the object-relational mapping syntax to support these additions in
+<xref linkend="ref_guide_mapping_jpa"></xref>. Finally,
+<xref linkend="ref_guide_meta_ext"></xref> covers additional extensions to JPA
+metadata that allow you to access auxiliary OpenJPA features.
+        </para>
         <section id="ref_guide_meta_jpa_datastoreid">
-          <title>Datastore Identity</title>
-          <indexterm zone="ref_guide_meta_jpa_datastoreid">
-            <primary>identity</primary>
-            <secondary>datastore</secondary>
-          </indexterm>
-          <para>
-      JPA typically requires you to declare one or more
-      <literal>Id</literal> fields to act as primary keys.  OpenJPA, however,
-      can create and maintain a surrogate primary key value when you do
-      not declare any <literal>Id</literal> fields.  This form of 
-      persistent identity is called <emphasis>datastore 
-      identity</emphasis>.  <xref linkend="ref_guide_pc_oid"/> discusses 
-      OpenJPA's support for datastore identity in JPA.  We
-      cover how to map your datastore identity primary key column in
-      <xref linkend="ref_guide_mapping_jpa_datastoreid"/>
-      </para>
+            <title>
+                Datastore Identity
+            </title>
+            <indexterm zone="ref_guide_meta_jpa_datastoreid">
+                <primary>
+                    identity
+                </primary>
+                <secondary>
+                    datastore
+                </secondary>
+            </indexterm>
+            <para>
+JPA typically requires you to declare one or more <literal>Id</literal> fields
+to act as primary keys. OpenJPA, however, can create and maintain a surrogate
+primary key value when you do not declare any <literal>Id</literal> fields. This
+form of persistent identity is called <emphasis>datastore identity</emphasis>.
+<xref linkend="ref_guide_pc_oid"></xref> discusses OpenJPA's support for
+datastore identity in JPA. We cover how to map your datastore identity primary
+key column in <xref linkend="ref_guide_mapping_jpa_datastoreid"></xref>
+            </para>
         </section>
         <section id="ref_guide_meta_jpa_version">
-          <title>Surrogate Version</title>
-          <indexterm zone="ref_guide_meta_jpa_version">
-            <primary>version</primary>
-            <secondary>surrogate</secondary>
-          </indexterm>
-          <para>
-      Just as OpenJPA can maintain your entity's identity without any
-      <literal>Id</literal> fields, OpenJPA can maintain your entity's
-      optimistic version without any <literal>Version</literal> fields.
-      <xref linkend="ref_guide_mapping_jpa_version"/> shows you how
-      to map surrogate version columns.
-      </para>
+            <title>
+                Surrogate Version
+            </title>
+            <indexterm zone="ref_guide_meta_jpa_version">
+                <primary>
+                    version
+                </primary>
+                <secondary>
+                    surrogate
+                </secondary>
+            </indexterm>
+            <para>
+Just as OpenJPA can maintain your entity's identity without any <literal>Id
+</literal> fields, OpenJPA can maintain your entity's optimistic version without
+any <literal>Version</literal> fields.
+<xref linkend="ref_guide_mapping_jpa_version"></xref> shows you how to map
+surrogate version columns.
+            </para>
         </section>
         <section id="ref_guide_meta_jpa_persistent">
-          <title>Persistent Field Values</title>
-          <indexterm zone="ref_guide_meta_jpa_persistent">
-            <primary>persistent fields</primary>
-          </indexterm>
-          <para>
-      JPA defines <literal>Basic</literal>,
-      <literal>Lob</literal>, <literal>Embedded</literal>, 
-      <literal>ManyToOne</literal>, and <literal>OneToOne</literal> 
-      persistence strategies for direct field values.  OpenJPA supports all 
-      of these standard strategies, but adds one of its own: 
-      <literal>Persistent</literal>.  The 
-      <ulink url="../apidocs/org/apache/openjpa/persistence/Persistent.html"><classname>org.apache.openjpa.persistence.Persistent</classname></ulink> metadata
-      annotation can represent any direct field value, including
-      custom types.  It has the following properties:
-      </para>
-          <itemizedlist>
-            <listitem>
-              <para><literal>FetchType fetch</literal>: Whether to load the
-          field eagerly or lazily.  Corresponds exactly to the
-          same-named property of standard JPA annotations
-          such as <link linkend="jpa_overview_meta_basic"><classname>
-          Basic</classname></link>. Defaults to
-          <literal>FetchType.EAGER</literal>.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>CascadeType[] cascade</literal>: Array of enum
-          values defining cascade behavior for this field.  
-          Corresponds exactly to the same-named property of standard
-          JPA annotations such as 
-          <link linkend="jpa_overview_meta_manytoone"><classname>
-          ManyToOne</classname></link>. Defaults to empty array.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>String mappedBy</literal>: Names the field in the
-          related entity that maps this bidirectional relation.
-          Corresponds to the same-named property of standard JPA 
-          annotations such as 
-          <link linkend="jpa_overview_meta_onetoone"><classname>
-          OneToOne</classname></link>.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>boolean optional</literal>: Whether the value can
-          be null.  Corresponds to the same-named property of standard
-          JPA annotations such as 
-          <link linkend="jpa_overview_meta_manytoone"><classname>
-          ManyToOne</classname></link>, but can apply to non-entity
-          object values as well. Defaults to <literal>true</literal>.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>boolean embedded</literal>: Set this property to
-          <literal>true</literal> if the field value is stored as
-          an embedded object.
-          </para>
-            </listitem>
-          </itemizedlist>
-          <para>
-      Though you can use the <classname>Persistent</classname> annotation
-      in place of most of the standard direct field annotations mentioned
-      above, we recommend primarily using it for non-standard and custom
-      types for which no standard JPA annotation exists.  For example,
-      <xref linkend="ref_guide_mapping_jpa_columns"/> demonstrates the
-      use of the <classname>Persistent</classname> annotation to denote
-      a persistent <classname>java.awt.Point</classname> field.
-      </para>
+            <title>
+                Persistent Field Values
+            </title>
+            <indexterm zone="ref_guide_meta_jpa_persistent">
+                <primary>
+                    persistent fields
+                </primary>
+            </indexterm>
+            <para>
+JPA defines <literal>Basic</literal>, <literal>Lob</literal>, <literal>Embedded
+</literal>, <literal>ManyToOne</literal>, and <literal>OneToOne</literal>
+persistence strategies for direct field values. OpenJPA supports all of these
+standard strategies, but adds one of its own: <literal>Persistent</literal>.
+The <ulink url="../apidocs/org/apache/openjpa/persistence/Persistent.html">
+<classname>org.apache.openjpa.persistence.Persistent</classname></ulink>
+metadata annotation can represent any direct field value, including custom
+types. It has the following properties:
+            </para>
+            <itemizedlist>
+                <listitem>
+                    <para>
+<literal>FetchType fetch</literal>: Whether to load the field eagerly or
+lazily. Corresponds exactly to the same-named property of standard JPA
+annotations such as <link linkend="jpa_overview_meta_basic"><classname> Basic
+</classname></link>. Defaults to <literal>FetchType.EAGER</literal>.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>CascadeType[] cascade</literal>: Array of enum values defining cascade
+behavior for this field. Corresponds exactly to the same-named property of
+standard JPA annotations such as <link linkend="jpa_overview_meta_manytoone">
+<classname> ManyToOne</classname></link>. Defaults to empty array.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>String mappedBy</literal>: Names the field in the related entity that
+maps this bidirectional relation. Corresponds to the same-named property of
+standard JPA annotations such as <link linkend="jpa_overview_meta_onetoone">
+<classname> OneToOne</classname></link>.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>boolean optional</literal>: Whether the value can be null. Corresponds
+to the same-named property of standard JPA annotations such as
+<link linkend="jpa_overview_meta_manytoone"><classname> ManyToOne</classname>
+</link>, but can apply to non-entity object values as well. Defaults to
+<literal>true</literal>.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>boolean embedded</literal>: Set this property to <literal>true
+</literal> if the field value is stored as an embedded object.
+                    </para>
+                </listitem>
+            </itemizedlist>
+            <para>
+Though you can use the <classname>Persistent</classname> annotation in place of
+most of the standard direct field annotations mentioned above, we recommend
+primarily using it for non-standard and custom types for which no standard JPA
+annotation exists. For example, <xref linkend="ref_guide_mapping_jpa_columns">
+</xref> demonstrates the use of the <classname>Persistent</classname> annotation
+to denote a persistent <classname>java.awt.Point</classname> field.
+            </para>
         </section>
         <section id="ref_guide_meta_jpa_persistent_coll">
-          <title>Persistent Collection Fields</title>
-          <indexterm zone="ref_guide_meta_jpa_persistent_coll">
-            <primary>persistent fields</primary>
-            <secondary>collection metadata</secondary>
-          </indexterm>
-          <para>
-      JPA standardizes support for collections of entities with the
-      <literal>OneToMany</literal> and <literal>ManyToMany</literal>
-      persistence strategies.  OpenJPA expands collection support to handle
-      collections of simple types (primitive wrappers, 
-      <classname>String</classname>s, etc), custom types, and embedded 
-      objects.
-      </para>
-          <para>
-      The
-      <ulink url="../apidocs/org/apache/openjpa/persistence/PersistentCollection.html"><classname>org.apache.openjpa.persistence.PersistentCollection</classname></ulink>
-      metadata annotation represents a persistent collection field.
-      It has the following properties:
-      </para>
-          <itemizedlist>
-            <listitem>
-              <para><literal>Class elementType</literal>: The class of the
-          collection elements.  This information is usually taken 
-          from the parameterized collection element type.  You must 
-          supply it explicitly, however, if your field isn't a 
-          parameterized type.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>FetchType fetch</literal>: Whether to load the
-          collection eagerly or lazily.  Corresponds exactly to the
-          same-named property of standard JPA annotations
-          such as <link linkend="jpa_overview_meta_basic"><classname>
-          Basic</classname></link>. Defaults to
-          <literal>FetchType.LAZY</literal>.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>String mappedBy</literal>: Names the field in the
-          related entity that maps this bidirectional relation.
-          Corresponds to the same-named property of standard JPA 
-          annotations such as 
-          <link linkend="jpa_overview_meta_manytomany"><classname>
-          ManyToMany</classname></link>.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>CascadeType[] elementCascade</literal>: Array of 
-          enum values defining cascade behavior for the collection 
-          elements.  Corresponds exactly to the <literal>cascade
-          </literal> property of standard JPA annotations
-          such as <link linkend="jpa_overview_meta_manytomany"><classname>ManyToMany</classname></link>. Defaults to 
-          empty array.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>boolean elementEmbedded</literal>: Set this
-          property to <literal>true</literal> if the elements are
-          stored as embedded objects.
-          </para>
-            </listitem>
-          </itemizedlist>
-          <para><xref linkend="ref_guide_mapping_jpa_coll"/> contains several 
-      examples of using <classname>PersistentCollection</classname> to 
-      mark non-standard collection fields persistent.
-      </para>
-        </section>
-        <section id="ref_guide_meta_jpa_persistent_map">
-          <title>Persistent Map Fields</title>
-          <indexterm zone="ref_guide_meta_jpa_persistent_map">
-            <primary>persistent fields</primary>
-            <secondary>map metadata</secondary>
-          </indexterm>
-          <para>
-      JPA has limited support for maps.  OpenJPA introduces the 
-      <ulink url="../apidocs/org/apache/openjpa/persistence/PersistentMap.html"><classname>org.apache.openjpa.persistence.PersistentMap</classname></ulink>
-      metadata annotation to represent a persistent map field.
-      It has the following properties:
-      </para>
-          <itemizedlist>
-            <listitem>
-              <para><literal>Class keyType</literal>: The class of the
-          map keys.  This information is usually taken 
-          from the parameterized map key type.  You must 
-          supply it explicitly, however, if your field isn't a 
-          parameterized type.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>Class elementType</literal>: The class of the
-          map values.  This information is usually taken 
-          from the parameterized map value type.  You must 
-          supply it explicitly, however, if your field isn't a 
-          parameterized type.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>FetchType fetch</literal>: Whether to load the
-          collection eagerly or lazily.  Corresponds exactly to the
-          same-named property of standard JPA annotations
-          such as <link linkend="jpa_overview_meta_basic"><classname>
-          Basic</classname></link>. Defaults to
-          <literal>FetchType.LAZY</literal>.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>CascadeType[] keyCascade</literal>: Array of 
-          enum values defining cascade behavior for the map 
-          keys.  Corresponds exactly to the <literal>cascade
-          </literal> property of standard JPA annotations
-          such as <link linkend="jpa_overview_meta_manytoone"><classname>ManyToOne</classname></link>. Defaults to 
-          empty array.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>CascadeType[] elementCascade</literal>: Array of 
-          enum values defining cascade behavior for the map 
-          values.  Corresponds exactly to the <literal>cascade
-          </literal> property of standard JPA annotations
-          such as <link linkend="jpa_overview_meta_manytoone"><classname>ManyToOne</classname></link>. Defaults to 
-          empty array.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>boolean keyEmbedded</literal>: Set this
-          property to <literal>true</literal> if the map keys are
-          stored as embedded objects.
-          </para>
-            </listitem>
-            <listitem>
-              <para><literal>boolean elementEmbedded</literal>: Set this
-          property to <literal>true</literal> if the map values are
-          stored as embedded objects.
-          </para>
-            </listitem>
-          </itemizedlist>
-          <para>
-      Map keys and values in OpenJPA can be entities, simple types
-      (primitive wrappers, <classname>String</classname>s, etc),
-      custom types, or embedded objects.
-      <xref linkend="ref_guide_mapping_jpa_map"/> contains several 
-      examples of using <classname>PersistentMap</classname> to annotate 
-      persistent map fields.
-      </para>
-        </section>
-      </section>
-      <section id="ref_guide_meta_ext">
-        <title>Metadata Extensions</title>
-        <indexterm zone="ref_guide_meta_ext">
-          <primary>metadata</primary>
-          <secondary>extensions</secondary>
-        </indexterm>
-        <para>
-    OpenJPA extends standard metadata to allow you to access advanced OpenJPA 
-    functionality. This section covers persistence metadata extensions; we 
-    discuss mapping metadata extensions in 
-    <xref linkend="ref_guide_mapping_ext"/>. 
-    All metadata extensions are optional; OpenJPA will rely on its defaults
-    when no explicit data is provided.
-    </para>
-        <section id="ref_guide_meta_class">
-          <title>Class Extensions</title>
-          <para>
-      OpenJPA recognizes the following class extensions:
-      </para>
-          <section id="fetch-groups">
-            <title>Fetch Groups</title>
-            <indexterm zone="data-cache">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>fetch groups</tertiary>
-              <seealso>fetch groups</seealso>
+            <title>
+                Persistent Collection Fields
+            </title>
+            <indexterm zone="ref_guide_meta_jpa_persistent_coll">
+                <primary>
+                    persistent fields
+                </primary>
+                <secondary>
+                    collection metadata
+                </secondary>
             </indexterm>
             <para>
-        
-        The 
-        <ulink url="../apidocs/org/apache/openjpa/persistence/FetchGroups.html"><classname>org.apache.openjpa.persistence.FetchGroups</classname></ulink>
-        and <ulink url="../apidocs/org/apache/openjpa/persistence/FetchGroup.html"><classname>org.apache.openjpa.persistence.FetchGroup</classname></ulink>
-        annotations allow you to define fetch groups in your JPA 
-        entities.  <xref linkend="ref_guide_fetch"/> discusses OpenJPA's 
-        support for fetch groups in general; see 
-        <xref linkend="ref_guide_fetch_custom"/> for how to use these
-        annotations in particular.
-        </para>
-          </section>
-          <section id="data-cache">
-            <title>Data Cache</title>
-            <indexterm zone="data-cache">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>data cache</tertiary>
-              <seealso>caching</seealso>
-            </indexterm>
-            <para><xref linkend="ref_guide_cache"/> examines caching in OpenJPA.  
-        Metadata extensions allow individual classes to override 
-        system caching defaults.
-        </para>
+JPA standardizes support for collections of entities with the <literal>
+OneToMany</literal> and <literal>ManyToMany</literal> persistence strategies.
+OpenJPA expands collection support to handle collections of simple types
+(primitive wrappers, <classname>String</classname> s, etc), custom types, and
+embedded objects.
+            </para>
             <para>
-        OpenJPA defines the 
-        <ulink url="../apidocs/org/apache/openjpa/persistence/DataCache.html"><classname>org.apache.openjpa.persistence.DataCache</classname></ulink>
-        annotation for caching information.  This annotation has the
-        following properties:
-        </para>
-            <itemizedlist>
-              <listitem>
-                <para><literal>boolean enabled</literal>: Whether to cache
-            data for instances of the class.  Defaults to
-            <literal>true</literal> for base classes, or the
-            superclass value for subclasses.  If you set this 
-            property to <literal>false</literal>, all other 
-            properties are ignored.
-            </para>
-              </listitem>
-              <listitem>
-                <para><literal>String name</literal>: Place data for instances
-            of the class in a named cache.  By default, instance 
-            data is placed in the same cache as superclass data, or
-            the default cache configured through
-            the <link linkend="openjpa.DataCache"><literal>
-            openjpa.DataCache</literal></link> configuration property
-            for base classes.
-            </para>
-              </listitem>
-              <listitem>
-                <para><literal>int timeout</literal>: The number of 
-            milliseconds data for the class remains valid.  Use
-            -1 for no timeout.  Defaults to the
-            <link linkend="openjpa.DataCacheTimeout"><literal>
-            openjpa.DataCacheTimeout</literal></link> property value.
+The
+<ulink url="../apidocs/org/apache/openjpa/persistence/PersistentCollection.html">
+<classname>org.apache.openjpa.persistence.PersistentCollection</classname>
+</ulink> metadata annotation represents a persistent collection field. It has
+the following properties:
             </para>
-              </listitem>
+            <itemizedlist>
+                <listitem>
+                    <para>
+<literal>Class elementType</literal>: The class of the collection elements.
+This information is usually taken from the parameterized collection element
+type. You must supply it explicitly, however, if your field isn't a
+parameterized type.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>FetchType fetch</literal>: Whether to load the collection eagerly or
+lazily. Corresponds exactly to the same-named property of standard JPA
+annotations such as <link linkend="jpa_overview_meta_basic"><classname> Basic
+</classname></link>. Defaults to <literal>FetchType.LAZY</literal>.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>String mappedBy</literal>: Names the field in the related entity that
+maps this bidirectional relation. Corresponds to the same-named property of
+standard JPA annotations such as <link linkend="jpa_overview_meta_manytomany">
+<classname> ManyToMany</classname></link>.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>CascadeType[] elementCascade</literal>: Array of enum values defining
+cascade behavior for the collection elements. Corresponds exactly to the
+<literal>cascade</literal> property of standard JPA annotations such as
+<link linkend="jpa_overview_meta_manytomany"><classname>ManyToMany</classname>
+</link>. Defaults to empty array.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>boolean elementEmbedded</literal>: Set this property to <literal>true
+</literal> if the elements are stored as embedded objects.
+                    </para>
+                </listitem>
             </itemizedlist>
             <para>
-        The <literal>data-cache</literal> key accepts the 
-        following values:
-        </para>
-            <itemizedlist>
-              <listitem>
-                <para><literal>true</literal>: Use the default cache, as
-            configured by the <link linkend="openjpa.DataCache"><literal>openjpa.DataCache</literal></link> configuration 
-            property. This is the default when no extension is 
-            given, unless a superclass names a different cache.
-            </para>
-              </listitem>
-              <listitem>
-                <para><literal>false</literal>: Data for instances of this 
-            class should not be cached.
-            </para>
-              </listitem>
-              <listitem>
-                <para><literal>&lt;cache-name&gt;</literal>:  Place data for
-            instances of this class into the cache with name 
-            <literal>&lt;cache-name&gt;</literal>.
+<xref linkend="ref_guide_mapping_jpa_coll"></xref> contains several examples of
+using <classname>PersistentCollection</classname> to mark non-standard
+collection fields persistent.
             </para>
-              </listitem>
-            </itemizedlist>
-          </section>
-          <section id="detached-state-field">
-            <title>Detached State</title>
-            <indexterm zone="detached-state-field">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>detached state field</tertiary>
-              <seealso>detachment</seealso>
+        </section>
+        <section id="ref_guide_meta_jpa_persistent_map">
+            <title>
+                Persistent Map Fields
+            </title>
+            <indexterm zone="ref_guide_meta_jpa_persistent_map">
+                <primary>
+                    persistent fields
+                </primary>
+                <secondary>
+                    map metadata
+                </secondary>
             </indexterm>
             <para>
-        The OpenJPA <link linkend="ref_guide_pc_enhance">enhancer</link> 
-        may add a synthetic field to detachable classes to hold detached
-        state (see <xref linkend="ref_guide_detach_graph"/> 
-        for details).  You can instead declare your own detached state 
-        field or supress the creation of a detached state field 
-        altogether.  In the latter case, your class must not use 
-        <link linkend="ref_guide_pc_oid">datastore identity</link>,
-        and should declare a version field to detect optimistic 
-        concurrency errors during detached modifications.
-        </para>
-            <para>
-        OpenJPA defines the 
-        <ulink url="../apidocs/org/apache/openjpa/persistence/DetachedState.html"><classname>org.apache.openjpa.persistence.DetachedState</classname></ulink> annotation for controlling detached state.  When used
-        to annotate a class, <classname>DetachedState</classname>
-        recognizes the following properties:
-        </para>
-            <itemizedlist>
-              <listitem>
-                <para><literal>boolean enabled</literal>: Set to false to
-            suppress the use of detached state.
-            </para>
-              </listitem>
-              <listitem>
-                <para><literal>String fieldName</literal>: Use this property 
-            to declare your own detached state field.  The field
-            must be of type <classname>Object</classname>.  
-            Typically this property is only used if the field is
-            inherited from a non-persisted superclass.  If the field
-            is declared in your entity class, you will typically
-            annotate the field directly, as described below.
+JPA has limited support for maps. OpenJPA introduces the
+<ulink url="../apidocs/org/apache/openjpa/persistence/PersistentMap.html">
+<classname>org.apache.openjpa.persistence.PersistentMap</classname></ulink>
+metadata annotation to represent a persistent map field. It has the following
+properties:
             </para>
-              </listitem>
+            <itemizedlist>
+                <listitem>
+                    <para>
+<literal>Class keyType</literal>: The class of the map keys. This information
+is usually taken from the parameterized map key type. You must supply it
+explicitly, however, if your field isn't a parameterized type.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>Class elementType</literal>: The class of the map values. This
+information is usually taken from the parameterized map value type. You must
+supply it explicitly, however, if your field isn't a parameterized type.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>FetchType fetch</literal>: Whether to load the collection eagerly or
+lazily. Corresponds exactly to the same-named property of standard JPA
+annotations such as <link linkend="jpa_overview_meta_basic"><classname> Basic
+</classname></link>. Defaults to <literal>FetchType.LAZY</literal>.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>CascadeType[] keyCascade</literal>: Array of enum values defining
+cascade behavior for the map keys. Corresponds exactly to the <literal>cascade
+</literal> property of standard JPA annotations such as
+<link linkend="jpa_overview_meta_manytoone"><classname>ManyToOne</classname>
+</link>. Defaults to empty array.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>CascadeType[] elementCascade</literal>: Array of enum values defining
+cascade behavior for the map values. Corresponds exactly to the <literal>
+cascade</literal> property of standard JPA annotations such as
+<link linkend="jpa_overview_meta_manytoone"><classname>ManyToOne</classname>
+</link>. Defaults to empty array.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>boolean keyEmbedded</literal>: Set this property to <literal>true
+</literal> if the map keys are stored as embedded objects.
+                    </para>
+                </listitem>
+                <listitem>
+                    <para>
+<literal>boolean elementEmbedded</literal>: Set this property to <literal>true
+</literal> if the map values are stored as embedded objects.
+                    </para>
+                </listitem>
             </itemizedlist>
             <para>
-        If you declare your own detached state field, you can annotate
-        that field with <classname>DetachedState</classname> directly,
-        rather than placing the annotation at the class level and using
-        the <literal>fieldName</literal> property.  When placed on a
-        field, <classname>DetachedState</classname> acts as a marker 
-        annotation; it does not recognize any properties.  Your 
-        annotated field must be of type <classname>Object</classname>.
-        </para>
-          </section>
-          <section id="lock-groups">
-            <title>Lock Groups</title>
-            <para>
-        OpenJPA requires you to pre-declare subclass lock groups in the
-        least-derived mapped class.  
-        <phrase>
-        The JPA 
-        <ulink url="../apidocs/org/apache/openjpa/persistence/LockGroups.html"><classname>org.apache.openjpa.persistence.LockGroups</classname></ulink>
-        annotation accepts an array of lock group names.
-        </phrase>
-        
-        For details on lock groups, see 
-        <xref linkend="ref_guide_lock_groups_and_subclasses"/>.
+Map keys and values in OpenJPA can be entities, simple types (primitive
+wrappers, <classname>String</classname> s, etc), custom types, or embedded
+objects. <xref linkend="ref_guide_mapping_jpa_map"></xref> contains several
+examples of using <classname>PersistentMap</classname> to annotate persistent
+map fields.
+            </para>
+        </section>
+    </section>
+    <section id="ref_guide_meta_ext">
+        <title>
+            Metadata Extensions
+        </title>
+        <indexterm zone="ref_guide_meta_ext">
+            <primary>
+                metadata
+            </primary>
+            <secondary>
+                extensions
+            </secondary>
+        </indexterm>
+        <para>
+OpenJPA extends standard metadata to allow you to access advanced OpenJPA
+functionality. This section covers persistence metadata extensions; we discuss
+mapping metadata extensions in <xref linkend="ref_guide_mapping_ext"></xref>.
+All metadata extensions are optional; OpenJPA will rely on its defaults when no
+explicit data is provided.
         </para>
-          </section>
-          <section id="auditable">
-            <title>Auditable</title>
+        <section id="ref_guide_meta_class">
+            <title>
+                Class Extensions
+            </title>
             <para>
-        Reserved for future use.
-        </para>
-          </section>
+OpenJPA recognizes the following class extensions:
+            </para>
+            <section id="fetch-groups">
+                <title>
+                    Fetch Groups
+                </title>
+                <indexterm zone="data-cache">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        fetch groups
+                    </tertiary>
+                    <seealso>
+                        fetch groups
+                    </seealso>
+                </indexterm>
+                <para>
+The <ulink url="../apidocs/org/apache/openjpa/persistence/FetchGroups.html">
+<classname>org.apache.openjpa.persistence.FetchGroups</classname></ulink> and
+<ulink url="../apidocs/org/apache/openjpa/persistence/FetchGroup.html">
+<classname>org.apache.openjpa.persistence.FetchGroup</classname></ulink>
+annotations allow you to define fetch groups in your JPA entities.
+<xref linkend="ref_guide_fetch"></xref> discusses OpenJPA's support for fetch
+groups in general; see <xref linkend="ref_guide_fetch_custom"></xref> for how to
+use these annotations in particular.
+                </para>
+            </section>
+            <section id="data-cache">
+                <title>
+                    Data Cache
+                </title>
+                <indexterm zone="data-cache">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        data cache
+                    </tertiary>
+                    <seealso>
+                        caching
+                    </seealso>
+                </indexterm>
+                <para>
+<xref linkend="ref_guide_cache"></xref> examines caching in OpenJPA. Metadata
+extensions allow individual classes to override system caching defaults.
+                </para>
+                <para>
+OpenJPA defines the
+<ulink url="../apidocs/org/apache/openjpa/persistence/DataCache.html">
+<classname>org.apache.openjpa.persistence.DataCache</classname></ulink>
+annotation for caching information. This annotation has the following
+properties:
+                </para>
+                <itemizedlist>
+                    <listitem>
+                        <para>
+<literal>boolean enabled</literal>: Whether to cache data for instances of the
+class. Defaults to <literal>true</literal> for base classes, or the superclass
+value for subclasses. If you set this property to <literal>false</literal>, all
+other properties are ignored.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<literal>String name</literal>: Place data for instances of the class in a
+named cache. By default, instance data is placed in the same cache as superclass
+data, or the default cache configured through the
+<link linkend="openjpa.DataCache"><literal> openjpa.DataCache</literal></link>
+configuration property for base classes.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<literal>int timeout</literal>: The number of milliseconds data for the class
+remains valid. Use -1 for no timeout. Defaults to the
+<link linkend="openjpa.DataCacheTimeout"><literal> openjpa.DataCacheTimeout
+</literal></link> property value.
+                        </para>
+                    </listitem>
+                </itemizedlist>
+                <para>
+The <literal>data-cache</literal> key accepts the following values:
+                </para>
+                <itemizedlist>
+                    <listitem>
+                        <para>
+<literal>true</literal>: Use the default cache, as configured by the
+<link linkend="openjpa.DataCache"><literal>openjpa.DataCache</literal></link>
+configuration property. This is the default when no extension is given, unless a
+superclass names a different cache.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<literal>false</literal>: Data for instances of this class should not be
+cached.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<literal>&lt;cache-name&gt;</literal>: Place data for instances of this class
+into the cache with name <literal>&lt;cache-name&gt;</literal>.
+                        </para>
+                    </listitem>
+                </itemizedlist>
+            </section>
+            <section id="detached-state-field">
+                <title>
+                    Detached State
+                </title>
+                <indexterm zone="detached-state-field">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        detached state field
+                    </tertiary>
+                    <seealso>
+                        detachment
+                    </seealso>
+                </indexterm>
+                <para>
+The OpenJPA <link linkend="ref_guide_pc_enhance">enhancer</link> may add a
+synthetic field to detachable classes to hold detached state (see
+<xref linkend="ref_guide_detach_graph"></xref> for details). You can instead
+declare your own detached state field or supress the creation of a detached
+state field altogether. In the latter case, your class must not use
+<link linkend="ref_guide_pc_oid">datastore identity</link>, and should declare
+a version field to detect optimistic concurrency errors during detached
+modifications.
+                </para>
+                <para>
+OpenJPA defines the
+<ulink url="../apidocs/org/apache/openjpa/persistence/DetachedState.html">
+<classname>org.apache.openjpa.persistence.DetachedState</classname></ulink>
+annotation for controlling detached state. When used to annotate a class,
+<classname>DetachedState</classname> recognizes the following properties:
+                </para>
+                <itemizedlist>
+                    <listitem>
+                        <para>
+<literal>boolean enabled</literal>: Set to false to suppress the use of
+detached state.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<literal>String fieldName</literal>: Use this property to declare your own
+detached state field. The field must be of type <classname>Object</classname>.
+Typically this property is only used if the field is inherited from a
+non-persisted superclass. If the field is declared in your entity class, you
+will typically annotate the field directly, as described below.
+                        </para>
+                    </listitem>
+                </itemizedlist>
+                <para>
+If you declare your own detached state field, you can annotate that field with
+<classname>DetachedState</classname> directly, rather than placing the
+annotation at the class level and using the <literal>fieldName</literal>
+property. When placed on a field, <classname>DetachedState</classname> acts as a
+marker annotation; it does not recognize any properties. Your annotated field
+must be of type <classname>Object</classname>.
+                </para>
+            </section>
+            <section id="lock-groups">
+                <title>
+                    Lock Groups
+                </title>
+                <para>
+OpenJPA requires you to pre-declare subclass lock groups in the least-derived
+mapped class. <phrase> The JPA
+<ulink url="../apidocs/org/apache/openjpa/persistence/LockGroups.html">
+<classname>org.apache.openjpa.persistence.LockGroups</classname></ulink>
+annotation accepts an array of lock group names.</phrase> For details on lock
+groups, see <xref linkend="ref_guide_lock_groups_and_subclasses"></xref>.
+                </para>
+            </section>
+            <section id="auditable">
+                <title>
+                    Auditable
+                </title>
+                <para>
+Reserved for future use.
+                </para>
+            </section>
         </section>
         <section id="ref_guide_meta_field">
-          <title>Field Extensions</title>
-          <para>
-      OpenJPA recognizes the following field extensions:
-      </para>
-          <section id="dependent">
-            <title>Dependent</title>
-            <indexterm zone="data-cache">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>dependent</tertiary>
-            </indexterm>
-            <para>
-        In a <emphasis>dependent</emphasis> relation, the referenced
-        object is deleted whenever the owning object is deleted, or 
-        whenever the relation is severed by nulling or resetting the 
-        owning field.  For example, if the 
-        <literal>Magazine.coverArticle</literal> field is marked 
-        dependent, then setting <literal>Magazine.coverArticle</literal>
-        to a new <classname>Article</classname> instance will 
-        automatically delete the old <classname>Article</classname> 
-        stored in the field.  Similarly, deleting a <classname>Magazine
-        </classname> object will automatically delete its current cover
-        <classname>Article</classname>.
-        You can prevent an orphaned dependent object from being deleted
-        by assigning it to another relation in the same transaction.
-        </para>
+            <title>
+                Field Extensions
+            </title>
             <para>
-        
-        OpenJPA offers a family of marker annotations to
-        denote dependent relations in JPA entities:
-        </para>
-            <itemizedlist>
-              <listitem>
-                <para><ulink url="../apidocs/org/apache/openjpa/persistence/Dependent.html"><classname>
-            org.apache.openjpa.persistence.Dependent</classname></ulink>: Marks
-            a direct relation as dependent.
-            </para>
-              </listitem>
-              <listitem>
-                <para><ulink url="../apidocs/org/apache/openjpa/persistence/ElementDependent.html"><classname>
-            org.apache.openjpa.persistence.ElementDependent</classname></ulink>: 
-            Marks the entity elements of a collection, array, or 
-            map field as dependent.
-            </para>
-              </listitem>
-              <listitem>
-                <para><ulink url="../apidocs/org/apache/openjpa/persistence/KeyDependent.html"><classname>
-            org.apache.openjpa.persistence.KeyDependent</classname></ulink>: 
-            Marks the key entities in a map field as dependent.
+OpenJPA recognizes the following field extensions:
             </para>
-              </listitem>
-            </itemizedlist>
-          </section>
-          <section id="lrs">
-            <title>LRS</title>
-            <indexterm zone="lrs">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>lrs</tertiary>
-              <seealso>large result sets</seealso>
-            </indexterm>
-            <para>
-        This boolean extension, denoted by 
-        <phrase>
-        the JPA <ulink url="../apidocs/org/apache/openjpa/persistence/LRS.html"><classname>org.apache.openjpa.persistence.LRS</classname></ulink> annotation,
-        </phrase>
-        
-        
-        indicates that a field should use 
-        OpenJPA's special large result set collection or map proxies.  
-        A complete description of large result set proxies is 
-        available in <xref linkend="ref_guide_pc_scos_proxy_lrs"/>.
-        </para>
-          </section>
-          <section id="order-by">
-            <title>Order-By</title>
-            <indexterm zone="order-by">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>order-by</tertiary>
-            </indexterm>
-            <para><phrase>
-        The JPA Overview's 
-        <xref linkend="jpa_overview_meta_orderby"/> describes JPA's 
-        <literal>OrderBy</literal> annotation for loading the elements
-        of collection fields in a prescribed order.
-        </phrase>
-        
-        
-        
-        Ordering syntax is as follows:
-        </para>
-            <programlisting format="linespecific">
+            <section id="dependent">
+                <title>
+                    Dependent
+                </title>
+                <indexterm zone="data-cache">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        dependent
+                    </tertiary>
+                </indexterm>
+                <para>
+In a <emphasis>dependent</emphasis> relation, the referenced object is deleted
+whenever the owning object is deleted, or whenever the relation is severed by
+nulling or resetting the owning field. For example, if the <literal>
+Magazine.coverArticle</literal> field is marked dependent, then setting
+<literal>Magazine.coverArticle</literal> to a new <classname>Article</classname>
+instance will automatically delete the old <classname>Article</classname> stored
+in the field. Similarly, deleting a <classname>Magazine</classname> object will
+automatically delete its current cover <classname>Article</classname>. You can
+prevent an orphaned dependent object from being deleted by assigning it to
+another relation in the same transaction.
+                </para>
+                <para>
+OpenJPA offers a family of marker annotations to denote dependent relations in
+JPA entities:
+                </para>
+                <itemizedlist>
+                    <listitem>
+                        <para>
+<ulink url="../apidocs/org/apache/openjpa/persistence/Dependent.html">
+<classname> org.apache.openjpa.persistence.Dependent</classname></ulink>: Marks
+a direct relation as dependent.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<ulink url="../apidocs/org/apache/openjpa/persistence/ElementDependent.html">
+<classname> org.apache.openjpa.persistence.ElementDependent</classname></ulink>
+: Marks the entity elements of a collection, array, or map field as dependent.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<ulink url="../apidocs/org/apache/openjpa/persistence/KeyDependent.html">
+<classname> org.apache.openjpa.persistence.KeyDependent</classname></ulink>:
+Marks the key entities in a map field as dependent.
+                        </para>
+                    </listitem>
+                </itemizedlist>
+            </section>
+            <section id="lrs">
+                <title>
+                    LRS
+                </title>
+                <indexterm zone="lrs">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        lrs
+                    </tertiary>
+                    <seealso>
+                        large result sets
+                    </seealso>
+                </indexterm>
+                <para>
+This boolean extension, denoted by <phrase> the JPA
+<ulink url="../apidocs/org/apache/openjpa/persistence/LRS.html"><classname>
+org.apache.openjpa.persistence.LRS</classname></ulink> annotation,</phrase>
+indicates that a field should use OpenJPA's special large result set collection
+or map proxies. A complete description of large result set proxies is available
+in <xref linkend="ref_guide_pc_scos_proxy_lrs"></xref>.
+                </para>
+            </section>
+            <section id="order-by">
+                <title>
+                    Order-By
+                </title>
+                <indexterm zone="order-by">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        order-by
+                    </tertiary>
+                </indexterm>
+                <para>
+<phrase> The JPA Overview's <xref linkend="jpa_overview_meta_orderby"></xref>
+describes JPA's <literal>OrderBy</literal> annotation for loading the elements
+of collection fields in a prescribed order.</phrase> Ordering syntax is as
+follows:
+                </para>
+<programlisting>
 #element|&lt;field name&gt;[ asc|ascending|desc|descending][, ...]
 </programlisting>
-            <para>
-        The token <literal>#element</literal> represents the element
-        value.  Simple element types such as strings and primitive
-        wrappers are sorted based on their natural ordering.  If the
-        collection holds persistent objects, its elements are sorted 
-        based on the natural ordering of the objects' primary key 
-        values.  By substituting a field name for the <literal>
-        #element</literal> token, you can order a collection of 
-        persistent objects by an arbitrary field in the related type,
-        rather than by primary key.
-        </para>
-            <para>
-        The field name or <literal>#element</literal> token may be
-        followed by the keywords <literal>asc/ascending</literal> or 
-        <literal>desc/descending</literal> in either all-upper or 
-        all-lower case to mandate ascending and descending order.
-        If the direction is omitted, OpenJPA defaults to ascending order.
-        </para>
-            <para>
-        Note that the defined ordering is only applied when the 
-        collection is loaded from the datastore.  It is not maintained
-        by OpenJPA as you modify the collection in memory.
-        </para>
-            <para>
-        The following ordering string orders a collection by its 
-        element values in descending order:
-        </para>
-            <programlisting format="linespecific">
+                <para>
+The token <literal>#element</literal> represents the element value. Simple
+element types such as strings and primitive wrappers are sorted based on their
+natural ordering. If the collection holds persistent objects, its elements are
+sorted based on the natural ordering of the objects' primary key values. By
+substituting a field name for the <literal> #element</literal> token, you can
+order a collection of persistent objects by an arbitrary field in the related
+type, rather than by primary key.
+                </para>
+                <para>
+The field name or <literal>#element</literal> token may be followed by the
+keywords <literal>asc/ascending</literal> or <literal>desc/descending</literal>
+in either all-upper or all-lower case to mandate ascending and descending order.
+If the direction is omitted, OpenJPA defaults to ascending order.
+                </para>
+                <para>
+Note that the defined ordering is only applied when the collection is loaded
+from the datastore. It is not maintained by OpenJPA as you modify the collection
+in memory.
+                </para>
+                <para>
+The following ordering string orders a collection by its element values in
+descending order:
+                </para>
+<programlisting>
 "#element desc"
 </programlisting>
-            <para>
-        The following ordering string orders a collection of 
-        <classname>Author</classname> objects by each author's last
-        name in ascending order.  If two last names are equal, the
-        authors are ordered by first name in ascending order.
-        </para>
-            <programlisting format="linespecific">
+                <para>
+The following ordering string orders a collection of <classname>Author
+</classname> objects by each author's last name in ascending order. If two last
+names are equal, the authors are ordered by first name in ascending order.
+                </para>
+<programlisting>
 "firstName, lastName"
 </programlisting>
-          </section>
-          <section id="inverse-logical">
-            <title>Inverse-Logical</title>
-            <indexterm zone="inverse-logical">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>inverse-logical</tertiary>
-              <seealso>bidirectional relations</seealso>
-            </indexterm>
-            <para>
-        This extension names the inverse field in a logical 
-        bidirectional relation.  
-        <phrase>
-        To create a logical bidrectional relation in OpenJPA, use the
-        <ulink url="../apidocs/org/apache/openjpa/persistence/InverseLogical.html"><classname>org.apache.openjpa.persistence.InverseLogical</classname></ulink> 
-        annotation.
-        </phrase>
-        
-        We discuss logical bidirectional relations and this extension
-        in detail in <xref linkend="ref_guide_inverses"/>.
-        </para>
-          </section>
-          <section id="lock-group">
-            <title>Lock Group</title>
-            <indexterm zone="lock-group">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>lock group</tertiary>
-              <seealso>locking</seealso>
-            </indexterm>
-            <para>
-        Lock groups allow for fine-grained optimistic locking 
-        concurrency.  
-        Use
-        <phrase>
-        OpenJPA's 
-        <ulink url="../apidocs/org/apache/openjpa/persistence/LockGroup.html"><classname>org.apache.openjpa.persistence.LockGroup</classname></ulink>
-        annotation
-        </phrase>
-        
-        
-        to name the lock group for a field.  You can exclude a field 
-        from optimistic locking with a value of <literal>none</literal>.
-        We discuss lock groups and this extension further in 
-        <xref linkend="ref_guide_lock_groups"/>.
-        </para>
-          </section>
-          <section id="read-only">
-            <title>Read-Only</title>
-            <indexterm zone="read-only">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>read-only</tertiary>
-              <seealso>persistent fields</seealso>
-            </indexterm>
-            <indexterm zone="read-only">
-              <primary>persistent fields</primary>
-              <secondary>read only</secondary>
-            </indexterm>
-            <para>
-        The read-only extension makes a field unwritable.  The 
-        extension only applies to existing persistent objects; new 
-        object fields are always writeable.
-        </para>
-            <para>
-        To mark a field read-only in JPA metadata, set the
-        <ulink url="../apidocs/org/apache/openjpa/persistence/ReadOnly.html"><classname>org.apache.openjpa.persistence.ReadOnly</classname></ulink>
-        annotation to a
-        <ulink url="../apidocs/org/apache/openjpa/persistence/UpdateAction.html"><classname>org.apache.openjpa.persistence.UpdateAction</classname></ulink>
-        enum value.  The <classname>UpdateAction</classname> enum
-        includes:
-        </para>
-            <itemizedlist>
-              <listitem>
-                <para><literal>UpdateAction.IGNORE</literal>: Updates to the 
-            field are completely ignored.  The field is not 
-            considered dirty.
-            The new value will not even get stored in the
-            OpenJPA <link linkend="ref_guide_cache">data cache</link>.
-            </para>
-              </listitem>
-              <listitem>
-                <para><literal>UpdateAction.RESTRICT</literal>: Any attempt 
-            to change the field will result in an immediate 
-            exception.
-            </para>
-              </listitem>
-            </itemizedlist>
-          </section>
-          <section id="type">
-            <title>Type</title>
-            <indexterm zone="type">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>type</tertiary>
-              <seealso>persistent fields</seealso>
-            </indexterm>
-            <para>
-        OpenJPA has three levels of support for relations:
-        </para>
-            <orderedlist>
-              <listitem>
+            </section>
+            <section id="inverse-logical">
+                <title>
+                    Inverse-Logical
+                </title>
+                <indexterm zone="inverse-logical">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        inverse-logical
+                    </tertiary>
+                    <seealso>
+                        bidirectional relations
+                    </seealso>
+                </indexterm>
                 <para>
-            Relations that hold a reference to an object of a 
-            concrete persistent class are supported by storing 
-            the primary key values of the related instance in 
-            the database.
-            </para>
-              </listitem>
-              <listitem>
-                <para>
-            Relations that hold a reference to an object of an
-            unknown persistent class are supported by storing 
-            the stringified identity value of the related 
-            instance.  This level of support does not allow 
-            queries across the relation.
-            </para>
-              </listitem>
-              <listitem>
-                <para>
-            Relations that hold an unknown object or interface.
-            The only way to support these relations is to 
-            serialize their value to the database.  This does 
-            not allow you to query the field, and is not very 
-            efficient.
-            </para>
-              </listitem>
-            </orderedlist>
-            <para>
-        Clearly, when you declare a field's type to be another
-        persistence-capable class, OpenJPA uses level 1 support.  
-        By default, OpenJPA assumes that any interface-typed fields 
-        you declare will be implemented only by other persistent 
-        classes, and assigns interfaces level 2 support.  The exception
-        to this rule is the <classname>java.io.Serializable</classname> 
-        interface.  If you declare a field to be of type 
-        <classname>Serializable</classname>, OpenJPA lumps it
-        together with <classname>java.lang.Object</classname>
-        fields and other non-interface, unrecognized field types,
-        which are all assigned level 3 support.
-        </para>
-            <para>
-        With OpenJPA's type family of metadata extensions, you can 
-        control the level of support given to your 
-        unknown/interface-typed fields.  Setting the value of this 
-        extension to 
-        <phrase><classname>Entity</classname></phrase>
-        
-        
-        
-        indicates that the field value will always be some persistent 
-        object, and gives level 2 support.  Setting the value of this
-        extension to the class of a concrete persistent
-        type is even better; it gives you level 1 
-        support (just as if you had declared your field to be
-        of that type in the first place).  Setting this extension
-        to <classname>Object</classname> uses level 3 
-        support.  This is useful when you have an interface
-        relation that may <emphasis role="bold">not</emphasis> 
-        hold other persistent objects (recall that OpenJPA 
-        assumes interface fields will always hold persistent
-        instances by default).
-        </para>
-            <para>
-        This extension is also used with OpenJPA's externalization feature,
-        described in <xref linkend="ref_guide_pc_extern"/>.
-        </para>
-            <para>
-        OpenJPA defines the following type annotations for field 
-        values, collection, array, and map elements, and map keys,
-        respectively:
-        </para>
-            <itemizedlist>
-              <listitem>
+This extension names the inverse field in a logical bidirectional relation.
+<phrase> To create a logical bidrectional relation in OpenJPA, use the
+<ulink url="../apidocs/org/apache/openjpa/persistence/InverseLogical.html">
+<classname>org.apache.openjpa.persistence.InverseLogical</classname></ulink>
+annotation.</phrase> We discuss logical bidirectional relations and this
+extension in detail in <xref linkend="ref_guide_inverses"></xref>.
+                </para>
+            </section>
+            <section id="lock-group">
+                <title>
+                    Lock Group
+                </title>
+                <indexterm zone="lock-group">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        lock group
+                    </tertiary>
+                    <seealso>
+                        locking
+                    </seealso>
+                </indexterm>
                 <para>
-                  <ulink url="../apidocs/org/apache/openjpa/persistence/Type.html">
-                    <classname>org.apache.openjpa.persistence.Type</classname>
-                  </ulink>
+Lock groups allow for fine-grained optimistic locking concurrency. Use <phrase>
+OpenJPA's <ulink url="../apidocs/org/apache/openjpa/persistence/LockGroup.html">
+<classname>org.apache.openjpa.persistence.LockGroup</classname></ulink>
+annotation</phrase> to name the lock group for a field. You can exclude a field
+from optimistic locking with a value of <literal>none</literal>. We discuss
+lock groups and this extension further in <xref linkend="ref_guide_lock_groups">
+</xref>.
                 </para>
-              </listitem>
-              <listitem>
+            </section>
+            <section id="read-only">
+                <title>
+                    Read-Only
+                </title>
+                <indexterm zone="read-only">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        read-only
+                    </tertiary>
+                    <seealso>
+                        persistent fields
+                    </seealso>
+                </indexterm>
+                <indexterm zone="read-only">
+                    <primary>
+                        persistent fields
+                    </primary>
+                    <secondary>
+                        read only
+                    </secondary>
+                </indexterm>
                 <para>
-                  <ulink url="../apidocs/org/apache/openjpa/persistence/ElementType.html">
-                    <classname>org.apache.openjpa.persistence.ElementType
-            </classname>
-                  </ulink>
+The read-only extension makes a field unwritable. The extension only applies to
+existing persistent objects; new object fields are always writeable.
                 </para>
-              </listitem>
-              <listitem>
                 <para>
-                  <ulink url="../apidocs/org/apache/openjpa/persistence/KeyType.html">
-                    <classname>org.apache.openjpa.persistence.KeyType
-            </classname>
-                  </ulink>
+To mark a field read-only in JPA metadata, set the
+<ulink url="../apidocs/org/apache/openjpa/persistence/ReadOnly.html">
+<classname>org.apache.openjpa.persistence.ReadOnly</classname></ulink>
+annotation to a
+<ulink url="../apidocs/org/apache/openjpa/persistence/UpdateAction.html">
+<classname>org.apache.openjpa.persistence.UpdateAction</classname></ulink> enum
+value. The <classname>UpdateAction</classname> enum includes:
                 </para>
-              </listitem>
-            </itemizedlist>
-          </section>
-          <section id="externalizer">
-            <title>Externalizer</title>
-            <indexterm zone="externalizer">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>externalizer</tertiary>
-              <seealso>externalization</seealso>
-            </indexterm>
-            <para>
-        The 
-        <phrase>
-        JPA 
-        <ulink url="../apidocs/org/apache/openjpa/persistence/Externalizer.html"><classname>org.apache.openjpa.persistence.Externalizer</classname></ulink>
-        annotation
-        </phrase>
-        
-        
-        names a method to transform a field value into a value of 
-        another type.  See <xref linkend="ref_guide_pc_extern"/>
-        for details.
-        </para>
-          </section>
-          <section id="factory">
-            <title>Factory</title>
-            <indexterm zone="factory">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>factory</tertiary>
-              <seealso>externalization</seealso>
-            </indexterm>
-            <para>
-        The 
-        <phrase>
-        JPA <ulink url="../apidocs/org/apache/openjpa/persistence/Factory.html"><classname>org.apache.openjpa.persistence.Factory</classname></ulink>
-        annotation
-        </phrase>
-        
-        
-        names a method to re-create a field value from its 
-        externalized form.  See <xref linkend="ref_guide_pc_extern"/> 
-        for details.
-        </para>
-          </section>
-          <section id="external-values">
-            <title>External Values</title>
-            <indexterm zone="factory">
-              <primary>metadata</primary>
-              <secondary>extensions</secondary>
-              <tertiary>external values</tertiary>
-              <seealso>externalization</seealso>
-            </indexterm>
-            <para>
-        The 
-        <phrase>
-        JPA 
-        <ulink url="../apidocs/org/apache/openjpa/persistence/ExternalValues.html"><classname>org.apache.openjpa.persistence.ExternalValues</classname></ulink>
-        annotation
-        </phrase>
-        
-        
-        declares values for transformation of simple fields
-        to different constant values in the datastore.
-        See <xref linkend="ref_guide_pc_extern_values"/> for details.
-        </para>
-          </section>
+                <itemizedlist>
+                    <listitem>
+                        <para>
+<literal>UpdateAction.IGNORE</literal>: Updates to the field are completely
+ignored. The field is not considered dirty. The new value will not even get
+stored in the OpenJPA <link linkend="ref_guide_cache">data cache</link>.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<literal>UpdateAction.RESTRICT</literal>: Any attempt to change the field will
+result in an immediate exception.
+                        </para>
+                    </listitem>
+                </itemizedlist>
+            </section>
+            <section id="type">
+                <title>
+                    Type
+                </title>
+                <indexterm zone="type">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        type
+                    </tertiary>
+                    <seealso>
+                        persistent fields
+                    </seealso>
+                </indexterm>
+                <para>
+OpenJPA has three levels of support for relations:
+                </para>
+                <orderedlist>
+                    <listitem>
+                        <para>
+Relations that hold a reference to an object of a concrete persistent class are
+supported by storing the primary key values of the related instance in the
+database.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+Relations that hold a reference to an object of an unknown persistent class are
+supported by storing the stringified identity value of the related instance.
+This level of support does not allow queries across the relation.
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+Relations that hold an unknown object or interface. The only way to support
+these relations is to serialize their value to the database. This does not allow
+you to query the field, and is not very efficient.
+                        </para>
+                    </listitem>
+                </orderedlist>
+                <para>
+Clearly, when you declare a field's type to be another persistence-capable
+class, OpenJPA uses level 1 support. By default, OpenJPA assumes that any
+interface-typed fields you declare will be implemented only by other persistent
+classes, and assigns interfaces level 2 support. The exception to this rule is
+the <classname>java.io.Serializable</classname> interface. If you declare a
+field to be of type <classname>Serializable</classname>, OpenJPA lumps it
+together with <classname>java.lang.Object</classname> fields and other
+non-interface, unrecognized field types, which are all assigned level 3 support.
+                </para>
+                <para>
+With OpenJPA's type family of metadata extensions, you can control the level of
+support given to your unknown/interface-typed fields. Setting the value of this
+extension to <phrase><classname>Entity</classname></phrase> indicates that the
+field value will always be some persistent object, and gives level 2 support.
+Setting the value of this extension to the class of a concrete persistent type
+is even better; it gives you level 1 support (just as if you had declared your
+field to be of that type in the first place). Setting this extension to
+<classname>Object</classname> uses level 3 support. This is useful when you have
+an interface relation that may <emphasis role="bold">not</emphasis> hold other
+persistent objects (recall that OpenJPA assumes interface fields will always
+hold persistent instances by default).
+                </para>
+                <para>
+This extension is also used with OpenJPA's externalization feature, described in
+<xref linkend="ref_guide_pc_extern"></xref>.
+                </para>
+                <para>
+OpenJPA defines the following type annotations for field values, collection,
+array, and map elements, and map keys, respectively:
+                </para>
+                <itemizedlist>
+                    <listitem>
+                        <para>
+<ulink url="../apidocs/org/apache/openjpa/persistence/Type.html"><classname>
+org.apache.openjpa.persistence.Type</classname></ulink>
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<ulink url="../apidocs/org/apache/openjpa/persistence/ElementType.html">
+<classname>org.apache.openjpa.persistence.ElementType</classname></ulink>
+                        </para>
+                    </listitem>
+                    <listitem>
+                        <para>
+<ulink url="../apidocs/org/apache/openjpa/persistence/KeyType.html"><classname>
+org.apache.openjpa.persistence.KeyType</classname></ulink>
+                        </para>
+                    </listitem>
+                </itemizedlist>
+            </section>
+            <section id="externalizer">
+                <title>
+                    Externalizer
+                </title>
+                <indexterm zone="externalizer">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        externalizer
+                    </tertiary>
+                    <seealso>
+                        externalization
+                    </seealso>
+                </indexterm>
+                <para>
+The <phrase> JPA
+<ulink url="../apidocs/org/apache/openjpa/persistence/Externalizer.html">
+<classname>org.apache.openjpa.persistence.Externalizer</classname></ulink>
+annotation</phrase> names a method to transform a field value into a value of
+another type. See <xref linkend="ref_guide_pc_extern"></xref> for details.
+                </para>
+            </section>
+            <section id="factory">
+                <title>
+                    Factory
+                </title>
+                <indexterm zone="factory">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        factory
+                    </tertiary>
+                    <seealso>
+                        externalization
+                    </seealso>
+                </indexterm>
+                <para>
+The <phrase> JPA
+<ulink url="../apidocs/org/apache/openjpa/persistence/Factory.html"><classname>
+org.apache.openjpa.persistence.Factory</classname></ulink> annotation</phrase>
+names a method to re-create a field value from its externalized form. See
+<xref linkend="ref_guide_pc_extern"></xref> for details.
+                </para>
+            </section>
+            <section id="external-values">
+                <title>
+                    External Values
+                </title>
+                <indexterm zone="factory">
+                    <primary>
+                        metadata
+                    </primary>
+                    <secondary>
+                        extensions
+                    </secondary>
+                    <tertiary>
+                        external values
+                    </tertiary>
+                    <seealso>
+                        externalization
+                    </seealso>
+                </indexterm>
+                <para>
+The <phrase> JPA
+<ulink url="../apidocs/org/apache/openjpa/persistence/ExternalValues.html">
+<classname>org.apache.openjpa.persistence.ExternalValues</classname></ulink>
+annotation</phrase> declares values for transformation of simple fields to
+different constant values in the datastore. See
+<xref linkend="ref_guide_pc_extern_values"></xref> for details.
+                </para>
+            </section>
         </section>
         <section id="ref_guide_meta_example">
-          <title>Example</title>
-          <para>
-      The following example shows you how to specify extensions in 
-      metadata.
-      </para>
-          <example id="ref_guide_metaex">
-            <title>OpenJPA Metadata Extensions</title>
-            <programlisting format="linespecific">
+            <title>
+                Example
+            </title>
+            <para>
+The following example shows you how to specify extensions in metadata.
+            </para>
+            <example id="ref_guide_metaex">
+                <title>
+                    OpenJPA Metadata Extensions
+                </title>
+<programlisting>
 import org.apache.openjpa.persistence.*;
 
 @Entity
@@ -970,7 +1071,7 @@
     ...
 }
 </programlisting>
-          </example>
+            </example>
         </section>
-      </section>
-    </chapter>
+    </section>
+</chapter>



Mime
View raw message