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>
<property name="openjpa.MetaDataFactory" value="jpa"/>
</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>
<property name="openjpa.MetaDataFactory" value="com.xyz.CustomMetaDataFactory"/>
</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><cache-name></literal>: Place data for
- instances of this class into the cache with name
- <literal><cache-name></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><cache-name></literal>: Place data for instances of this class
+into the cache with name <literal><cache-name></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|<field name>[ 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>
|