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