You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by aw...@apache.org on 2006/08/24 22:41:14 UTC
svn commit: r434517 [5/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/
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_overview_meta.xml Thu Aug 24 13:41:12 2006
@@ -1,335 +1,414 @@
-
- <chapter id="jpa_overview_meta">
- <title>Metadata</title>
- <indexterm zone="jpa_overview_meta">
- <primary>metadata</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta">
- <primary>JPA</primary>
- <secondary>metadata</secondary>
- <seealso>metadata</seealso>
- </indexterm>
- <para>
- JPA requires that you accompany each persistent class with
- persistence metadata. This metadata serves three primary purposes:
- </para>
- <orderedlist>
+<chapter id="jpa_overview_meta">
+ <title>
+ Metadata
+ </title>
+ <indexterm zone="jpa_overview_meta">
+ <primary>
+ metadata
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta">
+ <primary>
+ JPA
+ </primary>
+ <secondary>
+ metadata
+ </secondary>
+ <seealso>
+ metadata
+ </seealso>
+ </indexterm>
+ <para>
+JPA requires that you accompany each persistent class with persistence metadata.
+This metadata serves three primary purposes:
+ </para>
+ <orderedlist>
<listitem>
- <para>To identify persistent classes.</para>
+ <para>
+To identify persistent classes.
+ </para>
</listitem>
<listitem>
- <para>To override default JPA behavior.</para>
+ <para>
+To override default JPA behavior.
+ </para>
</listitem>
<listitem>
- <para>
- To provide the JPA implementation with information that
- it cannot glean from simply reflecting on the persistent class.
- </para>
+ <para>
+To provide the JPA implementation with information that it cannot glean from
+simply reflecting on the persistent class.
+ </para>
</listitem>
- </orderedlist>
- <para><indexterm><primary>annotations</primary></indexterm>
- Persistence metadata is specified using either the Java 5 annotations
- defined in the <literal>javax.persistence</literal> package, XML
- mapping files, or a mixture of both. In the latter case, XML declarations
- override conflicting annotations. If you choose to use XML metadata, the
- XML files must be available at development and runtime, and must be
- discoverable via either of two strategies:
- </para>
- <orderedlist>
+ </orderedlist>
+ <para>
+ <indexterm>
+ <primary>
+ annotations
+ </primary>
+ </indexterm>
+Persistence metadata is specified using either the Java 5 annotations defined in
+the <literal>javax.persistence</literal> package, XML mapping files, or a
+mixture of both. In the latter case, XML declarations override conflicting
+annotations. If you choose to use XML metadata, the XML files must be available
+at development and runtime, and must be discoverable via either of two
+strategies:
+ </para>
+ <orderedlist>
<listitem>
- <para>
- In a resource named <filename>orm.xml</filename> placed in
- the <filename>META-INF</filename> directory of the classpath
- or the jar archive containing your persistent classes.
- </para>
+ <para>
+In a resource named <filename>orm.xml</filename> placed in the <filename>
+META-INF</filename> directory of the classpath or the jar archive containing
+your persistent classes.
+ </para>
</listitem>
<listitem>
- <para>
- Declared in your <link linkend="jpa_overview_persistence_xml"><filename>persistence.xml</filename></link> configuration file.
- In this case, each XML metadata file must be
- listed in a <literal>mapping-file</literal> element whose
- content is either a path to the given file or a resource
- location available to the class' class loader.
- </para>
+ <para>
+Declared in your <link linkend="jpa_overview_persistence_xml"><filename>
+persistence.xml</filename></link> configuration file. In this case, each XML
+metadata file must be listed in a <literal>mapping-file</literal> element whose
+content is either a path to the given file or a resource location available to
+the class' class loader.
+ </para>
</listitem>
- </orderedlist>
- <para>
- We describe the standard metadata annotations and XML equivalents throughout
- this chapter. The full schema for XML mapping files is available in
- <xref linkend="jpa_overview_meta_xml"/>.
- JPA also standardizes relational mapping metadata and named
- query metadata, which we discuss in <xref linkend="jpa_overview_mapping"/>
- and <xref linkend="jpa_overview_query_named"/> respectively.
- </para>
- <note>
- <para>
- OpenJPA defines many useful annotations beyond the standard set. See
- <xref linkend="ref_guide_meta_ejb"/> and
- <xref linkend="ref_guide_meta_ext"/> in the Reference Guide for details.
- <!-- ### EJB -->
- There are currently no XML equivalents for these extension annotations.
+ </orderedlist>
+ <para>
+We describe the standard metadata annotations and XML equivalents throughout
+this chapter. The full schema for XML mapping files is available in
+<xref linkend="jpa_overview_meta_xml"></xref>. JPA also standardizes relational
+mapping metadata and named query metadata, which we discuss in
+<xref linkend="jpa_overview_mapping"></xref> and
+<xref linkend="jpa_overview_query_named"></xref> respectively.
</para>
- </note>
- <mediaobject>
+ <note>
+ <para>
+OpenJPA defines many useful annotations beyond the standard set. See
+<xref linkend="ref_guide_meta_jpa"></xref> and
+<xref linkend="ref_guide_meta_ext"></xref>
+in the Reference Guide for details. There are currently no XML equivalents for
+these extension annotations.
+ </para>
+ </note>
+ <mediaobject>
<imageobject>
-<!-- PNG image data, 553 x 580 (see README) -->
- <imagedata fileref="img/jpa-meta-model.png" width="369"/>
+ <!-- PNG image data, 553 x 580 (see README) -->
+ <imagedata fileref="img/jpa-meta-model.png" width="369">
+ </imagedata>
</imageobject>
- </mediaobject>
- <para>
- Through the course of this chapter, we will create the persistent object
- model above.
- </para>
- <section id="jpa_overview_meta_class">
- <title>Class Metadata</title>
- <para>
- The following metadata annotations and XML elements apply to persistent
- class declarations.
+ </mediaobject>
+ <para>
+Through the course of this chapter, we will create the persistent object model
+above.
</para>
- <section id="jpa_overview_meta_entity">
- <title>Entity</title>
- <indexterm zone="jpa_overview_meta_entity">
- <primary>Entity</primary>
- <secondary>annotation</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_entity">
- <primary>metadata</primary>
- <secondary>Entity</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_entity">
- <primary>annotations</primary>
- <secondary>Entity</secondary>
- </indexterm>
- <para>
- The <classname>Entity</classname> annotation denotes an entity
- class. All entity classes must have this annotation. The
- <classname>Entity</classname> annotation takes one optional
- property:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>String name</literal>: Name used to refer to the
- entity in queries. Must not be a reserved literal
- in JPQL. Defaults to the unqualified name of the entity
- class.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The equivalent XML element is <literal>entity</literal>. It has
- the following attributes:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>class</literal>: The entity class. This attribute
- is required.
- </para>
- </listitem>
- <listitem>
- <para><literal>name</literal>: Named used to refer to the class in
- queries. See the name property above.
- </para>
- </listitem>
- <listitem>
- <para><literal>access</literal>: The access type to use for the
- class. Must either be <literal>FIELD</literal> or
- <literal>PROPERTY</literal>. For details on access
- types, see <xref linkend="jpa_overview_meta_field"/>.
- </para>
- </listitem>
- </itemizedlist>
- <note>
- <para>
- OpenJPA uses a process called <emphasis>enhancement</emphasis> to
- modify the bytecode of entities for transparent
- lazy loading and immediate dirty tracking. See
- <xref linkend="ref_guide_pc_enhance"/> in the Reference Guide
- for details on enhancement.
+ <section id="jpa_overview_meta_class">
+ <title>
+ Class Metadata
+ </title>
+ <para>
+The following metadata annotations and XML elements apply to persistent class
+declarations.
</para>
- </note>
+ <section id="jpa_overview_meta_entity">
+ <title>
+ Entity
+ </title>
+ <indexterm zone="jpa_overview_meta_entity">
+ <primary>
+ Entity
+ </primary>
+ <secondary>
+ annotation
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_entity">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ Entity
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_entity">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ Entity
+ </secondary>
+ </indexterm>
+ <para>
+The <classname>Entity</classname> annotation denotes an entity class. All entity
+classes must have this annotation. The <classname>Entity</classname> annotation
+takes one optional property:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>String name</literal>: Name used to refer to the entity in queries.
+Must not be a reserved literal in JPQL. Defaults to the unqualified name of the
+entity class.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+The equivalent XML element is <literal>entity</literal>. It has the following
+attributes:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>class</literal>: The entity class. This attribute is required.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>name</literal>: Named used to refer to the class in queries. See the
+name property above.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>access</literal>: The access type to use for the class. Must either be
+<literal>FIELD</literal> or <literal>PROPERTY</literal>. For details on access
+types, see <xref linkend="jpa_overview_meta_field"></xref>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+OpenJPA uses a process called <emphasis>enhancement</emphasis> to modify the
+bytecode of entities for transparent lazy loading and immediate dirty tracking.
+See <xref linkend="ref_guide_pc_enhance"></xref> in the Reference Guide for
+details on enhancement.
+ </para>
+ </note>
</section>
<section id="jpa_overview_meta_idclass">
- <title>Id Class</title>
- <indexterm zone="jpa_overview_meta_idclass">
- <primary>IdClass</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_idclass">
- <primary>metadata</primary>
- <secondary>IdClass</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_idclass">
- <primary>annotations</primary>
- <secondary>IdClass</secondary>
- </indexterm>
- <para>
- As we discussed in <xref linkend="jpa_overview_pc_identitycls"/>,
- entities with multiple identity fields must use an <emphasis>
- identity class</emphasis> to encapsulate their persistent identity.
- The <classname>IdClass</classname> annotation specifies this class.
- It accepts a single <classname>java.lang.Class</classname> value.
- </para>
- <para>
- The equivalent XML element is <literal>id-class</literal>, which has
- a single attribute:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>class</literal>: This required attribute lists
- the class name for the identity class.
- </para>
- </listitem>
- </itemizedlist>
+ <title>
+ Id Class
+ </title>
+ <indexterm zone="jpa_overview_meta_idclass">
+ <primary>
+ IdClass
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_idclass">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ IdClass
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_idclass">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ IdClass
+ </secondary>
+ </indexterm>
+ <para>
+As we discussed in <xref linkend="jpa_overview_pc_identitycls"></xref>,
+entities with multiple identity fields must use an <emphasis> identity class
+</emphasis> to encapsulate their persistent identity. The <classname>IdClass
+</classname> annotation specifies this class. It accepts a single <classname>
+java.lang.Class</classname> value.
+ </para>
+ <para>
+The equivalent XML element is <literal>id-class</literal>, which has a single
+attribute:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>class</literal>: This required attribute lists the class name for the
+identity class.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
<section id="jpa_overview_meta_embeddablesuper">
- <title>Mapped Superclass</title>
- <indexterm zone="jpa_overview_meta_embeddablesuper">
- <primary>MappedSuperclass</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_embeddablesuper">
- <primary>metadata</primary>
- <secondary>MappedSuperclass</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_embeddablesuper">
- <primary>annotations</primary>
- <secondary>MappedSuperclass</secondary>
- </indexterm>
- <para>
- A <emphasis>mapped superclass</emphasis> is a non-entity
- class that can define persistent state and mapping information for
- entity subclasses. Mapped superclasses are usually abstract.
- Unlike true entities, you cannot query a mapped superclass,
- pass a mapped superclass instance to any
- <classname>EntityManager</classname> or <classname>Query</classname>
- methods, or declare a persistent relation with a mapped
- superclass target.
- You denote a mapped superclass with the <classname>MappedSuperclass
- </classname> marker annotation.
- </para>
- <para>
- The equivalent XML element is <literal>mapped-superclass</literal>.
- It expects the following attributes:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>class</literal>: The entity class. This attribute
- is required.
- </para>
- </listitem>
- <listitem>
- <para><literal>access</literal>: The access type to use for the
- class. Must either be <literal>FIELD</literal> or
- <literal>PROPERTY</literal>. For details on access
- types, see <xref linkend="jpa_overview_meta_field"/>.
- </para>
- </listitem>
- </itemizedlist>
- <note>
- <para>
- OpenJPA allows you to query on mapped superclasses. A
- query on a mapped superclass will return all matching
- subclass instances. OpenJPA also allows you to declare relations
- to mapped superclass types; however, you cannot query across
- these relations.
- </para>
- </note>
+ <title>
+ Mapped Superclass
+ </title>
+ <indexterm zone="jpa_overview_meta_embeddablesuper">
+ <primary>
+ MappedSuperclass
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_embeddablesuper">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ MappedSuperclass
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_embeddablesuper">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ MappedSuperclass
+ </secondary>
+ </indexterm>
+ <para>
+A <emphasis>mapped superclass</emphasis> is a non-entity class that can define
+persistent state and mapping information for entity subclasses. Mapped
+superclasses are usually abstract. Unlike true entities, you cannot query a
+mapped superclass, pass a mapped superclass instance to any <classname>
+EntityManager</classname> or <classname>Query</classname> methods, or declare a
+persistent relation with a mapped superclass target. You denote a mapped
+superclass with the <classname>MappedSuperclass</classname> marker annotation.
+ </para>
+ <para>
+The equivalent XML element is <literal>mapped-superclass</literal>. It expects
+the following attributes:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>class</literal>: The entity class. This attribute is required.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>access</literal>: The access type to use for the class. Must either be
+<literal>FIELD</literal> or <literal>PROPERTY</literal>. For details on access
+types, see <xref linkend="jpa_overview_meta_field"></xref>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+OpenJPA allows you to query on mapped superclasses. A query on a mapped
+superclass will return all matching subclass instances. OpenJPA also allows you
+to declare relations to mapped superclass types; however, you cannot query
+across these relations.
+ </para>
+ </note>
</section>
<section id="jpa_overview_meta_embeddable">
- <title>Embeddable</title>
- <indexterm zone="jpa_overview_meta_embeddable">
- <primary>Embeddable</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_embeddable">
- <primary>metadata</primary>
- <secondary>Embeddable</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_embeddable">
- <primary>annotations</primary>
- <secondary>Embeddable</secondary>
- </indexterm>
- <para>
- The <classname>Embeddable</classname> annotation designates an
- embeddable persistent class. Embeddable instances are stored as
- part of the record of their owning instance. All embeddable
- classes must have this annotation.
- </para>
- <para>
- A persistent class can either be an entity or an embeddable class,
- but not both.
- </para>
- <para>
- The equivalent XML element is <literal>embeddable</literal>.
- It understands the following attributes:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>class</literal>: The entity class. This attribute
- is required.
- </para>
- </listitem>
- <listitem>
- <para><literal>access</literal>: The access type to use for the
- class. Must either be <literal>FIELD</literal> or
- <literal>PROPERTY</literal>. For details on access
- types, see <xref linkend="jpa_overview_meta_field"/>.
- </para>
- </listitem>
- </itemizedlist>
- <note>
- <para>
- OpenJPA allows a persistent class to be both an entity and
- an embeddable class. Instances of the class will act as
- entites when persisted explicitly or assigned to non-embedded
- fields of entities. Instances will act as embedded values
- when assigned to embedded fields of entities.
- </para>
+ <title>
+ Embeddable
+ </title>
+ <indexterm zone="jpa_overview_meta_embeddable">
+ <primary>
+ Embeddable
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_embeddable">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ Embeddable
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_embeddable">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ Embeddable
+ </secondary>
+ </indexterm>
<para>
- To signal that a class is both an entity and an embeddable class
- in OpenJPA, simply add both the <literal>@Entity</literal> and the
- <literal>@Embeddable</literal> annotations to the class.
- </para>
- </note>
+The <classname>Embeddable</classname> annotation designates an embeddable
+persistent class. Embeddable instances are stored as part of the record of their
+owning instance. All embeddable classes must have this annotation.
+ </para>
+ <para>
+A persistent class can either be an entity or an embeddable class, but not both.
+ </para>
+ <para>
+The equivalent XML element is <literal>embeddable</literal>. It understands the
+following attributes:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>class</literal>: The entity class. This attribute is required.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>access</literal>: The access type to use for the class. Must either be
+<literal>FIELD</literal> or <literal>PROPERTY</literal>. For details on access
+types, see <xref linkend="jpa_overview_meta_field"></xref>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+OpenJPA allows a persistent class to be both an entity and an embeddable class.
+Instances of the class will act as entites when persisted explicitly or assigned
+to non-embedded fields of entities. Instances will act as embedded values when
+assigned to embedded fields of entities.
+ </para>
+ <para>
+To signal that a class is both an entity and an embeddable class in OpenJPA,
+simply add both the <literal>@Entity</literal> and the <literal>@Embeddable
+</literal> annotations to the class.
+ </para>
+ </note>
</section>
<section id="jpa_overview_meta_entity_listeners">
- <title>EntityListeners</title>
- <indexterm zone="jpa_overview_meta_entity_listeners">
- <primary>EntityListeners</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_entity_listeners">
- <primary>entity-listeners</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_entity_listeners">
- <primary>metadata</primary>
- <secondary>EntityListeners</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_entity_listeners">
- <primary>annotations</primary>
- <secondary>EntityListeners</secondary>
- </indexterm>
- <para>
- An entity may list its lifecycle event listeners
- in the <classname>EntityListeners</classname> annotation.
- This value of this annotation is an array of the listener
- <classname>Class</classname>es for the entity.
- The equivalent XML element is <literal>entity-listeners</literal>.
- For more details on entity listeners, see
- <xref linkend="jpa_overview_pc_callbacks"/>.
- </para>
+ <title>
+ EntityListeners
+ </title>
+ <indexterm zone="jpa_overview_meta_entity_listeners">
+ <primary>
+ EntityListeners
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_entity_listeners">
+ <primary>
+ entity-listeners
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_entity_listeners">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ EntityListeners
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_entity_listeners">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ EntityListeners
+ </secondary>
+ </indexterm>
+ <para>
+An entity may list its lifecycle event listeners in the <classname>
+EntityListeners</classname> annotation. This value of this annotation is an
+array of the listener <classname>Class</classname> es for the entity. The
+equivalent XML element is <literal>entity-listeners</literal>. For more details
+on entity listeners, see <xref linkend="jpa_overview_pc_callbacks"></xref>.
+ </para>
</section>
<section id="jpa_overview_meta_classex">
- <title>Example</title>
- <para>
- Here are the class declarations for our persistent object model,
- annotated with the appropriate persistence metadata. Note that
- <classname>Magazine</classname> declares an identity class, and
- that <classname>Document</classname> and <classname>Address
- </classname> are a mapped superclass and an embeddable class,
- respectively. <classname>LifetimeSubscription</classname> and
- <classname>TrialSubscription</classname> override the default
- entity name to supply a shorter alias for use in queries.
- </para>
- <example id="jpa_overview_meta_classlisting">
- <title>Class Metadata</title>
- <programlisting format="linespecific">
+ <title>
+ Example
+ </title>
+ <para>
+Here are the class declarations for our persistent object model, annotated with
+the appropriate persistence metadata. Note that <classname>Magazine</classname>
+declares an identity class, and that <classname>Document</classname> and
+<classname>Address</classname> are a mapped superclass and an embeddable class,
+respectively. <classname>LifetimeSubscription</classname> and <classname>
+TrialSubscription</classname> override the default entity name to supply a
+shorter alias for use in queries.
+ </para>
+ <example id="jpa_overview_meta_classlisting">
+ <title>
+ Class Metadata
+ </title>
+<programlisting>
package org.mag;
@Entity
@@ -414,10 +493,10 @@
...
}
</programlisting>
- <para>
- The equivalent declarations in XML:
- </para>
- <programlisting format="linespecific">
+ <para>
+The equivalent declarations in XML:
+ </para>
+<programlisting>
<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
@@ -455,661 +534,814 @@
</embeddable>
</entity-mappings>
</programlisting>
- </example>
+ </example>
</section>
- </section>
- <section id="jpa_overview_meta_field">
- <title>Field and Property Metadata</title>
+ </section>
+ <section id="jpa_overview_meta_field">
+ <title>
+ Field and Property Metadata
+ </title>
<para>
- The persistence implementation must be able to retrieve and set the
- persistent state of your entities, mapped superclasses, and
- embeddable types. JPA offers two modes of
- persistent state access: <emphasis>field access</emphasis>, and
- <emphasis>property access</emphasis>. Under field access, the
- implementation injects state directly into your persistent fields, and
- retrieves changed state from your fields as well. To declare field
- access on an entity with XML metadata, set the <literal>access
- </literal> attribute of your <literal>entity</literal> XML element to
- <literal>FIELD</literal>. To use field access for an entity using
- annotation metadata, simply place your metadata and mapping annotations
- on your field declarations:
- </para>
- <programlisting format="linespecific">
+The persistence implementation must be able to retrieve and set the persistent
+state of your entities, mapped superclasses, and embeddable types. JPA offers
+two modes of persistent state access: <emphasis>field access</emphasis>, and
+<emphasis>property access</emphasis>. Under field access, the implementation
+injects state directly into your persistent fields, and retrieves changed state
+from your fields as well. To declare field access on an entity with XML
+metadata, set the <literal>access</literal> attribute of your <literal>entity
+</literal> XML element to <literal>FIELD</literal>. To use field access for an
+entity using annotation metadata, simply place your metadata and mapping
+annotations on your field declarations:
+ </para>
+<programlisting>
@ManyToOne
private Company publisher;
</programlisting>
- <para><indexterm><primary>metadata</primary><secondary>property access</secondary></indexterm><indexterm><primary>persistent classes</primary><secondary>property access</secondary></indexterm><indexterm><primary>persistent properties</primary><seealso>persistent fields</seealso></indexterm>
- Property access, on the other hand, retrieves and loads state through
- JavaBean "getter" and "setter" methods. For a property
- <literal>p</literal> of type <literal>T</literal>, you must define the
- following getter method:
- </para>
- <programlisting format="linespecific">
+ <para>
+ <indexterm>
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ property access
+ </secondary>
+ </indexterm>
+ <indexterm>
+ <primary>
+ persistent classes
+ </primary>
+ <secondary>
+ property access
+ </secondary>
+ </indexterm>
+ <indexterm>
+ <primary>
+ persistent properties
+ </primary>
+ <seealso>
+ persistent fields
+ </seealso>
+ </indexterm>
+Property access, on the other hand, retrieves and loads state through JavaBean
+"getter" and "setter" methods. For a property <literal>p</literal> of type
+<literal>T</literal>, you must define the following getter method:
+ </para>
+<programlisting>
T getP ();
</programlisting>
<para>
- For boolean properties, this is also acceptable:
- </para>
- <programlisting format="linespecific">
+For boolean properties, this is also acceptable:
+ </para>
+<programlisting>
boolean isP ();
</programlisting>
<para>
- You must also define the following setter method:
- </para>
- <programlisting format="linespecific">
+You must also define the following setter method:
+ </para>
+<programlisting>
void setP (T value);
</programlisting>
<para>
- To use property access, set your <literal>entity</literal> element's
- <literal>access</literal> attribute to <literal>PROPERTY</literal>, or
- place your metadata and mapping annotations on the getter method:
- </para>
- <programlisting format="linespecific">
+To use property access, set your <literal>entity</literal> element's <literal>
+access</literal> attribute to <literal>PROPERTY</literal>, or place your
+metadata and mapping annotations on the getter method:
+ </para>
+<programlisting>
@ManyToOne
private Company getPublisher () { ... }
private void setPublisher (Company publisher) { ... }
</programlisting>
<warning>
- <para>
- When using property access, only the getter and setter method for
- a property should ever access the underlying persistent field
- directly. Other methods, including internal business methods in
- the persistent class, should go through the getter and setter
- methods when manipulating persistent state.
- </para>
- <para>
- Also, take care when adding business logic to your
- getter and setter methods. Consider that they are invoked by the
- persistence implementation to load and retrieve all persistent
- state; other side effects might not be desirable.
- </para>
+ <para>
+When using property access, only the getter and setter method for a property
+should ever access the underlying persistent field directly. Other methods,
+including internal business methods in the persistent class, should go through
+the getter and setter methods when manipulating persistent state.
+ </para>
+ <para>
+Also, take care when adding business logic to your getter and setter methods.
+Consider that they are invoked by the persistence implementation to load and
+retrieve all persistent state; other side effects might not be desirable.
+ </para>
</warning>
<para>
- Each class must use either field access or property access for all
- state; you cannot use both access types within the same class.
- Additionally, a subclass must use the same access type as its
- superclass.
- </para>
+Each class must use either field access or property access for all state; you
+cannot use both access types within the same class. Additionally, a subclass
+must use the same access type as its superclass.
+ </para>
<para>
- The remainder of this document uses the term
- "persistent field" to refer to either a persistent field or a
- persistent property.
- </para>
+The remainder of this document uses the term "persistent field" to refer to
+either a persistent field or a persistent property.
+ </para>
<section id="jpa_overview_meta_transient">
- <title>Transient</title>
- <indexterm zone="jpa_overview_meta_transient">
- <primary>Transient</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_transient">
- <primary>metadata</primary>
- <secondary>Transient</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_transient">
- <primary>annotations</primary>
- <secondary>Transient</secondary>
- </indexterm>
- <para>
- The <classname>Transient</classname> annotation specifies that a
- field is non-persistent. Use it to exclude fields from management
- that would otherwise be persistent. <classname>
- Transient</classname> is a marker annotation only; it has no
- properties.
- </para>
- <para>
- The equivalent XML element is <literal>transient</literal>. It
- has a single attribute:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>name</literal>: The transient field or property
- name. This attribute is required.
- </para>
- </listitem>
- </itemizedlist>
+ <title>
+ Transient
+ </title>
+ <indexterm zone="jpa_overview_meta_transient">
+ <primary>
+ Transient
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_transient">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ Transient
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_transient">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ Transient
+ </secondary>
+ </indexterm>
+ <para>
+The <classname>Transient</classname> annotation specifies that a field is
+non-persistent. Use it to exclude fields from management that would otherwise be
+persistent. <classname> Transient</classname> is a marker annotation only; it
+has no properties.
+ </para>
+ <para>
+The equivalent XML element is <literal>transient</literal>. It has a single
+attribute:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>name</literal>: The transient field or property name. This attribute
+is required.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
<section id="jpa_overview_meta_id">
- <title>Id</title>
- <indexterm zone="jpa_overview_meta_id">
- <primary>Id</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_id">
- <primary>metadata</primary>
- <secondary>Id</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_id">
- <primary>annotations</primary>
- <secondary>Id</secondary>
- </indexterm>
- <para>
- Annotate your simple identity fields with <classname>Id</classname>.
- This annotation has no properties. We explore entity identity and
- identity fields in <xref linkend="jpa_overview_pc_id"/>.
- </para>
- <para>
- The equivalent XML element is <literal>id</literal>. It has one
- required attribute:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>name</literal>: The name of the identity field or
- property.
- </para>
- </listitem>
- </itemizedlist>
+ <title>
+ Id
+ </title>
+ <indexterm zone="jpa_overview_meta_id">
+ <primary>
+ Id
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_id">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ Id
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_id">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ Id
+ </secondary>
+ </indexterm>
+ <para>
+Annotate your simple identity fields with <classname>Id</classname>. This
+annotation has no properties. We explore entity identity and identity fields in
+<xref linkend="jpa_overview_pc_id"></xref>.
+ </para>
+ <para>
+The equivalent XML element is <literal>id</literal>. It has one required
+attribute:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>name</literal>: The name of the identity field or property.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
<section id="jpa_overview_meta_gen">
- <title>Generated Value</title>
- <indexterm zone="jpa_overview_meta_gen">
- <primary>GeneratedValue</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_gen">
- <primary>metadata</primary>
- <secondary>GeneratedValue</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_gen">
- <primary>annotations</primary>
- <secondary>GeneratedValue</secondary>
- </indexterm>
- <para>
- The previous section showed you how to declare your identity
- fields with the <classname>Id</classname> annotation. It is often
- convenient to allow the persistence implementation to assign a
- unique value to your identity fields automatically. JPA
- includes the the <classname>GeneratedValue</classname>
- annotation for this purpose. You can only apply the <classname>
- GeneratedValue</classname> annotation to numeric fields. It has
- the following properties:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>GenerationType strategy</literal>: Enum value
- specifying how to auto-generate the field value.
- The <classname>GenerationType</classname> enum has the
- following values:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>GeneratorType.AUTO</literal>: The default.
- Assign the field a generated value, leaving the
- details to the JPA vendor.
- </para>
- </listitem>
- <listitem>
- <para><literal>GenerationType.IDENTITY</literal>: The
- database will assign an identity value on insert.
- </para>
- </listitem>
- <listitem>
- <para><literal>GenerationType.SEQUENCE</literal>: Use a
- datastore sequence to generate a field value.
- </para>
- </listitem>
- <listitem>
- <para><literal>GenerationType.TABLE</literal>: Use a
- sequence table to generate a field value.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para><literal>String generator</literal>: The name of a
- generator defined in mapping metadata. We show you how
- to define named generators in
- <xref linkend="jpa_overview_mapping_sequence"/>.
- If the <classname>GenerationType</classname> is set but
- this property is unset, the JPA implementation
- uses appropriate defaults for the selected generation type.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The equivalent XML element is <literal>generated-value</literal>,
- which includes the following attributes:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>strategy</literal>: One of <literal>
- TABLE</literal>, <literal>SEQUENCE</literal>, <literal>
- IDENTITY</literal>, or <literal>AUTO</literal>, defaulting
- to <literal>AUTO</literal>.
- </para>
- </listitem>
- <listitem>
- <para><literal>generator</literal>: Equivalent to the generator
- property listed above.
- </para>
- </listitem>
- </itemizedlist>
- <note>
- <para>
- OpenJPA allows you to use the <classname>GeneratedValue</classname>
- annotation on any field, not just identity fields.
- Before using the <literal>IDENTITY</literal> generation
- strategy, however, read
- <xref linkend="ref_guide_pc_oid_pkgen_autoinc"/>
- in the Reference Guide.
- </para>
+ <title>
+ Generated Value
+ </title>
+ <indexterm zone="jpa_overview_meta_gen">
+ <primary>
+ GeneratedValue
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_gen">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ GeneratedValue
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_gen">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ GeneratedValue
+ </secondary>
+ </indexterm>
<para>
- OpenJPA also offers two additional
- generator strategies for non-numeric fields, which you can
- access by setting <literal>strategy</literal> to
- <literal>AUTO</literal> (the default), and setting
- the <literal>generator</literal> string to:
- </para>
- <itemizedlist>
- <listitem>
- <para><indexterm><primary>mapping metadata</primary><secondary>uuid-string</secondary></indexterm><indexterm><primary>uuid-string</primary></indexterm><literal>uuid-string</literal>: OpenJPA will generate a
- 128-bit UUID unique
- within the network, represented as a 16-character
- string. For more information on UUIDs, see the IETF
- UUID draft specification at:
- <ulink url="http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/">
- http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/
- </ulink></para>
- </listitem>
- <listitem>
- <para><indexterm><primary>mapping metadata</primary><secondary>uuid-hex</secondary></indexterm><indexterm><primary>uuid-hex</primary></indexterm><literal>uuid-hex</literal>: Same as <literal>
- uuid-string</literal>, but represents the UUID as
- a 32-character hexadecimal string.
+The previous section showed you how to declare your identity fields with the
+<classname>Id</classname> annotation. It is often convenient to allow the
+persistence implementation to assign a unique value to your identity fields
+automatically. JPA includes the the <classname>GeneratedValue</classname>
+annotation for this purpose. You can only apply the <classname> GeneratedValue
+</classname> annotation to numeric fields. It has the following properties:
</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>GenerationType strategy</literal>: Enum value specifying how to
+auto-generate the field value. The <classname>GenerationType</classname> enum
+has the following values:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>GeneratorType.AUTO</literal>: The default. Assign the field a
+generated value, leaving the details to the JPA vendor.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>GenerationType.IDENTITY</literal>: The database will assign an
+identity value on insert.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>GenerationType.SEQUENCE</literal>: Use a datastore sequence to
+generate a field value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>GenerationType.TABLE</literal>: Use a sequence table to generate a
+field value.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+<literal>String generator</literal>: The name of a generator defined in mapping
+metadata. We show you how to define named generators in
+<xref linkend="jpa_overview_mapping_sequence"></xref>. If the <classname>
+GenerationType</classname> is set but this property is unset, the JPA
+implementation uses appropriate defaults for the selected generation type.
+ </para>
+ </listitem>
</itemizedlist>
<para>
- These string constants are defined in
- <ulink url="../../api/openjpa/persistence/Generator.html"><classname>org.apache.openjpa.persistence.Generator</classname></ulink>.
- </para>
- </note>
+The equivalent XML element is <literal>generated-value</literal>, which
+includes the following attributes:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>strategy</literal>: One of <literal> TABLE</literal>, <literal>
+SEQUENCE</literal>, <literal> IDENTITY</literal>, or <literal>AUTO</literal>,
+defaulting to <literal>AUTO</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>generator</literal>: Equivalent to the generator property listed
+above.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+OpenJPA allows you to use the <classname>GeneratedValue</classname> annotation
+on any field, not just identity fields. Before using the <literal>IDENTITY
+</literal> generation strategy, however, read
+<xref linkend="ref_guide_pc_oid_pkgen_autoinc"></xref> in the Reference Guide.
+ </para>
+ <para>
+OpenJPA also offers two additional generator strategies for non-numeric fields,
+which you can access by setting <literal>strategy</literal> to <literal>AUTO
+</literal> (the default), and setting the <literal>generator</literal> string
+to:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ uuid-string
+ </secondary>
+ </indexterm>
+ <indexterm>
+ <primary>
+ uuid-string
+ </primary>
+ </indexterm>
+<literal>uuid-string</literal>: OpenJPA will generate a 128-bit UUID unique
+within the network, represented as a 16-character string. For more information
+on UUIDs, see the IETF UUID draft specification at:
+<ulink url="http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/">
+http://www1.ics.uci.edu/~ejw/authoring/uuid-guid/</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mapping metadata
+ </primary>
+ <secondary>
+ uuid-hex
+ </secondary>
+ </indexterm>
+ <indexterm>
+ <primary>
+ uuid-hex
+ </primary>
+ </indexterm>
+<literal>uuid-hex</literal>: Same as <literal> uuid-string</literal>, but
+represents the UUID as a 32-character hexadecimal string.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+These string constants are defined in
+<ulink url="../../api/openjpa/persistence/Generator.html"><classname>
+org.apache.openjpa.persistence.Generator</classname></ulink>.
+ </para>
+ </note>
</section>
<section id="jpa_overview_meta_embedid">
- <title>Embedded Id</title>
- <indexterm zone="jpa_overview_meta_embedid">
- <primary>EmbeddedId</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_embedid">
- <primary>metadata</primary>
- <secondary>EmbeddedId</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_embedid">
- <primary>annotations</primary>
- <secondary>EmbeddedId</secondary>
- </indexterm>
- <para>
- If your entity has multiple identity values, you may declare
- multiple <literal>@Id</literal> fields, or you may declare a single
- <literal>@EmbeddedId</literal> field. The type of a field
- annotated with <classname>EmbeddedId</classname> must be an
- embeddable entity class. The fields of this embeddable class are
- considered the identity values of the owning entity. We explore
- entity identity and identity fields in
- <xref linkend="jpa_overview_pc_id"/>.
- </para>
- <para>
- The <classname>EmbeddedId</classname> annotation has no properties.
- </para>
- <para>
- The equivalent XML element is <literal>embedded-id</literal>. It
- has one required attribute:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>name</literal>: The name of the identity field or
- property.
- </para>
- </listitem>
- </itemizedlist>
+ <title>
+ Embedded Id
+ </title>
+ <indexterm zone="jpa_overview_meta_embedid">
+ <primary>
+ EmbeddedId
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_embedid">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ EmbeddedId
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_embedid">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ EmbeddedId
+ </secondary>
+ </indexterm>
+ <para>
+If your entity has multiple identity values, you may declare multiple <literal>
+@Id</literal> fields, or you may declare a single <literal>@EmbeddedId</literal>
+field. The type of a field annotated with <classname>EmbeddedId</classname> must
+be an embeddable entity class. The fields of this embeddable class are
+considered the identity values of the owning entity. We explore entity identity
+and identity fields in <xref linkend="jpa_overview_pc_id"></xref>.
+ </para>
+ <para>
+The <classname>EmbeddedId</classname> annotation has no properties.
+ </para>
+ <para>
+The equivalent XML element is <literal>embedded-id</literal>. It has one
+required attribute:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>name</literal>: The name of the identity field or property.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
<section id="jpa_overview_meta_version">
- <title>Version</title>
- <indexterm zone="jpa_overview_meta_version">
- <primary>Version</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_version">
- <primary>metadata</primary>
- <secondary>Version</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_version">
- <primary>annotations</primary>
- <secondary>Version</secondary>
- </indexterm>
- <para>
- Use the <classname>Version</classname> annotation to designate a
- version field. <xref linkend="jpa_overview_pc_version"/>
- explained the importance of version fields to JPA.
- This is a marker annotation; it has no properties.
- </para>
- <para>
- The equivalent XML element is <literal>version</literal>, which
- has a single attribute:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>name</literal>: The name of the version field or
- property. This attribute is required.
- </para>
- </listitem>
- </itemizedlist>
+ <title>
+ Version
+ </title>
+ <indexterm zone="jpa_overview_meta_version">
+ <primary>
+ Version
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_version">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ Version
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_version">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ Version
+ </secondary>
+ </indexterm>
+ <para>
+Use the <classname>Version</classname> annotation to designate a version field.
+<xref linkend="jpa_overview_pc_version"></xref> explained the importance of
+version fields to JPA. This is a marker annotation; it has no properties.
+ </para>
+ <para>
+The equivalent XML element is <literal>version</literal>, which has a single
+attribute:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>name</literal>: The name of the version field or property. This
+attribute is required.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
<section id="jpa_overview_meta_basic">
- <title>Basic</title>
- <indexterm zone="jpa_overview_meta_basic">
- <primary>Basic</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_basic">
- <primary>metadata</primary>
- <secondary>Basic</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_basic">
- <primary>annotations</primary>
- <secondary>Basic</secondary>
- </indexterm>
- <para><classname>Basic</classname> signifies a standard value persisted
- as-is to the datastore. You can use the <classname>Basic
- </classname> annotation on persistent fields of the following types:
- primitives, primitive wrappers,
- <classname>java.lang.String</classname>,
- <classname>byte[]</classname>,
- <classname>Byte[]</classname>,
- <classname>char[]</classname>,
- <classname>Character[]</classname>,
- <classname>java.math.BigDecimal</classname>,
- <classname>java.math.BigInteger</classname>,
- <classname>java.util.Date</classname>,
- <classname>java.util.Calendar</classname>,
- <classname>java.sql.Date</classname>,
- <classname>java.sql.Timestamp</classname>,
- <classname>Enum</classname>s, and
- <classname>Serializable</classname> types.
- </para>
- <para><classname>Basic</classname> declares these properties:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>FetchType fetch</literal>: Whether to load the
- field eagerly (<literal>FetchType.EAGER</literal>) or
- lazily (<literal>FetchType.LAZY</literal>).
- Defaults to <literal>FetchType.EAGER</literal>.
- </para>
- </listitem>
- <listitem>
- <para><literal>boolean optional</literal>: Whether the datastore
- allows null values. Defaults to true.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The equivalent XML element is <literal>basic</literal>. It has
- the following attributes:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>name</literal>: The name of the field or property.
- This attribute is required.
- </para>
- </listitem>
- <listitem>
- <para><literal>fetch</literal>: One of <literal>EAGER</literal>
- or<literal>LAZY</literal>.
- </para>
- </listitem>
- <listitem>
- <para><literal>optional</literal>: Boolean indicating whether the
- field value may be null.
- </para>
- </listitem>
- </itemizedlist>
- <section id="jpa_overview_meta_fetch">
- <title>Fetch Type</title>
- <indexterm zone="jpa_overview_meta_fetch">
- <primary>eager fetching</primary>
- <secondary>FetchType</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_fetch">
- <primary>FetchType</primary>
- <seealso>eager fetching</seealso>
- </indexterm>
- <indexterm zone="jpa_overview_meta_fetch">
- <primary>metadata</primary>
- <secondary>FetchType</secondary>
- </indexterm>
- <para>
- Many metadata annotations in JPA have a
- <literal>fetch</literal> property. This property can take
- on one of two values: <literal>FetchType.EAGER</literal> or
- <literal>FetchType.LAZY</literal>. <literal>FetchType.EAGER
- </literal> means that the field is loaded by the JPA
- implementation before it returns the persistent object to you.
- Whenever you retrieve an entity from a query or from the
- <classname>EntityManager</classname>, you are guaranteed that
- all of its eager fields are populated with datastore data.
- </para>
- <para><literal>FetchType.LAZY</literal> is a hint to the JPA runtime
- that you want to defer loading of the field until you access it.
- This is called <emphasis>lazy loading</emphasis>. Lazy loading
- is completely transparent; when you attempt to read the field
- for the first time, the JPA runtime will load the value from the
- datastore and populate the field automatically. Lazy loading
- is only a hint and not a directive because some JPA
- implementations cannot lazy-load certain field types.
- </para>
+ <title>
+ Basic
+ </title>
+ <indexterm zone="jpa_overview_meta_basic">
+ <primary>
+ Basic
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_basic">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ Basic
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_basic">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ Basic
+ </secondary>
+ </indexterm>
<para>
- With a mix of eager and lazily-loaded fields, you can ensure
- that commonly-used fields load efficiently, and that other
- state loads transparently when accessed. As you will see
- in <xref linkend="jpa_overview_emfactory_perscontext"/>,
- you can also use eager fetching to ensure that entites have
- all needed data loaded before they become <emphasis>detached
- </emphasis> at the end of a persistence context.
- </para>
- <note>
- <para>
- OpenJPA can lazy-load any field type. OpenJPA also allows you
- to dynamically change which fields are eagerly or lazily
- loaded at runtime. See <xref linkend="ref_guide_fetch"/>
- in the Reference Guide for details.
- </para>
- <para>
- The Reference Guide details OpenJPA's eager fetching
- behavior in <xref linkend="ref_guide_perfpack_eager"/>.
- </para>
- </note>
- </section>
+<classname>Basic</classname> signifies a standard value persisted as-is to the
+datastore. You can use the <classname>Basic</classname> annotation on persistent
+fields of the following types: primitives, primitive wrappers, <classname>
+java.lang.String</classname>, <classname>byte[]</classname>, <classname>Byte[]
+</classname>, <classname>char[]</classname>, <classname>Character[]</classname>
+, <classname>java.math.BigDecimal</classname>, <classname>java.math.BigInteger
+</classname>, <classname>java.util.Date</classname>, <classname>
+java.util.Calendar</classname>, <classname>java.sql.Date</classname>,
+<classname>java.sql.Timestamp</classname>, <classname>Enum</classname> s, and
+<classname>Serializable</classname> types.
+ </para>
+ <para>
+<classname>Basic</classname> declares these properties:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>FetchType fetch</literal>: Whether to load the field eagerly (
+<literal>FetchType.EAGER</literal>) or lazily ( <literal>FetchType.LAZY
+</literal> ). Defaults to <literal>FetchType.EAGER</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>boolean optional</literal>: Whether the datastore allows null values.
+Defaults to true.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+The equivalent XML element is <literal>basic</literal>. It has the following
+attributes:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>name</literal>: The name of the field or property. This attribute is
+required.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>fetch</literal>: One of <literal>EAGER</literal> or <literal>LAZY
+</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>optional</literal>: Boolean indicating whether the field value may be
+null.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section id="jpa_overview_meta_fetch">
+ <title>
+ Fetch Type
+ </title>
+ <indexterm zone="jpa_overview_meta_fetch">
+ <primary>
+ eager fetching
+ </primary>
+ <secondary>
+ FetchType
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_fetch">
+ <primary>
+ FetchType
+ </primary>
+ <seealso>
+ eager fetching
+ </seealso>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_fetch">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ FetchType
+ </secondary>
+ </indexterm>
+ <para>
+Many metadata annotations in JPA have a <literal>fetch</literal> property. This
+property can take on one of two values: <literal>FetchType.EAGER</literal> or
+<literal>FetchType.LAZY</literal>. <literal>FetchType.EAGER</literal> means that
+the field is loaded by the JPA implementation before it returns the persistent
+object to you. Whenever you retrieve an entity from a query or from the
+<classname>EntityManager</classname>, you are guaranteed that all of its eager
+fields are populated with datastore data.
+ </para>
+ <para>
+<literal>FetchType.LAZY</literal> is a hint to the JPA runtime that you want to
+defer loading of the field until you access it. This is called <emphasis>lazy
+loading</emphasis>. Lazy loading is completely transparent; when you attempt to
+read the field for the first time, the JPA runtime will load the value from the
+datastore and populate the field automatically. Lazy loading is only a hint and
+not a directive because some JPA implementations cannot lazy-load certain field
+types.
+ </para>
+ <para>
+With a mix of eager and lazily-loaded fields, you can ensure that commonly-used
+fields load efficiently, and that other state loads transparently when accessed.
+As you will see in <xref linkend="jpa_overview_emfactory_perscontext"></xref>,
+you can also use eager fetching to ensure that entites have all needed data
+loaded before they become <emphasis>detached</emphasis> at the end of a
+persistence context.
+ </para>
+ <note>
+ <para>
+OpenJPA can lazy-load any field type. OpenJPA also allows you to dynamically
+change which fields are eagerly or lazily loaded at runtime. See
+<xref linkend="ref_guide_fetch"></xref> in the Reference Guide for details.
+ </para>
+ <para>
+The Reference Guide details OpenJPA's eager fetching behavior in
+<xref linkend="ref_guide_perfpack_eager"></xref>.
+ </para>
+ </note>
+ </section>
</section>
<section id="jpa_overview_meta_embedded">
- <title>Embedded</title>
- <indexterm zone="jpa_overview_meta_embedded">
- <primary>Embedded</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_embedded">
- <primary>metadata</primary>
- <secondary>Embedded</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_embedded">
- <primary>annotations</primary>
- <secondary>Embedded</secondary>
- </indexterm>
- <para>
- Use the <classname>Embedded</classname> marker annotation on
- embeddable field types. Embedded fields are mapped as part of the
- datastore record of the declaring entity. In our sample model,
- <classname>Author</classname> and <classname>Company</classname>
- each embed their <classname>Address</classname>, rather than
- forming a relation to an <classname>Address</classname> as a
- separate entity.
- </para>
- <para>
- The equivalent XML element is <literal>embedded</literal>, which
- expects a single attribute:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>name</literal>: The name of the field or property.
- This attribute is required.
- </para>
- </listitem>
- </itemizedlist>
+ <title>
+ Embedded
+ </title>
+ <indexterm zone="jpa_overview_meta_embedded">
+ <primary>
+ Embedded
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_embedded">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ Embedded
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_embedded">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ Embedded
+ </secondary>
+ </indexterm>
+ <para>
+Use the <classname>Embedded</classname> marker annotation on embeddable field
+types. Embedded fields are mapped as part of the datastore record of the
+declaring entity. In our sample model, <classname>Author</classname> and
+<classname>Company</classname> each embed their <classname>Address</classname>,
+rather than forming a relation to an <classname>Address</classname> as a
+separate entity.
+ </para>
+ <para>
+The equivalent XML element is <literal>embedded</literal>, which expects a
+single attribute:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>name</literal>: The name of the field or property. This attribute is
+required.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
<section id="jpa_overview_meta_manytoone">
- <title>Many To One</title>
- <indexterm zone="jpa_overview_meta_manytoone">
- <primary>ManyToOne</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_manytoone">
- <primary>metadata</primary>
- <secondary>ManyToOne</secondary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_manytoone">
- <primary>annotations</primary>
- <secondary>ManyToOne</secondary>
- </indexterm>
- <para>
- When an entity <literal>A</literal> references a single entity
- <literal>B</literal>, and other <literal>A</literal>s might also
- reference the same <literal>B</literal>, we say there is a
- <emphasis>many to one</emphasis> relation from
- <literal>A</literal> to <literal>B</literal>.
- In our sample model, for example, each magazine has a reference to
- its publisher. Multiple magazines might have the same publisher.
- We say, then, that the <literal>Magazine.publisher</literal> field
- is a many to one relation from magazines to publishers.
- </para>
- <para>
- JPA indicates many to one relations between
- entities with the <classname>ManyToOne</classname> annotation.
- This annotation has the following properties:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>Class targetEntity</literal>: The class of the
- related entity type.
- </para>
- </listitem>
- <listitem>
- <para><literal>CascadeType[] cascade</literal>: Array of enum
- values defining cascade behavior for this field. We
- explore cascades below. Defaults to an empty array.
- </para>
- </listitem>
- <listitem>
- <para><literal>FetchType fetch</literal>: Whether to load the
- field eagerly (<literal>FetchType.EAGER</literal>) or
- lazily (<literal>FetchType.LAZY</literal>).
- Defaults to <literal>FetchType.EAGER</literal>.
- See <xref linkend="jpa_overview_meta_fetch"/> above
- for details on fetch types.
- </para>
- </listitem>
- <listitem>
- <para><literal>boolean optional</literal>: Whether the related
- object must exist. If <literal>false</literal>, this
- field cannot be null. Defaults to <literal>true</literal>.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The equivalent XML element is <literal>many-to-one</literal>. It
- accepts the following attributes:
- </para>
- <itemizedlist>
- <listitem>
- <para><literal>name</literal>: The name of the field or property.
- This attribute is required.
- </para>
- </listitem>
- <listitem>
- <para><literal>target-entity</literal>: The class of the related
- type.
- </para>
- </listitem>
- <listitem>
- <para><literal>fetch</literal>: One of <literal>EAGER</literal>
- or<literal>LAZY</literal>.
- </para>
- </listitem>
- <listitem>
- <para><literal>optional</literal>: Boolean indicating whether the
- field value may be null.
- </para>
- </listitem>
- </itemizedlist>
- <section id="jpa_overview_meta_cascade">
- <title>Cascade Type</title>
- <indexterm zone="jpa_overview_meta_cascade">
- <primary>CascadeType</primary>
- </indexterm>
- <indexterm zone="jpa_overview_meta_cascade">
- <primary>metadata</primary>
- <secondary>CascadeType</secondary>
- </indexterm>
- <para>
- We introduce the JPA <classname>EntityManager
- </classname> in <xref linkend="jpa_overview_em"/>.
- The <classname>EntityManager</classname> has APIs to persist
- new entities, remove (delete) existing entities,
- refresh entity state from the datastore, and merge <emphasis>
- detached</emphasis> entity state back into the persistence
- context. We explore all of these APIs in detail later in the
- overview.
- </para>
+ <title>
+ Many To One
+ </title>
+ <indexterm zone="jpa_overview_meta_manytoone">
+ <primary>
+ ManyToOne
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_manytoone">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ ManyToOne
+ </secondary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_manytoone">
+ <primary>
+ annotations
+ </primary>
+ <secondary>
+ ManyToOne
+ </secondary>
+ </indexterm>
<para>
- When the <classname>EntityManager</classname> is performing the
- above operations, you can instruct it to automatically cascade
- the operation to the entities held in a persistent field with
- the <literal>cascade</literal> property of your metadata
- annotation. This process is recursive. The <literal>cascade
- </literal> property accepts an array of <classname>CascadeType
- </classname> enum values.
- </para>
+When an entity <literal>A</literal> references a single entity <literal>B
+</literal>, and other <literal>A</literal>s might also reference the same
+<literal>B</literal>, we say there is a <emphasis>many to one</emphasis>
+relation from <literal>A</literal> to <literal>B</literal>. In our sample
+model, for example, each magazine has a reference to its publisher. Multiple
+magazines might have the same publisher. We say, then, that the <literal>
+Magazine.publisher</literal> field is a many to one relation from magazines to
+publishers.
+ </para>
+ <para>
+JPA indicates many to one relations between entities with the <classname>
+ManyToOne</classname> annotation. This annotation has the following properties:
+ </para>
<itemizedlist>
- <listitem>
- <para><literal>CascadeType.PERSIST</literal>: When persisting
- an entity, also persist the entities held in this field.
- We suggest liberal application of this cascade rule,
- because if the <classname>EntityManager</classname>
- finds a field that references a new entity
- during flush, and the field does not use
- <literal>CascadeType.PERSIST</literal>, it is an error.
- </para>
- </listitem>
- <listitem>
- <para><literal>CascadeType.REMOVE</literal>: When deleting
- an entity, also delete the entities held in this field.
- </para>
- </listitem>
- <listitem>
- <para><literal>CascadeType.REFRESH</literal>: When refreshing
- an entity, also refresh the entities held in this field.
- </para>
- </listitem>
- <listitem>
- <para><literal>CascadeType.MERGE</literal>: When merging
- entity state, also merge the entities held in this
- field.
- </para>
- </listitem>
- </itemizedlist>
- <para><classname>CascadeType</classname> defines one additional value,
- <literal>CascadeType.ALL</literal>, that acts as a shortcut for
- all of the values above. The following annotations are
- equivalent:
- </para>
- <programlisting format="linespecific">
+ <listitem>
+ <para>
+<literal>Class targetEntity</literal>: The class of the related entity type.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>CascadeType[] cascade</literal>: Array of enum values defining cascade
+behavior for this field. We explore cascades below. Defaults to an empty array.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>FetchType fetch</literal>: Whether to load the field eagerly (
+<literal>FetchType.EAGER</literal>) or lazily ( <literal>FetchType.LAZY
+</literal> ). Defaults to <literal>FetchType.EAGER</literal>. See
+<xref linkend="jpa_overview_meta_fetch"></xref> above for details on fetch
+types.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>boolean optional</literal>: Whether the related object must exist. If
+<literal>false</literal>, this field cannot be null. Defaults to <literal>true
+</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+The equivalent XML element is <literal>many-to-one</literal>. It accepts the
+following attributes:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>name</literal>: The name of the field or property. This attribute is
+required.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>target-entity</literal>: The class of the related type.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>fetch</literal>: One of <literal>EAGER</literal> or <literal>LAZY
+</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>optional</literal>: Boolean indicating whether the field value may be
+null.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section id="jpa_overview_meta_cascade">
+ <title>
+ Cascade Type
+ </title>
+ <indexterm zone="jpa_overview_meta_cascade">
+ <primary>
+ CascadeType
+ </primary>
+ </indexterm>
+ <indexterm zone="jpa_overview_meta_cascade">
+ <primary>
+ metadata
+ </primary>
+ <secondary>
+ CascadeType
+ </secondary>
+ </indexterm>
+ <para>
+We introduce the JPA <classname>EntityManager</classname> in
+<xref linkend="jpa_overview_em"></xref>. The <classname>EntityManager
+</classname> has APIs to persist new entities, remove (delete) existing
+entities, refresh entity state from the datastore, and merge <emphasis> detached
+</emphasis> entity state back into the persistence context. We explore all of
+these APIs in detail later in the overview.
+ </para>
+ <para>
+When the <classname>EntityManager</classname> is performing the above
+operations, you can instruct it to automatically cascade the operation to the
+entities held in a persistent field with the <literal>cascade</literal> property
+of your metadata annotation. This process is recursive. The <literal>cascade
+</literal> property accepts an array of <classname>CascadeType</classname> enum
+values.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<literal>CascadeType.PERSIST</literal>: When persisting an entity, also persist
+the entities held in this field. We suggest liberal application of this cascade
+rule, because if the <classname>EntityManager</classname> finds a field that
+references a new entity during flush, and the field does not use <literal>
+CascadeType.PERSIST</literal>, it is an error.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>CascadeType.REMOVE</literal>: When deleting an entity, also delete the
+entities held in this field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>CascadeType.REFRESH</literal>: When refreshing an entity, also refresh
+the entities held in this field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<literal>CascadeType.MERGE</literal>: When merging entity state, also merge the
+entities held in this field.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+<classname>CascadeType</classname> defines one additional value, <literal>
+CascadeType.ALL</literal>, that acts as a shortcut for all of the values above.
+The following annotations are equivalent:
+ </para>
+<programlisting>
@ManyToOne(cascade={CascadeType.PERSIST,CascadeType.REMOVE,
CascadeType.REFRESH,CascadeType.MERGE})
private Company publisher;
</programlisting>
- <programlisting format="linespecific">
+<programlisting>
@ManyToOne(cascade=CascadeType.ALL)
private Company publisher;
</programlisting>
- <para>
- In XML, these enumeration constants are available as child
- elements of the <literal>cascade</literal> element. The
- <literal>cascade</literal> element is itself a child of
- <literal>many-to-one</literal>. The following examples are
- equivalent:
- </para>
- <programlisting format="linespecific">
+ <para>
+In XML, these enumeration constants are available as child elements of the
+<literal>cascade</literal> element. The <literal>cascade</literal> element is
+itself a child of <literal>many-to-one</literal>. The following examples are
+equivalent:
+ </para>
+<programlisting>
<many-to-one name="publisher">
<cascade>
<cascade-persist/>
@@ -1119,564 +1351,624 @@
</cascade>
</many-to-one>
</programlisting>
- <programlisting format="linespecific">
+<programlisting>
<many-to-one name="publisher">
<cascade>
<cascade-all/>
</cascade>
</many-to-one>
</programlisting>
- </section>
+ </section>
</section>
[... 1201 lines stripped ...]