openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From strub...@apache.org
Subject svn commit: r953480 [14/37] - in /websites/production/openjpa/content/builds/2.4.0: ./ apache-openjpa/ apache-openjpa/docs/
Date Mon, 01 Jun 2015 20:19:02 GMT
Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_meta_xml.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc.html Mon Jun  1 20:19:00 2015
@@ -0,0 +1,450 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>Chapter&nbsp;4.&nbsp; 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.4 User's Guide"><link rel="up" href="jpa_overview.html" title="Part&nbsp;2.&nbsp;Java Persistence API"><link rel="prev" href="jpa_overview_arch.html" title="Chapter&nbsp;3.&nbsp; Java Persistence API Architecture"><link rel="next" href="jpa_overview_pc_identity.html" title="2.&nbsp; 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&nbsp;4.&nbsp;
+        Entity
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_arch.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;2.&nbsp;Java Persistence API</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="jpa_overview_pc_identity.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;4.&nbsp; Entity" id="jpa_overview_pc"><div class="titlepage"><div><div><h2 class="title">Chapter&nbsp;4.&nbsp;
+        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&nbsp;4.1.&nbsp;
+            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.&nbsp; Restrictions on Persistent Classes"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_pc_restrict">1.&nbsp;
+            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.&nbsp; Default or No-Arg Constructor"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_no_arg">1.1.&nbsp;
+                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.&nbsp; Enhancement">Section&nbsp;2, &#8220;
+            Enhancement
+        &#8221;</a>
+of the Reference Guide for details.
+                </p>
+            </div>
+        </div>
+        <div class="section" title="1.2.&nbsp; Final"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_final">1.2.&nbsp;
+                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.&nbsp; Identity Fields"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_id">1.3.&nbsp;
+                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.&nbsp; Id">Section&nbsp;2.3, &#8220;
+                Id
+            &#8221;</a> will show you how to denote your
+identity fields in JPA metadata. <a class="xref" href="jpa_overview_pc_identity.html" title="2.&nbsp; Entity Identity">Section&nbsp;2, &#8220;
+            Entity Identity
+        &#8221;</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.&nbsp; Object Identity">Section&nbsp;4, &#8220;
+            Object Identity
+        &#8221;</a> of the Reference Guide for details.
+                </p>
+            </div>
+        </div>
+        <div class="section" title="1.4.&nbsp; Version Field"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_version">1.4.&nbsp;
+                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.&nbsp; Version">Section&nbsp;2.6, &#8220;
+                Version
+            &#8221;</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.&nbsp; Additional JPA Mappings">Section&nbsp;7, &#8220;
+            Additional JPA Mappings
+        &#8221;</a> in the Reference Guide.
+                </p>
+            </div>
+        </div>
+        <div class="section" title="1.5.&nbsp; Inheritance"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_restrict_inheritance">1.5.&nbsp;
+                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.&nbsp; Entity Identity">Section&nbsp;2, &#8220;
+            Entity Identity
+        &#8221;</a>.
+                    </p>
+                </li></ul></div>
+        </div>
+        <div class="section" title="1.6.&nbsp; Persistent Fields"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_restrict_fields">1.6.&nbsp;
+                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&nbsp;5.&nbsp; Metadata">Chapter&nbsp;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.&nbsp; Conclusions"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_restrict_conclusion">1.7.&nbsp;
+                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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="jpa_overview.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="jpa_overview_pc_identity.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;3.&nbsp;
+        Java Persistence API Architecture
+    &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;2.&nbsp;
+            Entity Identity
+        </td></tr></table></div></body></html>
\ No newline at end of file

Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_callbacks.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_callbacks.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_callbacks.html Mon Jun  1 20:19:00 2015
@@ -0,0 +1,280 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>3.&nbsp; 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.4 User's Guide"><link rel="up" href="jpa_overview_pc.html" title="Chapter&nbsp;4.&nbsp; Entity"><link rel="prev" href="jpa_overview_pc_identity.html" title="2.&nbsp; Entity Identity"><link rel="next" href="jpa_overview_pc_conclusion.html" title="4.&nbsp; 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.&nbsp;
+            Lifecycle Callbacks
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_pc_identity.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;4.&nbsp;
+        Entity
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="jpa_overview_pc_conclusion.html">Next</a></td></tr></table><hr></div><div class="section" title="3.&nbsp; Lifecycle Callbacks"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_pc_callbacks">3.&nbsp;
+            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.&nbsp; Callback Methods"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_callbacks_methods">3.1.&nbsp;
+                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.&nbsp; Using Callback Methods"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_callbacks_using">3.2.&nbsp;
+                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&lt;Photo&gt; photos;
+
+    @PostLoad
+    public void convertPhotos() {
+        data = new byte[photos.size()][];
+        for (int i = 0; i &lt; 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">
+&lt;entity class="Magazine"&gt;
+    &lt;pre-remove&gt;logMagazineDeletion&lt;/pre-remove&gt;
+    &lt;post-load&gt;convertPhotos&lt;/post-load&gt;
+&lt;/entity&gt;
+</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&nbsp;5.&nbsp; Metadata">Chapter&nbsp;5, <i>
+        Metadata
+    </i></a>.
+                </p>
+            </div>
+        </div>
+        <div class="section" title="3.3.&nbsp; Using Entity Listeners"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_entity_listeners_using">3.3.&nbsp;
+                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">
+&lt;entity class="Magazine"&gt;
+    &lt;entity-listeners&gt;
+        &lt;entity-listener class="MagazineLogger"&gt;
+            &lt;post-persist&gt;logAddition&lt;/post-persist&gt;
+            &lt;pre-remove&gt;logDeletion&lt;/pre-remove&gt;
+        &lt;/entity-listener&gt;
+    &lt;/entity-listeners&gt;
+&lt;/entity&gt;
+</pre>
+        </div>
+        <div class="section" title="3.4.&nbsp; Entity Listeners Hierarchy"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_entity_listeners_exclude">3.4.&nbsp;
+                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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="jpa_overview_pc.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="jpa_overview_pc_conclusion.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.&nbsp;
+            Entity Identity
+        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;4.&nbsp;
+            Conclusions
+        </td></tr></table></div></body></html>
\ No newline at end of file

Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_callbacks.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_conclusion.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_conclusion.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_conclusion.html Mon Jun  1 20:19:00 2015
@@ -0,0 +1,21 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>4.&nbsp; 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.4 User's Guide"><link rel="up" href="jpa_overview_pc.html" title="Chapter&nbsp;4.&nbsp; Entity"><link rel="prev" href="jpa_overview_pc_callbacks.html" title="3.&nbsp; Lifecycle Callbacks"><link rel="next" href="jpa_overview_meta.html" title="Chapter&nbsp;5.&nbsp; 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.&nbsp;
+            Conclusions
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_pc_callbacks.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;4.&nbsp;
+        Entity
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="jpa_overview_meta.html">Next</a></td></tr></table><hr></div><div class="section" title="4.&nbsp; Conclusions"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_pc_conclusion">4.&nbsp;
+            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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="jpa_overview_pc.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="jpa_overview_meta.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.&nbsp;
+            Lifecycle Callbacks
+        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;5.&nbsp;
+        Metadata
+    </td></tr></table></div></body></html>
\ No newline at end of file

Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_conclusion.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_identity.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_identity.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_identity.html Mon Jun  1 20:19:00 2015
@@ -0,0 +1,296 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>2.&nbsp; 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.4 User's Guide"><link rel="up" href="jpa_overview_pc.html" title="Chapter&nbsp;4.&nbsp; Entity"><link rel="prev" href="jpa_overview_pc.html" title="Chapter&nbsp;4.&nbsp; Entity"><link rel="next" href="jpa_overview_pc_callbacks.html" title="3.&nbsp; 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.&nbsp;
+            Entity Identity
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jpa_overview_pc.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;4.&nbsp;
+        Entity
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="jpa_overview_pc_callbacks.html">Next</a></td></tr></table><hr></div><div class="section" title="2.&nbsp; Entity Identity"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="jpa_overview_pc_identity">2.&nbsp;
+            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.&nbsp; Entities as Identity Fields">Section&nbsp;4.2, &#8220;
+                Entities as Identity Fields
+            &#8221;</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.&nbsp; Persistence Context">Section&nbsp;3, &#8220;
+            Persistence Context
+        &#8221;</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.&nbsp; Identity Class"><div class="titlepage"><div><div><h3 class="title" id="jpa_overview_pc_identitycls">2.1.&nbsp;
+                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&nbsp;8.&nbsp; 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.&nbsp; Identity Hierarchies">Section&nbsp;2.1.1, &#8220;
+                    Identity Hierarchies
+                &#8221;</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.&nbsp; Application Identity Tool">Section&nbsp;4.3, &#8220;
+                Application Identity Tool
+            &#8221;</a> of the Reference Guide.
+                </p>
+            </div>
+            <div class="example"><a name="jpa_overview_pc_identity_appidcode"></a><p class="title"><b>Example&nbsp;4.2.&nbsp;
+                    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 &amp;&amp; isbn.equals(mi.isbn)))
+                &amp;&amp; (title == mi.title
+                || (title != null &amp;&amp; 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.&nbsp; Identity Hierarchies"><div class="titlepage"><div><div><h4 class="title" id="jpa_overview_pc_identity_hierarchy">2.1.1.&nbsp;
+                    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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="jpa_overview_pc.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="jpa_overview_pc_callbacks.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;4.&nbsp;
+        Entity
+    &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;3.&nbsp;
+            Lifecycle Callbacks
+        </td></tr></table></div></body></html>
\ No newline at end of file

Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/jpa_overview_pc_identity.html
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message