You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by kw...@apache.org on 2014/05/15 00:22:26 UTC
svn commit: r908837 [14/37] -
/websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_meta_xml.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc.html Wed May 14 22:22:23 2014
@@ -0,0 +1,450 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>Chapter 4. Entity</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="jpa_overview.html" title="Part 2. Java Persistence API"><link rel="prev" href="jpa_overview_arch.html" title="Chapter 3. Java Persistence API Architecture"><link rel="next" href="jpa_overview_pc_identity.html" title="2. Entity Identity"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 4.
+ Entity
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_arch.html">Prev</a> </td><th width="60%" align="center">Part 2. Java Persistence API</th><td width="20%" align="right"> <a accesskey="n" href="jpa_overview_pc_identity.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 4. Entity" id="jpa_overview_pc"><div class="titlepage"><div><div><h2 class="title">Chapter 4.
+ Entity
+ </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_restrict">1.
+ Restrictions on Persistent Classes
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_no_arg">1.1.
+ Default or No-Arg Constructor
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_final">1.2.
+ Final
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_id">1.3.
+ Identity Fields
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_version">1.4.
+ Version Field
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_restrict_inheritance">1.5.
+ Inheritance
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_restrict_fields">1.6.
+ Persistent Fields
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_restrict_conclusion">1.7.
+ Conclusions
+ </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_pc_identity.html">2.
+ Entity Identity
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_pc_identity.html#jpa_overview_pc_identitycls">2.1.
+ Identity Class
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_pc_identity.html#jpa_overview_pc_identity_hierarchy">2.1.1.
+ Identity Hierarchies
+ </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="jpa_overview_pc_callbacks.html">3.
+ Lifecycle Callbacks
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_pc_callbacks.html#jpa_overview_pc_callbacks_methods">3.1.
+ Callback Methods
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc_callbacks.html#jpa_overview_callbacks_using">3.2.
+ Using Callback Methods
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc_callbacks.html#jpa_overview_entity_listeners_using">3.3.
+ Using Entity Listeners
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc_callbacks.html#jpa_overview_entity_listeners_exclude">3.4.
+ Entity Listeners Hierarchy
+ </a></span></dt></dl></dd><dt><span class="section"><a href="jpa_overview_pc_conclusion.html">4.
+ Conclusions
+ </a></span></dt></dl></div>
+
+ <a class="indexterm" name="d5e486"></a>
+ <a class="indexterm" name="d5e488"></a>
+ <a class="indexterm" name="d5e491"></a>
+ <a class="indexterm" name="d5e495"></a>
+ <p>
+JPA recognizes two types of persistent classes: <span class="emphasis"><em>entity</em></span>
+classes and <span class="emphasis"><em>embeddable</em></span> classes. Each persistent instance of
+an entity class - each <span class="emphasis"><em>entity</em></span> - represents a unique
+datastore record. You can use the <code class="classname">EntityManager</code> to find
+an entity by its persistent identity (covered later in this chapter), or use a
+<code class="classname">Query</code> to find entities matching certain criteria.
+ </p>
+ <p>
+An instance of an embeddable class, on the other hand, is only stored as part of
+a separate entity. Embeddable instances have no persistent identity, and are
+never returned directly from the <code class="classname">EntityManager</code> or from a
+<code class="classname">Query</code> unless the query uses a projection on owning class
+to the embedded instance. For example, if <code class="classname">Address</code> is
+embedded in <code class="classname">Company</code>, then
+a query <code class="classname">"SELECT a FROM Address a"</code> will never return the
+embedded <code class="classname">Address</code> of <code class="classname">Company</code>;
+but a projection query such as
+<code class="classname">"SELECT c.address FROM Company c"</code> will.
+ </p>
+ <p>
+Despite these differences, there are few distinctions between entity classes and
+embeddable classes. In fact, writing either type of persistent class is a lot
+like writing any other class. There are no special parent classes to
+extend from, field types to use, or methods to write. This is one important way
+in which JPA makes persistence transparent to you, the developer.
+ </p>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+JPA supports both fields and JavaBean properties as persistent state. For
+simplicity, however, we will refer to all persistent state as persistent fields,
+unless we want to note a unique aspect of persistent properties.
+ </p>
+ </div>
+ <div class="example"><a name="jpa_overview_pc_pcclass"></a><p class="title"><b>Example 4.1.
+ Persistent Class
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+package org.mag;
+
+/**
+ * Example persistent class. Notice that it looks exactly like any other
+ * class. JPA makes writing persistent classes completely transparent.
+ */
+public class Magazine {
+
+ private String isbn;
+ private String title;
+ private Set articles = new HashSet();
+ private Article coverArticle;
+ private int copiesSold;
+ private double price;
+ private Company publisher;
+ private int version;
+
+ protected Magazine() {
+ }
+
+ public Magazine(String title, String isbn) {
+ this.title = title;
+ this.isbn = isbn;
+ }
+
+ public void publish(Company publisher, double price) {
+ this.publisher = publisher;
+ publisher.addMagazine(this);
+ this.price = price;
+ }
+
+ public void sell() {
+ copiesSold++;
+ publisher.addRevenue(price);
+ }
+
+ public void addArticle(Article article) {
+ articles.add(article);
+ }
+
+ // rest of methods omitted
+}
+</pre>
+ </div></div><br class="example-break">
+ <div class="section" title="1. Restrictions on Persistent Classes"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_pc_restrict">1.
+ Restrictions on Persistent Classes
+ </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_no_arg">1.1.
+ Default or No-Arg Constructor
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_final">1.2.
+ Final
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_id">1.3.
+ Identity Fields
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_version">1.4.
+ Version Field
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_restrict_inheritance">1.5.
+ Inheritance
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_restrict_fields">1.6.
+ Persistent Fields
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc.html#jpa_overview_pc_restrict_conclusion">1.7.
+ Conclusions
+ </a></span></dt></dl></div>
+
+ <a class="indexterm" name="d5e521"></a>
+ <p>
+There are very few restrictions placed on persistent classes. Still, it never
+hurts to familiarize yourself with exactly what JPA does and does not support.
+ </p>
+ <div class="section" title="1.1. Default or No-Arg Constructor"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_no_arg">1.1.
+ Default or No-Arg Constructor
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e527"></a>
+ <a class="indexterm" name="d5e530"></a>
+ <p>
+The JPA specification requires that all persistent classes have a no-arg
+constructor. This constructor may be public or protected. Because the compiler
+automatically creates a default no-arg constructor when no other constructor is
+defined, only classes that define constructors must also include a no-arg
+constructor.
+ </p>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+OpenJPA's <span class="emphasis"><em>enhancer</em></span> will automatically add a protected
+no-arg constructor to your class when required. Therefore, this restriction does
+not apply when using the enhancer. See <a class="xref" href="ref_guide_pc_enhance.html" title="2. Enhancement">Section 2, “
+ Enhancement
+ ”</a>
+of the Reference Guide for details.
+ </p>
+ </div>
+ </div>
+ <div class="section" title="1.2. Final"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_final">1.2.
+ Final
+ </h3></div></div></div>
+
+ <p>
+Entity classes may not be final. No method of an entity class can be final.
+ </p>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+OpenJPA supports final classes and final methods.
+ </p>
+ </div>
+ </div>
+ <div class="section" title="1.3. Identity Fields"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_id">1.3.
+ Identity Fields
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e545"></a>
+ <a class="indexterm" name="d5e548"></a>
+ <p>
+All entity classes must declare one or more fields which together form the
+persistent identity of an instance. These are called <span class="emphasis"><em>identity
+</em></span> or <span class="emphasis"><em>primary key</em></span> fields. In our <code class="classname">
+Magazine</code> class, <code class="literal">isbn</code> and <code class="literal">title</code>
+are identity fields, because no two magazine records in the datastore can have
+the same <code class="literal">isbn</code> and <code class="literal">title</code> values.
+<a class="xref" href="jpa_overview_meta_field.html#jpa_overview_meta_id" title="2.3. Id">Section 2.3, “
+ Id
+ ”</a> will show you how to denote your
+identity fields in JPA metadata. <a class="xref" href="jpa_overview_pc_identity.html" title="2. Entity Identity">Section 2, “
+ Entity Identity
+ ”</a>
+below examines persistent identity.
+ </p>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+OpenJPA fully supports identity fields, but does not require them. See
+<a class="xref" href="ref_guide_pc_oid.html" title="4. Object Identity">Section 4, “
+ Object Identity
+ ”</a> of the Reference Guide for details.
+ </p>
+ </div>
+ </div>
+ <div class="section" title="1.4. Version Field"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_version">1.4.
+ Version Field
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e566"></a>
+ <a class="indexterm" name="d5e569"></a>
+ <p>
+The <code class="literal">version</code> field in our <code class="classname">Magazine</code>
+class may seem out of place. JPA uses a version field in your entities to detect
+concurrent modifications to the same datastore record. When the JPA runtime
+detects an attempt to concurrently modify the same record, it throws an
+exception to the transaction attempting to commit last. This prevents
+overwriting the previous commit with stale data.
+ </p>
+ <p>
+A version field is not required, but without one concurrent threads or
+processes might succeed in making conflicting changes to the same record at the
+same time. This is unacceptable to most applications.
+<a class="xref" href="jpa_overview_meta_field.html#jpa_overview_meta_version" title="2.6. Version">Section 2.6, “
+ Version
+ ”</a> shows you how to designate a
+version field in JPA metadata.
+ </p>
+ <p>
+The version field must be an integral type (<code class="classname"> int</code>,
+<code class="classname">Long</code>, etc) or a <code class="classname">
+java.sql.Timestamp</code>. You should consider version fields immutable.
+Changing the field value has undefined results.
+ </p>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+OpenJPA fully supports version fields, but does not require them within the actual entity for concurrency
+detection. OpenJPA can maintain surrogate version values or use state
+comparisons to detect concurrent modifications. See
+<a class="xref" href="ref_guide_mapping_jpa.html" title="7. Additional JPA Mappings">Section 7, “
+ Additional JPA Mappings
+ ”</a> in the Reference Guide.
+ </p>
+ </div>
+ </div>
+ <div class="section" title="1.5. Inheritance"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_restrict_inheritance">1.5.
+ Inheritance
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e586"></a>
+ <a class="indexterm" name="d5e590"></a>
+ <p>
+JPA fully supports inheritance in persistent classes. It allows persistent
+classes to inherit from non-persistent classes, persistent classes to inherit
+from other persistent classes, and non-persistent classes to inherit from
+persistent classes. It is even possible to form inheritance hierarchies in which
+persistence skips generations. There are, however, a few important limitations:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+Persistent classes cannot inherit from certain natively-implemented system
+classes such as <code class="classname">java.net.Socket</code> and <code class="classname">
+java.lang.Thread</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+If a persistent class inherits from a non-persistent class, the fields of the
+non-persistent superclass cannot be persisted.
+ </p>
+ </li><li class="listitem">
+ <p>
+All classes in an inheritance tree must use the same identity type. We cover
+entity identity in <a class="xref" href="jpa_overview_pc_identity.html" title="2. Entity Identity">Section 2, “
+ Entity Identity
+ ”</a>.
+ </p>
+ </li></ul></div>
+ </div>
+ <div class="section" title="1.6. Persistent Fields"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_restrict_fields">1.6.
+ Persistent Fields
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e606"></a>
+ <a class="indexterm" name="d5e610"></a>
+ <a class="indexterm" name="d5e614"></a>
+ <p>
+JPA manages the state of all persistent fields. Before you access persistent
+state, the JPA runtime makes sure that it has been loaded from the datastore.
+When you set a field, the runtime records that it has changed so that the new
+value will be persisted. This allows you to treat the field in exactly the same
+way you treat any other field - another aspect of JPA's transparency.
+ </p>
+ <p>
+JPA does not support static or final fields. It does, however, include built-in
+support for most common field types. These types can be roughly divided into
+three categories: immutable types, mutable types, and relations.
+ </p>
+ <p>
+ <a class="indexterm" name="d5e620"></a>
+ <a class="indexterm" name="d5e623"></a>
+<span class="emphasis"><em>Immutable</em></span> types, once created, cannot be changed. The only
+way to alter a persistent field of an immutable type is to assign a new value to
+the field. JPA supports the following immutable types:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+All primitives (<code class="classname">int, float, byte</code>, etc)
+ </p>
+ </li><li class="listitem">
+ <p>
+All primitive wrappers (<code class="classname">java.lang.Integer, java.lang.Float,
+java.lang.Byte</code>, etc)
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">java.lang.String</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">java.math.BigInteger</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">java.math.BigDecimal</code>
+ </p>
+ </li></ul></div>
+ <p>
+JPA also supports <code class="classname">byte[]</code>, <code class="classname">Byte[]</code>,
+<code class="classname">char[]</code>, and <code class="classname">Character[]</code> as
+immutable types. That is, you can persist fields of these types,
+but you should not manipulate individual array indexes without resetting the
+array into the persistent field.
+ </p>
+ <p>
+ <a class="indexterm" name="d5e649"></a>
+ <a class="indexterm" name="d5e653"></a>
+ <a class="indexterm" name="d5e658"></a>
+ <a class="indexterm" name="d5e661"></a>
+Persistent fields of <span class="emphasis"><em>mutable</em></span> types can be altered without
+assigning the field a new value. Mutable types can be modified directly through
+their own methods. The JPA specification requires that implementations support
+the following mutable field types:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="classname">java.util.Date</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">java.util.Calendar</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">java.sql.Date</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">java.sql.Timestamp</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">java.sql.Time</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+Enums
+ </p>
+ </li><li class="listitem">
+ <p>
+Entity types (relations between entities)
+ </p>
+ </li><li class="listitem">
+ <p>
+Embeddable types
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">java.util.Collection</code>s of entities
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">java.util.Set</code>s of entities
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">java.util.List</code>s of entities
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">java.util.Map</code>s in which each entry maps the value of one
+of a related entity's fields to that entity.
+ </p>
+ </li></ul></div>
+ <p>
+Collection and map types may be parameterized.
+ </p>
+ <p>
+ <a class="indexterm" name="d5e702"></a>
+ <a class="indexterm" name="d5e705"></a>
+Most JPA implementations also have support for persisting serializable values as
+binary data in the datastore. <a class="xref" href="jpa_overview_meta.html" title="Chapter 5. Metadata">Chapter 5, <i>
+ Metadata
+ </i></a> has more
+information on persisting serializable types.
+ </p>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+OpenJPA also supports arrays, <code class="classname">java.lang.Number</code>,
+<code class="classname">java.util.Locale</code>, all JDK 1.2 <code class="classname">Set</code>,
+<code class="classname">List</code>, and <code class="classname">Map</code> types,
+and many other mutable and immutable field types. OpenJPA also allows you to
+plug in support for custom types.
+ </p>
+ </div>
+ </div>
+ <div class="section" title="1.7. Conclusions"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_restrict_conclusion">1.7.
+ Conclusions
+ </h3></div></div></div>
+
+ <p>
+This section detailed all of the restrictions JPA places on persistent classes.
+While it may seem like we presented a lot of information, you will seldom find
+yourself hindered by these restrictions in practice. Additionally, there are
+often ways of using JPA's other features to circumvent any limitations you run
+into.
+ </p>
+ </div>
+ </div>
+
+
+
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jpa_overview_arch.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jpa_overview.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jpa_overview_pc_identity.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3.
+ Java Persistence API Architecture
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2.
+ Entity Identity
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_callbacks.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_callbacks.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_callbacks.html Wed May 14 22:22:23 2014
@@ -0,0 +1,280 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>3. Lifecycle Callbacks</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="jpa_overview_pc.html" title="Chapter 4. Entity"><link rel="prev" href="jpa_overview_pc_identity.html" title="2. Entity Identity"><link rel="next" href="jpa_overview_pc_conclusion.html" title="4. Conclusions"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.
+ Lifecycle Callbacks
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_pc_identity.html">Prev</a> </td><th width="60%" align="center">Chapter 4.
+ Entity
+ </th><td width="20%" align="right"> <a accesskey="n" href="jpa_overview_pc_conclusion.html">Next</a></td></tr></table><hr></div><div class="section" title="3. Lifecycle Callbacks"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_pc_callbacks">3.
+ Lifecycle Callbacks
+ </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="jpa_overview_pc_callbacks.html#jpa_overview_pc_callbacks_methods">3.1.
+ Callback Methods
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc_callbacks.html#jpa_overview_callbacks_using">3.2.
+ Using Callback Methods
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc_callbacks.html#jpa_overview_entity_listeners_using">3.3.
+ Using Entity Listeners
+ </a></span></dt><dt><span class="section"><a href="jpa_overview_pc_callbacks.html#jpa_overview_entity_listeners_exclude">3.4.
+ Entity Listeners Hierarchy
+ </a></span></dt></dl></div>
+
+ <a class="indexterm" name="d5e874"></a>
+ <a class="indexterm" name="d5e876"></a>
+ <p>
+It is often necessary to perform various actions at different stages of a
+persistent object's lifecycle. JPA includes a variety of callbacks methods for
+monitoring changes in the lifecycle of your persistent objects. These callbacks
+can be defined on the persistent classes themselves and on non-persistent
+listener classes.
+ </p>
+ <div class="section" title="3.1. Callback Methods"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_callbacks_methods">3.1.
+ Callback Methods
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e883"></a>
+ <a class="indexterm" name="d5e886"></a>
+ <p>
+Every persistence event has a corresponding callback method marker. These
+markers are shared between persistent classes and their listeners. You can use
+these markers to designate a method for callback either by annotating that
+method or by listing the method in the XML mapping file for a given class. The
+lifecycle events and their corresponding method markers are:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e893"></a>
+<a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/PrePersist.html" target="_top">
+<code class="classname">PrePersist</code></a>: Methods marked with this annotation
+will be invoked before an object is persisted. This could be used for assigning
+primary key values to persistent objects. This is equivalent to the XML element
+tag <code class="literal">pre-persist</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e901"></a>
+<a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/PostPersist.html" target="_top">
+<code class="classname">PostPersist</code></a>: Methods marked with this annotation
+will be invoked after an object has transitioned to the persistent state. You
+might want to use such methods to update a screen after a new row is added. This
+is equivalent to the XML element tag <code class="literal">post-persist</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e909"></a>
+<a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/PostLoad.html" target="_top">
+<code class="classname">PostLoad</code></a>: Methods marked with this annotation
+will be invoked after all eagerly fetched fields of your class have been loaded
+from the datastore. No other persistent fields can be accessed in this method.
+This is equivalent to the XML element tag <code class="literal">post-load</code>.
+ </p>
+ <p>
+<code class="classname">PostLoad</code> is often used to initialize non-persistent
+fields whose values depend on the values of persistent fields, such as a complex
+data structure.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e919"></a>
+<a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/PreUpdate.html" target="_top">
+<code class="classname">PreUpdate</code></a>: Methods marked with this annotation
+will be invoked just the persistent values in your objects are flushed to the
+datastore. This is equivalent to the XML element tag <code class="literal">
+pre-update</code>.
+ </p>
+ <p>
+<code class="classname">PreUpdate</code> is the complement to <code class="classname">PostLoad
+</code>. While methods marked with <code class="classname">PostLoad</code> are most
+often used to initialize non-persistent values from persistent data, methods
+annotated with <code class="classname">PreUpdate</code> is normally used to set
+persistent fields with information cached in non-persistent data.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e932"></a>
+<a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/PostUpdate.html" target="_top">
+<code class="classname">PostUpdate</code></a>: Methods marked with this annotation
+will be invoked after changes to a given instance have been stored to the
+datastore. This is useful for clearing stale data cached at the application
+layer. This is equivalent to the XML element tag <code class="literal">post-update</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e940"></a>
+<a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/PreRemove.html" target="_top">
+<code class="classname">PreRemove</code></a>: Methods marked with this annotation
+will be invoked before an object transactions to the deleted state. Access to
+persistent fields is valid within this method. You might use this method to
+cascade the deletion to related objects based on complex criteria, or to perform
+other cleanup. This is equivalent to the XML element tag <code class="literal">
+pre-remove</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+ <a class="indexterm" name="d5e948"></a>
+<a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/PostRemove.html" target="_top">
+<code class="classname">PostRemove</code></a>: Methods marked with this annotation
+will be invoked after an object has been marked as to be deleted. This is
+equivalent to the XML element tag <code class="literal">post-remove</code>.
+ </p>
+ </li></ul></div>
+ </div>
+ <div class="section" title="3.2. Using Callback Methods"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_callbacks_using">3.2.
+ Using Callback Methods
+ </h3></div></div></div>
+
+ <p>
+When declaring callback methods on a persistent class, any method may be used
+which takes no arguments and is not shared with any property access fields.
+Multiple events can be assigned to a single method as well.
+ </p>
+ <p>
+Below is an example of how to declare callback methods on persistent classes:
+ </p>
+<pre class="programlisting">
+/**
+ * Example persistent class declaring our entity listener.
+ */
+@Entity
+public class Magazine {
+
+ @Transient
+ private byte[][] data;
+
+ @ManyToMany
+ private List<Photo> photos;
+
+ @PostLoad
+ public void convertPhotos() {
+ data = new byte[photos.size()][];
+ for (int i = 0; i < photos.size(); i++)
+ data[i] = photos.get(i).toByteArray();
+ }
+
+ @PreDelete
+ public void logMagazineDeletion() {
+ getLog().debug("deleting magazine containing" + photos.size()
+ + " photos.");
+ }
+}
+
+</pre>
+ <p>
+In an XML mapping file, we can define the same methods without annotations:
+ </p>
+<pre class="programlisting">
+<entity class="Magazine">
+ <pre-remove>logMagazineDeletion</pre-remove>
+ <post-load>convertPhotos</post-load>
+</entity>
+</pre>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+We fully explore persistence metadata annotations and XML in
+<a class="xref" href="jpa_overview_meta.html" title="Chapter 5. Metadata">Chapter 5, <i>
+ Metadata
+ </i></a>.
+ </p>
+ </div>
+ </div>
+ <div class="section" title="3.3. Using Entity Listeners"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_entity_listeners_using">3.3.
+ Using Entity Listeners
+ </h3></div></div></div>
+
+ <p>
+Mixing lifecycle event code into your persistent classes is not always ideal. It
+is often more elegant to handle cross-cutting lifecycle events in a
+non-persistent listener class. JPA allows for this, requiring only that listener
+classes have a public no-arg constructor. Like persistent classes, your listener
+classes can consume any number of callbacks. The callback methods must take in a
+single <code class="classname">java.lang.Object</code> argument which represents the
+persistent object that triggered the event.
+ </p>
+ <p>
+Entities can enumerate listeners using the <code class="classname">EntityListeners
+</code> annotation. This annotation takes an array of listener classes as
+its value.
+ </p>
+ <p>
+Below is an example of how to declare an entity and its corresponding listener
+classes.
+ </p>
+<pre class="programlisting">
+/**
+ * Example persistent class declaring our entity listener.
+ */
+@Entity
+@EntityListeners({ MagazineLogger.class, ... })
+public class Magazine {
+
+ // ... //
+}
+
+
+/**
+ * Example entity listener.
+ */
+public class MagazineLogger {
+
+ @PostPersist
+ public void logAddition(Object pc) {
+ getLog().debug("Added new magazine:" + ((Magazine) pc).getTitle());
+ }
+
+
+ @PreRemove
+ public void logDeletion(Object pc) {
+ getLog().debug("Removing from circulation:" +
+ ((Magazine) pc).getTitle());
+ }
+}
+</pre>
+ <p>
+In XML, we define both the listeners and their callback methods as so:
+ </p>
+<pre class="programlisting">
+<entity class="Magazine">
+ <entity-listeners>
+ <entity-listener class="MagazineLogger">
+ <post-persist>logAddition</post-persist>
+ <pre-remove>logDeletion</pre-remove>
+ </entity-listener>
+ </entity-listeners>
+</entity>
+</pre>
+ </div>
+ <div class="section" title="3.4. Entity Listeners Hierarchy"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_entity_listeners_exclude">3.4.
+ Entity Listeners Hierarchy
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e976"></a>
+ <p>
+Entity listener methods are invoked in a specific order when a given event is
+fired. So-called <span class="emphasis"><em>default</em></span> listeners are invoked first: these
+are listeners which have been defined in a package annotation or in the root
+element of XML mapping files. Next, entity listeners are invoked in the order of
+the inheritance hierarchy, with superclass listeners being invoked before
+subclass listeners. Finally, if an entity has multiple listeners for the same
+event, the listeners are invoked in declaration order.
+ </p>
+ <p>
+You can exclude default listeners and listeners defined in superclasses from the
+invocation chain through the use of two class-level annotations:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+<code class="classname">ExcludeDefaultListeners</code>: This annotation indicates that
+no default listeners will be invoked for this class, or any of its subclasses.
+The XML equivalent is the empty <code class="literal">exclude-default-listeners</code>
+element.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="classname">ExcludeSuperclassListeners</code>: This annotation will cause
+OpenJPA to skip invoking any listeners declared in superclasses. The XML
+equivalent is the empty <code class="literal">exclude-superclass-listeners</code> element.
+ </p>
+ </li></ul></div>
+ </div>
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jpa_overview_pc_identity.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jpa_overview_pc.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jpa_overview_pc_conclusion.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.
+ Entity Identity
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 4.
+ Conclusions
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_callbacks.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_conclusion.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_conclusion.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_conclusion.html Wed May 14 22:22:23 2014
@@ -0,0 +1,21 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>4. Conclusions</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="jpa_overview_pc.html" title="Chapter 4. Entity"><link rel="prev" href="jpa_overview_pc_callbacks.html" title="3. Lifecycle Callbacks"><link rel="next" href="jpa_overview_meta.html" title="Chapter 5. Metadata"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.
+ Conclusions
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_pc_callbacks.html">Prev</a> </td><th width="60%" align="center">Chapter 4.
+ Entity
+ </th><td width="20%" align="right"> <a accesskey="n" href="jpa_overview_meta.html">Next</a></td></tr></table><hr></div><div class="section" title="4. Conclusions"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_pc_conclusion">4.
+ Conclusions
+ </h2></div></div></div>
+
+ <p>
+This chapter covered everything you need to know to write persistent class
+definitions in JPA. JPA cannot use your persistent classes, however, until you
+complete one additional step: you must define the persistence metadata. The next
+chapter explores metadata in detail.
+ </p>
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jpa_overview_pc_callbacks.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jpa_overview_pc.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jpa_overview_meta.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.
+ Lifecycle Callbacks
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5.
+ Metadata
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_conclusion.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_identity.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_identity.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_identity.html Wed May 14 22:22:23 2014
@@ -0,0 +1,296 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>2. Entity Identity</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="jpa_overview_pc.html" title="Chapter 4. Entity"><link rel="prev" href="jpa_overview_pc.html" title="Chapter 4. Entity"><link rel="next" href="jpa_overview_pc_callbacks.html" title="3. Lifecycle Callbacks"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.
+ Entity Identity
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_pc.html">Prev</a> </td><th width="60%" align="center">Chapter 4.
+ Entity
+ </th><td width="20%" align="right"> <a accesskey="n" href="jpa_overview_pc_callbacks.html">Next</a></td></tr></table><hr></div><div class="section" title="2. Entity Identity"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_pc_identity">2.
+ Entity Identity
+ </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="jpa_overview_pc_identity.html#jpa_overview_pc_identitycls">2.1.
+ Identity Class
+ </a></span></dt><dd><dl><dt><span class="section"><a href="jpa_overview_pc_identity.html#jpa_overview_pc_identity_hierarchy">2.1.1.
+ Identity Hierarchies
+ </a></span></dt></dl></dd></dl></div>
+
+ <a class="indexterm" name="d5e722"></a>
+ <a class="indexterm" name="d5e726"></a>
+ <a class="indexterm" name="d5e729"></a>
+ <p>
+ <a class="indexterm" name="d5e733"></a>
+ <a class="indexterm" name="d5e736"></a>
+ <a class="indexterm" name="d5e739"></a>
+ <a class="indexterm" name="d5e742"></a>
+Java recognizes two forms of object identity: numeric identity and qualitative
+identity. If two references are <span class="emphasis"><em>numerically</em></span> identical, then
+they refer to the same JVM instance in memory. You can test for this using the
+<code class="literal">==</code> operator. <span class="emphasis"><em>Qualitative</em></span> identity, on
+the other hand, relies on some user-defined criteria to determine whether two
+objects are "equal". You test for qualitative identity using the <code class="methodname">
+equals</code> method. By default, this method simply relies on numeric
+identity.
+ </p>
+ <p>
+JPA introduces another form of object identity, called <span class="emphasis"><em>entity
+identity</em></span> or <span class="emphasis"><em>persistent identity</em></span>. Entity
+identity tests whether two persistent objects represent the same state in the
+datastore.
+ </p>
+ <p>
+ <a class="indexterm" name="d5e753"></a>
+ <a class="indexterm" name="d5e756"></a>
+The entity identity of each persistent instance is encapsulated in its
+<span class="emphasis"><em>identity field(s)</em></span>. If two entities of the same type have
+the same identity field values, then the two entities represent the same state
+in the datastore. Each entity's identity field values must be unique among all
+other entities of the same type.
+ </p>
+ <p>
+Identity fields must be primitives, primitive wrappers, <code class="classname">
+String</code>s, <code class="classname">Date</code>s, <code class="classname">
+Timestamp</code>s, or embeddable types.
+ </p>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+OpenJPA supports entities as identity fields, as the Reference Guide discusses
+in <a class="xref" href="ref_guide_pc_oid.html#ref_guide_pc_oid_entitypk" title="4.2. Entities as Identity Fields">Section 4.2, “
+ Entities as Identity Fields
+ ”</a>. For legacy schemas with binary
+primary key columns, OpenJPA also supports using identity fields of type
+<code class="classname">byte[]</code>. When you use a <code class="classname">byte[]</code>
+identity field, you must create an identity class. Identity classes are
+covered below.
+ </p>
+ </div>
+ <div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3>
+ <p>
+Changing the fields of an embeddable instance while it is assigned to an
+identity field has undefined results. Always treat embeddable identity instances
+as immutable objects in your applications.
+ </p>
+ </div>
+ <p>
+ <a class="indexterm" name="d5e773"></a>
+ <a class="indexterm" name="d5e776"></a>
+If you are dealing with a single persistence context (see
+<a class="xref" href="jpa_overview_emfactory_perscontext.html" title="3. Persistence Context">Section 3, “
+ Persistence Context
+ ”</a>), then you do not
+have to compare identity fields to test whether two entity references represent
+the same state in the datastore. There is a much easier way: the <code class="literal">==
+</code> operator. JPA requires that each persistence context maintain only
+one JVM object to represent each unique datastore record. Thus, entity identity
+is equivalent to numeric identity within a persistence context. This is referred
+to as the <span class="emphasis"><em>uniqueness requirement</em></span>.
+ </p>
+ <p>
+The uniqueness requirement is extremely important - without it, it would be
+impossible to maintain data integrity. Think of what could happen if two
+different objects in the same transaction were allowed to represent the same
+persistent data. If you made different modifications to each of these objects,
+which set of changes should be written to the datastore? How would your
+application logic handle seeing two different "versions" of the same data?
+Thanks to the uniqueness requirement, these questions do not have to be
+answered.
+ </p>
+ <div class="section" title="2.1. Identity Class"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_identitycls">2.1.
+ Identity Class
+ </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="jpa_overview_pc_identity.html#jpa_overview_pc_identity_hierarchy">2.1.1.
+ Identity Hierarchies
+ </a></span></dt></dl></div>
+
+ <p>
+ <a class="indexterm" name="d5e786"></a>
+ <a class="indexterm" name="d5e789"></a>
+If your entity has only one identity field, you can use the value of that field
+as the entity's identity object in all <a class="link" href="jpa_overview_em.html" title="Chapter 8. EntityManager">
+<code class="classname">EntityManager</code></a> APIs. Otherwise, you must supply an
+identity class to use for identity objects. Your identity class must meet the
+following criteria:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+The class must be public.
+ </p>
+ </li><li class="listitem">
+ <p>
+The class must be serializable.
+ </p>
+ </li><li class="listitem">
+ <p>
+The class must have a public no-args constructor.
+ </p>
+ </li><li class="listitem">
+ <p>
+The names of the non-static fields or properties of the class must be the same
+as the names of the identity fields or properties of the corresponding entity
+class, and the types must be identical.
+ </p>
+ </li><li class="listitem">
+ <p>
+The <code class="methodname">equals</code> and <code class="methodname">hashCode</code>
+methods of the class must use the values of all fields or properties
+corresponding to identity fields or properties in the entity class.
+ </p>
+ </li><li class="listitem">
+ <p>
+If the class is an inner class, it must be <code class="literal">static</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+All entity classes related by inheritance must use the same identity class, or
+else each entity class must have its own identity class whose inheritance
+hierarchy mirrors the inheritance hierarchy of the owning entity classes (see
+<a class="xref" href="jpa_overview_pc_identity.html#jpa_overview_pc_identity_hierarchy" title="2.1.1. Identity Hierarchies">Section 2.1.1, “
+ Identity Hierarchies
+ ”</a>).
+ </p>
+ </li></ul></div>
+ <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+ <p>
+Though you may still create identity classes by hand, OpenJPA provides the
+<code class="classname">appidtool</code> to automatically generate proper identity
+classes based on your identity fields. See
+<a class="xref" href="ref_guide_pc_oid.html#ref_guide_pc_oid_application" title="4.3. Application Identity Tool">Section 4.3, “
+ Application Identity Tool
+ ”</a> of the Reference Guide.
+ </p>
+ </div>
+ <div class="example"><a name="jpa_overview_pc_identity_appidcode"></a><p class="title"><b>Example 4.2.
+ Identity Class
+ </b></p><div class="example-contents">
+
+ <p>
+This example illustrates a proper identity class for an entity with multiple
+identity fields.
+ </p>
+<pre class="programlisting">
+/**
+ * Persistent class using application identity.
+ */
+public class Magazine {
+
+ private String isbn; // identity field
+ private String title; // identity field
+
+ // rest of fields and methods omitted
+
+
+ /**
+ * Application identity class for Magazine.
+ */
+ public static class MagazineId {
+
+ // each identity field in the Magazine class must have a
+ // corresponding field in the identity class
+ public String isbn;
+ public String title;
+
+ /**
+ * Equality must be implemented in terms of identity field
+ * equality, and must use instanceof rather than comparing
+ * classes directly (some JPA implementations may subclass the
+ * identity class).
+ */
+ public boolean equals(Object other) {
+ if (other == this)
+ return true;
+ if (!(other instanceof MagazineId))
+ return false;
+
+ MagazineId mi = (MagazineId) other;
+ return (isbn == mi.isbn
+ || (isbn != null && isbn.equals(mi.isbn)))
+ && (title == mi.title
+ || (title != null && title.equals(mi.title)));
+ }
+
+ /**
+ * Hashcode must also depend on identity values.
+ */
+ public int hashCode() {
+ return ((isbn == null) ? 0 : isbn.hashCode())
+ ^ ((title == null) ? 0 : title.hashCode());
+ }
+
+ public String toString() {
+ return isbn + ":" + title;
+ }
+ }
+}
+</pre>
+ </div></div><br class="example-break">
+ <div class="section" title="2.1.1. Identity Hierarchies"><div class="titlepage"><div><div><h4 class="title" id="jpa_overview_pc_identity_hierarchy">2.1.1.
+ Identity Hierarchies
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e823"></a>
+ <div class="mediaobject"><table border="0" summary="manufactured viewport for HTML img" cellspacing="0" cellpadding="0" width="213"><tr><td><img src="img/appid-hierarchy.png"></td></tr></table></div>
+ <p>
+An alternative to having a single identity class for an entire inheritance
+hierarchy is to have one identity class per level in the inheritance hierarchy.
+The requirements for using a hierarchy of identity classes are as follows:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+ <p>
+The inheritance hierarchy of identity classes must exactly mirror the hierarchy
+of the persistent classes that they identify. In the example pictured above,
+abstract class <code class="classname">Person</code> is extended by abstract class
+<code class="classname">Employee</code>, which is extended by non-abstract class
+<code class="classname"> FullTimeEmployee</code>, which is extended by non-abstract
+class <code class="classname">Manager</code>. The corresponding identity classes, then,
+are an abstract <code class="classname">PersonId</code> class, extended by an abstract
+<code class="classname">EmployeeId</code> class, extended by a non-abstract <code class="classname">
+FullTimeEmployeeId</code> class, extended by a non-abstract <code class="classname">
+ManagerId</code> class.
+ </p>
+ </li><li class="listitem">
+ <p>
+Subclasses in the identity hierarchy may define additional identity fields until
+the hierarchy becomes non-abstract. In the aforementioned example, <code class="classname">
+Person</code> defines an identity field <code class="literal">ssn</code>, <code class="classname">
+Employee</code> defines additional identity field <code class="literal">userName
+</code>, and <code class="classname">FullTimeEmployee</code> adds a final identity
+field, <code class="literal">empId</code>. However, <code class="classname">Manager</code> may not
+define any additional identity fields, since it is a subclass of a non-abstract
+class. The hierarchy of identity classes, of course, must match the identity
+field definitions of the persistent class hierarchy.
+ </p>
+ </li><li class="listitem">
+ <p>
+It is not necessary for each abstract class to declare identity fields. In the
+previous example, the abstract <code class="classname">Person</code> and <code class="classname">
+Employee</code> classes could declare no identity fields, and the first
+concrete subclass <code class="classname">FullTimeEmployee</code> could define one or
+more identity fields.
+ </p>
+ </li><li class="listitem">
+ <p>
+All subclasses of a concrete identity class must be <code class="methodname">equals
+</code> and <code class="methodname">hashCode</code>-compatible with the
+concrete superclass. This means that in our example, a <code class="classname">ManagerId
+</code> instance and a <code class="classname">FullTimeEmployeeId</code> instance
+with the same identity field values should have the same hash code, and should
+compare equal to each other using the <code class="methodname">equals</code> method of
+either one. In practice, this requirement reduces to the following coding
+practices:
+ </p>
+ <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
+ <p>
+Use <code class="literal">instanceof</code> instead of comparing <code class="classname">Class
+</code> objects in the <code class="methodname">equals</code> methods of your
+identity classes.
+ </p>
+ </li><li class="listitem">
+ <p>
+An identity class that extends another non-abstract identity class should not
+override <code class="methodname">equals</code> or <code class="methodname">hashCode</code>.
+ </p>
+ </li></ol></div>
+ </li></ul></div>
+ </div>
+ </div>
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jpa_overview_pc.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="jpa_overview_pc.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="jpa_overview_pc_callbacks.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4.
+ Entity
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 3.
+ Lifecycle Callbacks
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/jpa_overview_pc_identity.html
------------------------------------------------------------------------------
svn:mime-type = text/plain