Added:
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc.html
==============================================================================
---
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc.html
(added)
+++
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc.html
Fri Jan 6 19:19:20 2017
@@ -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 Stylesheets V1.79.1"><link rel="home" href="manual.html"
title="Apache OpenJPA 2.4 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" 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
class="toc"><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" 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" id="jpa_overview_pc_pcclass"><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" id="jpa_overview_pc_restrict"><div
class="titlepage"><div><div><h2 class="title" style="clear: both">1.
+ Restrictions on Persistent Classes
+ </h2></div></div></div><div class="toc"><dl class="toc"><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" id="jpa_overview_pc_no_arg"><div
class="titlepage"><div><div><h3 class="title">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" 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" id="jpa_overview_pc_final"><div
class="titlepage"><div><div><h3 class="title">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" 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" id="jpa_overview_pc_id"><div
class="titlepage"><div><div><h3 class="title">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" 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" id="jpa_overview_pc_version"><div
class="titlepage"><div><div><h3 class="title">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" 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" id="jpa_overview_pc_restrict_inheritance"><div
class="titlepage"><div><div><h3 class="title">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"
style="list-style-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" id="jpa_overview_pc_restrict_fields"><div
class="titlepage"><div><div><h3 class="title">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"
style="list-style-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"
style="list-style-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" 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" id="jpa_overview_pc_restrict_conclusion"><div
class="titlepage"><div><div><h3 class="title">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
Added:
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc_callbacks.html
==============================================================================
---
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc_callbacks.html
(added)
+++
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc_callbacks.html
Fri Jan 6 19:19:20 2017
@@ -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 Stylesheets V1.79.1"><link rel="home" href="manual.html"
title="Apache OpenJPA 2.4 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" id="jpa_overview_pc_callbacks"><div
class="titlepage"><div><div><h2 class="title" style="clear: both">3.
+ Lifecycle Callbacks
+ </h2></div></div></div><div class="toc"><dl class="toc"><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" id="jpa_overview_pc_callbacks_methods"><div
class="titlepage"><div><div><h3 class="title">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"
style="list-style-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" id="jpa_overview_callbacks_using"><div
class="titlepage"><div><div><h3 class="title">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" 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" id="jpa_overview_entity_listeners_using"><div
class="titlepage"><div><div><h3 class="title">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" id="jpa_overview_entity_listeners_exclude"><div
class="titlepage"><div><div><h3 class="title">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"
style="list-style-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
Added:
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc_conclusion.html
==============================================================================
---
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc_conclusion.html
(added)
+++
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc_conclusion.html
Fri Jan 6 19:19:20 2017
@@ -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 Stylesheets V1.79.1"><link rel="home" href="manual.html"
title="Apache OpenJPA 2.4 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" id="jpa_overview_pc_conclusion"><div
class="titlepage"><div><div><h2 class="title" style="clear: both">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
Added:
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc_identity.html
==============================================================================
---
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc_identity.html
(added)
+++
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/jpa_overview_pc_identity.html
Fri Jan 6 19:19:20 2017
@@ -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 Stylesheets V1.79.1"><link rel="home" href="manual.html"
title="Apache OpenJPA 2.4 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" id="jpa_overview_pc_identity"><div
class="titlepage"><div><div><h2 class="title" style="clear: both">2.
+ Entity Identity
+ </h2></div></div></div><div class="toc"><dl class="toc"><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" 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" 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" id="jpa_overview_pc_identitycls"><div
class="titlepage"><div><div><h3 class="title">2.1.
+ Identity Class
+ </h3></div></div></div><div class="toc"><dl class="toc"><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"
style="list-style-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" 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" id="jpa_overview_pc_identity_appidcode"><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" id="jpa_overview_pc_identity_hierarchy"><div
class="titlepage"><div><div><h4 class="title">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" style="cellpadding: 0;
cellspacing: 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"
style="list-style-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
