openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From strub...@apache.org
Subject svn commit: r953480 [35/37] - in /websites/production/openjpa/content/builds/2.4.0: ./ apache-openjpa/ apache-openjpa/docs/
Date Mon, 01 Jun 2015 20:19:02 GMT
Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_pc_scos.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_pc_scos.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_pc_scos.html Mon Jun  1 20:19:00 2015
@@ -0,0 +1,724 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>6.&nbsp; Persistent Fields</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="ref_guide_pc.html" title="Chapter&nbsp;5.&nbsp; Persistent Classes"><link rel="prev" href="ref_guide_inverses.html" title="5.&nbsp; Managed Inverses"><link rel="next" href="ref_guide_fetch.html" title="7.&nbsp; Fetch Groups"></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">6.&nbsp;
+            Persistent Fields
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_inverses.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;
+        Persistent Classes
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_fetch.html">Next</a></td></tr></table><hr></div><div class="section" title="6.&nbsp; Persistent Fields"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_pc_scos">6.&nbsp;
+            Persistent Fields
+        </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_scos_restore">6.1. 
+                Restoring State
+            </a></span></dt><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_scos_order">6.2. 
+                Typing and Ordering
+            </a></span></dt><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_calendar_timezone">6.3. 
+                Calendar Fields and TimeZones
+            </a></span></dt><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy">6.4. 
+                Proxies
+            </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_smart">6.4.1. 
+                    Smart Proxies
+                </a></span></dt><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_lrs">6.4.2. 
+                    Large Result Set Proxies
+                </a></span></dt><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_custom">6.4.3. 
+                    Custom Proxies
+                </a></span></dt><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_serial">6.4.4. 
+                    Serialization
+                </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_extern">6.5. 
+                Externalization
+            </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_extern_values">6.5.1. 
+                    External Values
+                </a></span></dt></dl></dd></dl></div>
+        
+        <a class="indexterm" name="d5e12460"></a>
+        <p>
+OpenJPA enhances the specification's support for persistent fields in many ways.
+This section documents aspects of OpenJPA's persistent field handling that may
+affect the way you design your persistent classes.
+        </p>
+        <div class="section" title="6.1.&nbsp; Restoring State"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_scos_restore">6.1.&nbsp;
+                Restoring State
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12465"></a>
+            <a class="indexterm" name="d5e12468"></a>
+            <p>
+While the JPA specification says that you should not use rolled back objects,
+such objects are perfectly valid in OpenJPA. You can control whether the
+objects' managed state is rolled back to its pre-transaction values with the
+<a class="link" href="ref_guide_conf_openjpa.html#openjpa.RestoreState" title="5.62.&nbsp; openjpa.RestoreState"><code class="literal">openjpa.RestoreState</code>
+</a> configuration property. <code class="literal">none</code> does not roll back state
+(the object becomes hollow, and will re-load its state the next time it is
+accessed), <code class="literal">immutable</code> restores immutable values (primitives,
+primitive wrappers, strings) and clears mutable values so that they are reloaded
+on next access, and <code class="literal">all</code> restores all managed values to their
+pre-transaction state.
+            </p>
+        </div>
+        <div class="section" title="6.2.&nbsp; Typing and Ordering"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_scos_order">6.2.&nbsp;
+                Typing and Ordering
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12478"></a>
+            <p>
+When loading data into a field, OpenJPA examines the value you assign the field
+in your declaration code or in your no-args constructor. If the field value's
+type is more specific than the field's declared type, OpenJPA uses the value
+type to hold the loaded data. OpenJPA also uses the comparator you've
+initialized the field with, if any. Therefore, you can use custom comparators on
+your persistent field simply by setting up the comparator and using it in your
+field's initial value.
+            </p>
+            <div class="example"><a name="ref_guide_pc_scos_order_initialvals"></a><p class="title"><b>Example&nbsp;5.12.&nbsp;
+                    Using Initial Field Values
+                </b></p><div class="example-contents">
+                
+                <p>
+Though the annotations are left out for simplicity, assume <code class="literal">
+employeesBySal</code> and <code class="literal">departments</code> are persistent
+fields in the class below.
+                </p>
+<pre class="programlisting">
+public class Company {
+
+    // OpenJPA will detect the custom comparator in the initial field value
+    // and use it whenever loading data from the database into this field
+    private Collection employeesBySal = new TreeSet(new SalaryComparator());
+    private Map departments;
+
+    public Company {
+        // or we can initialize fields in our no-args constructor; even though
+        // this field is declared type Map, OpenJPA will detect that it's 
+        // actually a TreeMap and use natural ordering for loaded data
+        departments = new TreeMap();
+    }
+
+    // rest of class definition...
+}
+</pre>
+            </div></div><br class="example-break">
+        </div>
+        <div class="section" title="6.3.&nbsp; Calendar Fields and TimeZones"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_calendar_timezone">6.3.&nbsp;
+                Calendar Fields and TimeZones
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12490"></a>
+            <p>
+OpenJPA's support for the <code class="classname">java.util.Calendar</code> type will
+store only the <code class="classname">Date</code> part of the field, not the
+<code class="classname">TimeZone</code> associated with the field. When loading the date
+into the <code class="classname">Calendar</code> field, OpenJPA will use the <code class="classname">
+TimeZone</code> that was used to initialize the field.
+            </p>
+        </div>
+        <div class="section" title="6.4.&nbsp; Proxies"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_scos_proxy">6.4.&nbsp;
+                Proxies
+            </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_smart">6.4.1. 
+                    Smart Proxies
+                </a></span></dt><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_lrs">6.4.2. 
+                    Large Result Set Proxies
+                </a></span></dt><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_custom">6.4.3. 
+                    Custom Proxies
+                </a></span></dt><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_serial">6.4.4. 
+                    Serialization
+                </a></span></dt></dl></div>
+            
+            <a class="indexterm" name="d5e12501"></a>
+            <a class="indexterm" name="d5e12503"></a>
+            <p>
+At runtime, the values of all mutable second class object fields in persistent
+and transactional objects are replaced with implementation-specific proxies. On
+modification, these proxies notify their owning instance that they have been
+changed, so that the appropriate updates can be made on the datastore.
+            </p>
+            <div class="section" title="6.4.1.&nbsp; Smart Proxies"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_pc_scos_proxy_smart">6.4.1.&nbsp;
+                    Smart Proxies
+                </h4></div></div></div>
+                
+                <a class="indexterm" name="d5e12510"></a>
+                <p>
+Most proxies only track whether or not they have been modified. Smart proxies
+for collection and map fields, however, keep a record of which elements have
+been added, removed, and changed. This record enables the OpenJPA runtime to
+make more efficient database updates on these fields.
+                </p>
+                <p>
+When designing your persistent classes, keep in mind that you can optimize for
+OpenJPA smart proxies by using fields of type <code class="classname">java.util.Set
+</code>, <code class="classname">java.util.TreeSet</code>, and <code class="classname">
+java.util.HashSet</code> for your collections whenever possible. Smart
+proxies for these types are more efficient than proxies for <code class="classname">
+List</code>s. You can also design your own smart proxies to further 
+optimize OpenJPA for your usage patterns. See the section on
+<a class="link" href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_custom" title="6.4.3.&nbsp; Custom Proxies">custom proxies</a> for
+details.
+                </p>
+            </div>
+            <div class="section" title="6.4.2.&nbsp; Large Result Set Proxies"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_pc_scos_proxy_lrs">6.4.2.&nbsp;
+                    Large Result Set Proxies
+                </h4></div></div></div>
+                
+                <a class="indexterm" name="d5e12522"></a>
+                <a class="indexterm" name="d5e12525"></a>
+                <p>
+Under standard ORM behavior, traversing a persistent collection or map field
+brings the entire contents of that field into memory. Some persistent fields,
+however, might represent huge amounts of data, to the point that attempting to
+fully instantiate them can overwhelm the JVM or seriously degrade performance.
+                </p>
+                <p>
+OpenJPA uses special proxy types to represent these "large result set" fields.
+OpenJPA's large result set proxies do not cache any data in memory. Instead,
+each operation on the proxy offloads the work to the database and returns the
+proper result. For example, the <code class="methodname">contains</code> method of a
+large result set collection will perform a <code class="literal"> SELECT COUNT(*)</code>
+query with the proper <code class="literal">WHERE</code> conditions to find out if the
+given element exists in the database's record of the collection. Similarly, each
+time you obtain an iterator OpenJPA performs the proper query using the current
+<a class="link" href="ref_guide_dbsetup_lrs.html" title="10.&nbsp; Large Result Sets">large result set settings</a>, as
+discussed in the <a class="link" href="ref_guide_dbsetup.html" title="Chapter&nbsp;4.&nbsp; JDBC">JDBC</a> chapter. As you
+invoke <code class="methodname">Iterator.next</code>, OpenJPA instantiates the result
+objects on-demand.
+                </p>
+                <p>
+You can free the resources used by a large result set iterator by passing it to
+the static <a class="link" href="ref_guide_runtime_jpa.html#ref_guide_runtime_openjpapersistence" title="2.9.&nbsp; OpenJPAPersistence"><code class="methodname">
+OpenJPAPersistence.close</code></a> method.
+                </p>
+                <div class="example"><a name="ref_guide_pc_scos_proxy_lrs_itr"></a><p class="title"><b>Example&nbsp;5.13.&nbsp;
+                        Using a Large Result Set Iterator
+                    </b></p><div class="example-contents">
+                    
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+...
+
+Collection employees = company.getEmployees(); // employees is a lrs collection
+Iterator itr = employees.iterator();
+while (itr.hasNext())
+    process((Employee) itr.next());
+OpenJPAPersistence.close(itr);
+</pre>
+                </div></div><br class="example-break">
+                <p>
+You can also add and remove from large result set proxies, just as with standard
+fields. OpenJPA keeps a record of all changes to the elements of the proxy,
+which it uses to make sure the proper results are always returned from
+collection and map methods, and to update the field's database record on commit.
+                </p>
+                <p>
+In order to use large result set proxies in JPA, add the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/LRS.html" target="_top"><code class="classname">
+org.apache.openjpa.persistence.LRS</code></a> annotation to the
+persistent field.
+                </p>
+                <p>
+The following restrictions apply to large result set fields:
+                </p>
+                <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                        <p>
+The field must be declared as either a <code class="classname">java.util.Collection
+</code> or <code class="classname">java.util.Map</code>. It cannot be declared as
+any other type, including any sub-interface of collection or map, or any
+concrete collection or map class.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+The field cannot have an externalizer (see 
+<a class="xref" href="ref_guide_pc_scos.html#ref_guide_pc_extern" title="6.5.&nbsp; Externalization">Section&nbsp;6.5, &#8220;
+                Externalization
+            &#8221;</a>).
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+Because they rely on their owning object for context, large result set proxies
+cannot be transferred from one persistent field to another. The following code
+would result in an error on commit:
+                        </p>
+<pre class="programlisting">
+Collection employees = company.getEmployees()  // employees is a lrs collection
+company.setEmployees(null);
+anotherCompany.setEmployees(employees);
+</pre>
+                    </li></ul></div>
+                <div class="example"><a name="ref_guide_pc_scos_proxy_lrs_extension"></a><p class="title"><b>Example&nbsp;5.14.&nbsp;
+                        Marking a Large Result Set Field
+                    </b></p><div class="example-contents">
+                    
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+public class Company {
+
+    @ManyToMany
+    @LRS private Collection&lt;Employee&gt; employees;
+
+    ...
+}
+</pre>
+                </div></div><br class="example-break">
+            </div>
+            <div class="section" title="6.4.3.&nbsp; Custom Proxies"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_pc_scos_proxy_custom">6.4.3.&nbsp;
+                    Custom Proxies
+                </h4></div></div></div>
+                
+                <a class="indexterm" name="d5e12563"></a>
+                <a class="indexterm" name="d5e12566"></a>
+                <p>
+OpenJPA manages proxies through the
+<a class="ulink" href="../javadoc/org/apache/openjpa/util/ProxyManager.html" target="_top"><code class="classname">
+org.apache.openjpa.util.ProxyManager</code></a> interface. OpenJPA
+includes a default proxy manager, the <code class="classname">
+org.apache.openjpa.util.ProxyManagerImpl</code> (with a plugin alias name
+of <code class="literal">default</code>), that will meet the needs of most users. The
+default proxy manager understands the following configuration properties:
+                </p>
+                <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                        <p>
+<code class="literal">TrackChanges</code>: Whether to use
+<a class="link" href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_smart" title="6.4.1.&nbsp; Smart Proxies">smart proxies</a>. Defaults to
+<code class="literal">true</code>.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">AssertAllowedType</code>: Whether to immediately throw an exception
+if you attempt to add an element to a collection or map that is not assignable
+to the element type declared in metadata.  Defaults to <code class="literal">false</code>.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">DelayCollectionLoading</code>: Whether to delay loading elements of a
+lazily loaded collection.  Delay loading allows non-indexed add and remove
+operations to occur without prior loading of the collection from the data store.  This can
+improve performance of some applications by allowing them to perform simple add or remove
+operations on collections without requiring them to be loaded. Delayed proxies are
+loaded when an operation is performed that requires loading, such
+as iteration, size, serialization, and indexOf.  They can also be loaded by casting the
+proxy to a <a class="ulink" href="../javadoc/org/apache/openjpa/util/DelayedProxy.html" target="_top"><code class="classname">
+org.apache.openjpa.util.DelayedProxy</code></a> and invoking the
+<code class="methodname">load</code> method. If a broker factory is available after detaching the owning
+entity, a collection may be available for delayed loading after the persistence context has been
+cleared. In post-detachment, entities that are loaded are not associated with a persistence context.
+Defaults to <code class="literal">false</code>.
+                        </p>
+                    </li></ul></div>
+                <p>
+The default proxy manager can proxy the standard methods of any 
+<code class="classname">Collection</code>, <code class="classname">List</code>, 
+<code class="classname">Map</code>, <code class="classname">Queue</code>, 
+<code class="classname">Date</code>, or <code class="classname">Calendar</code> class, 
+including custom implementations.  It can also proxy custom classes whose 
+accessor and mutator methods follow JavaBean naming conventions.  Your custom
+types must, however, meet the following criteria:
+                </p>
+                <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                        <p>
+Custom container types must have a public no-arg constructor or a public
+constructor that takes a single <code class="classname">Comparator</code> parameter.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+Custom date types must have a public no-arg constructor or a public
+constructor that takes a single <code class="classname">long</code> parameter 
+representing the current time.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+Other custom types must have a public no-arg constructor or a public copy
+constructor.  If a custom types does not have a copy constructor, it must be 
+possible to fully copy an instance A by creating a new instance B and calling 
+each of B's setters with the value from the corresponding getter on A.
+                        </p>
+                    </li></ul></div>
+                <p>
+If you have custom classes that must be proxied and do not meet these 
+requirements, OpenJPA allows you to define your own proxy classes and
+your own proxy manager. See the <code class="literal">openjpa.util</code> package
+<a class="ulink" href="../javadoc/" target="_top">Javadoc</a> for details on the interfaces involved,
+and the utility classes OpenJPA provides to assist you.
+                </p>
+                <p>
+You can plug your custom proxy manager into the OpenJPA runtime through the
+<a class="link" href="ref_guide_conf_openjpa.html#openjpa.ProxyManager" title="5.56.&nbsp; openjpa.ProxyManager"><code class="literal"> openjpa.ProxyManager</code>
+</a> configuration property.
+                </p>
+                <div class="example"><a name="ref_guide_pc_scos_proxy_custom_ex"></a><p class="title"><b>Example&nbsp;5.15.&nbsp;
+                        Configuring the Proxy Manager
+                    </b></p><div class="example-contents">
+                    
+<pre class="programlisting">
+&lt;property name="openjpa.ProxyManager" value="TrackChanges=false"/&gt;
+</pre>
+                </div></div><br class="example-break">
+            </div>
+            <div class="section" title="6.4.4.&nbsp; Serialization"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_pc_scos_proxy_serial">6.4.4.&nbsp;
+                    Serialization
+                </h4></div></div></div>
+                
+                <a class="indexterm" name="d5e12618"></a>
+                <a class="indexterm" name="d5e12621"></a>
+                <p>
+When objects are serialized, the <code class="literal">DetachedStateField</code> in
+section <a class="xref" href="ref_guide_remote.html#ref_guide_detach_state" title="1.3.1.&nbsp; Detached State">Section&nbsp;1.3.1, &#8220;
+                    Detached State
+                &#8221;</a> 
+will be used to help determine when build time proxies will be removed.  
+If runtime created proxies are being used (proxies not supplied by OpenJPA)
+or if an entity has already been detached, then any found proxies will be
+removed during serialization.
+                </p>
+                <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                        <p>
+<code class="literal">transient</code>: Use a transient detached state field. This gives
+the benefits of a detached state field to local objects that are never
+serialized, but retains serialization compatibility for client tiers without
+access to the enhanced versions of your classes or the OpenJPA runtime.
+All proxies will be removed during serialization.  This is the default.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">true</code>: Use a non-transient detached state field so that
+objects crossing serialization barriers can still be attached efficiently. This
+requires, however, that your client tier have the enhanced versions of your
+classes and the OpenJPA runtime.
+No OpenJPA provided proxies will be removed during serialization.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">false</code>: Do not use a detached state field.
+All proxies will be removed during serialization.
+                        </p>
+                    </li></ul></div>
+            </div>
+        </div>
+        <div class="section" title="6.5.&nbsp; Externalization"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_extern">6.5.&nbsp;
+                Externalization
+            </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_pc_scos.html#ref_guide_pc_extern_values">6.5.1. 
+                    External Values
+                </a></span></dt></dl></div>
+            
+            <a class="indexterm" name="d5e12639"></a>
+            <a class="indexterm" name="d5e12641"></a>
+            <p>
+OpenJPA offers the ability to write
+<a class="link" href="ref_guide_mapping_custom.html#ref_guide_mapping_custom_field" title="10.3.&nbsp; Custom Field Mapping">custom field mappings</a> in
+order to have complete control over the mechanism with which fields are stored,
+queried, and loaded from the datastore. Often, however, a custom mapping is
+overkill. There is often a simple transformation from a Java field value to its
+database representation. Thus, OpenJPA provides the externalization service.
+Externalization allows you to specify methods that will externalize a field
+value to its database equivalent on store and then rebuild the value from its
+externalized form on load.
+            </p>
+            <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+                <p>
+Fields of embeddable classes used for <code class="literal">@EmbeddedId</code> values in
+JPA cannot have externalizers.
+                </p>
+            </div>
+            <p>
+The OpenJPA
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/Externalizer.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.Externalizer</code></a>
+annotation sets the name of a method that will be invoked to convert
+the field into its external form for database storage. You can specify either
+the name of a non-static method, which will be invoked on the field value, or a
+static method, which will be invoked with the field value as a parameter. Each
+method can also take an optional
+<a class="ulink" href="../javadoc/org/apache/openjpa/kernel/StoreContext.html" target="_top"><code class="classname">
+StoreContext</code></a> parameter for access to a persistence context.
+The return value of the method is the field's external form. By default, OpenJPA
+assumes that all named methods belong to the field value's class (or its
+superclasses). You can, however, specify static methods of other classes using
+the format <code class="literal">&lt;class-name&gt;.&lt;method-name&gt;</code>.
+            </p>
+            <p>
+Given a field of type <code class="classname">CustomType</code> that externalizes to a
+string, the table below demonstrates several possible externalizer methods and
+their corresponding metadata extensions.
+            </p>
+            <div class="table"><a name="d5e12658"></a><p class="title"><b>Table&nbsp;5.1.&nbsp;
+                    Externalizer Options
+                </b></p><div class="table-contents">
+                
+                <table summary="&#xA;                    Externalizer Options&#xA;                " border="1"><colgroup><col align="left" class="method"><col align="left" class="extension"></colgroup><thead><tr><th align="left">
+Method
+                            </th><th align="left">
+Extension
+                            </th></tr></thead><tbody><tr><td align="left">
+                                <code class="literal">
+public String CustomType.toString()
+                                </code>
+                            </td><td align="left">
+                                <code class="literal">
+@Externalizer("toString")
+                                </code>
+                            </td></tr><tr><td align="left">
+                                <code class="literal">
+public String CustomType.toString(StoreContext ctx)
+                                </code>
+                            </td><td align="left">
+                                <code class="literal">
+@Externalizer("toString")
+                                </code>
+                            </td></tr><tr><td align="left">
+                                <code class="literal">
+public static String AnyClass.toString(CustomType ct)
+                                </code>
+                            </td><td align="left">
+                                <code class="literal">
+@Externalizer("AnyClass.toString")
+                                </code>
+                            </td></tr><tr><td align="left">
+                                <code class="literal">
+public static String AnyClass.toString(CustomType ct, StoreContext ctx)
+                                </code>
+                            </td><td align="left">
+                                <code class="literal">
+@Externalizer("AnyClass.toString")
+                                </code>
+                            </td></tr></tbody></table>
+            </div></div><br class="table-break">
+            <p>
+The OpenJPA
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/Factory.html" target="_top"><code class="classname">
+org.apache.openjpa.persistence.Factory</code></a> annotation
+contains the name of a method that will be invoked to instantiate the field from
+the external form stored in the database. Specify a static method name. The
+method will be invoked with the externalized value and must return an
+instance of the field type. The method can also take an optional
+<a class="ulink" href="../javadoc/org/apache/openjpa/kernel/StoreContext.html" target="_top"><code class="classname">
+StoreContext</code></a> parameter for access to a persistence context.
+If a factory is not specified, OpenJPA will use the constructor of the field
+type that takes a single argument of the external type, or will throw an
+exception if no constructor with that signature exists.
+            </p>
+            <p>
+Given a field of type <code class="classname">CustomType</code> that externalizes to a
+string, the table below demonstrates several possible factory methods and their
+corresponding metadata extensions.
+            </p>
+            <div class="table"><a name="d5e12695"></a><p class="title"><b>Table&nbsp;5.2.&nbsp;
+                    Factory Options
+                </b></p><div class="table-contents">
+                
+                <table summary="&#xA;                    Factory Options&#xA;                " border="1"><colgroup><col align="left" class="method"><col align="left" class="extension"></colgroup><thead><tr><th align="left">
+Method
+                            </th><th align="left">
+Extension
+                            </th></tr></thead><tbody><tr><td align="left">
+                                <code class="literal">
+public CustomType(String str)
+                                </code>
+                            </td><td align="left">
+none
+                            </td></tr><tr><td align="left">
+                                <code class="literal">
+public static CustomType CustomType.fromString(String str)
+                                </code>
+                            </td><td align="left">
+                                <code class="literal">
+@Factory("fromString")
+                                </code>
+                            </td></tr><tr><td align="left">
+                                <code class="literal">
+public static CustomType CustomType.fromString(String str, StoreContext ctx)
+                                </code>
+                            </td><td align="left">
+                                <code class="literal">
+@Factory("fromString")
+                                </code>
+                            </td></tr><tr><td align="left">
+                                <code class="literal">
+public static CustomType AnyClass.fromString(String str)
+                                </code>
+                            </td><td align="left">
+                                <code class="literal">
+@Factory("AnyClass.fromString")
+                                </code>
+                            </td></tr><tr><td align="left">
+                                <code class="literal">
+public static CustomType AnyClass.fromString(String str, StoreContext ctx)
+                                </code>
+                            </td><td align="left">
+                                <code class="literal">
+@Factory("AnyClass.fromString")
+                                </code>
+                            </td></tr></tbody></table>
+            </div></div><br class="table-break">
+            <p>
+If your externalized field is not a standard persistent type, you must
+explicitly mark it persistent. In OpenJPA, you can force a persistent field
+by annotating it with <a class="link" href="ref_guide_meta_jpa.html#ref_guide_meta_jpa_persistent" title="3.3.&nbsp; Persistent Field Values"><code class="classname">
+org.apache.openjpa.persistence.Persistent</code></a> annotation.
+            </p>
+            <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+                <p>
+If your custom field type is mutable and is not a standard collection, map, or
+date class, OpenJPA will not be able to detect changes to the field. You must
+mark the field dirty manually, or create a custom field proxy.
+See
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top">
+<code class="methodname">OpenJPAEntityManager.dirty</code></a> for how to mark a
+field dirty manually in JPA.
+See <a class="xref" href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy" title="6.4.&nbsp; Proxies">Section&nbsp;6.4, &#8220;
+                Proxies
+            &#8221;</a> for a discussion of proxies.
+                </p>
+            </div>
+            <p>
+You can externalize a field to virtually any value that is supported by
+OpenJPA's field mappings (embedded relations are the exception; you must declare
+your field to be a persistence-capable type in order to embed it). This means
+that a field can externalize to something as simple as a primitive, something as
+complex as a collection or map of entities, or anything in
+between. If you do choose to externalize to a collection or map, OpenJPA
+recognizes a family of metadata extensions for specifying type information for the
+externalized form of your fields - see <a class="xref" href="ref_guide_meta_ext.html#type" title="4.2.6.&nbsp; Type">Section&nbsp;4.2.6, &#8220;
+                    Type
+                &#8221;</a>. If the
+external form of your field is an entity object or contains entities, OpenJPA 
+will correctly include the objects in its persistence-by-reachability 
+algorithms and its delete-dependent algorithms.
+            </p>
+            <p>
+The example below demonstrates a few forms of externalization.
+            </p>
+            <div class="example"><a name="ref_guide_pc_externex"></a><p class="title"><b>Example&nbsp;5.16.&nbsp;
+                    Using Externalization
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+public class Magazine {
+
+    // use Class.getName and Class.forName to go to/from strings
+    @Persistent
+    @Externalizer("getName")
+    @Factory("forName")
+    private Class cls;
+
+    // use URL.getExternalForm for externalization. no factory;
+    // we can rely on the URL string constructor
+    @Persistent
+    @Externalizer("toExternalForm")
+    private URL url;
+
+    // use our custom methods
+    @Persistent
+    @Externalizer("Magazine.authorsFromCustomType")
+    @Factory("Magazine.authorsToCustomType")
+    @ElementType(Author.class)
+    private CustomType customType;
+
+    public static Collection authorsFromCustomType(CustomType customType) {
+        ... logic to pack custom type into a list of authors ...
+    }
+
+    public static CustomType authorsToCustomType(Collection authors) {
+        ... logic to create custom type from a collection of authors ...
+    }
+
+    ...
+}
+</pre>
+            </div></div><br class="example-break">
+            <p>
+            <a class="indexterm" name="d5e12744"></a>
+You can query externalized fields using parameters. Pass in a value of the field
+type when executing the query. OpenJPA will externalize the parameter using the
+externalizer method named in your metadata, and compare the externalized
+parameter with the value stored in the database. As a shortcut, OpenJPA also
+allows you to use parameters or literals of the field's externalized type in
+queries, as demonstrated in the example below.
+            </p>
+            <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+                <p>
+Currently, queries are limited to fields that externalize to a primitive,
+primitive wrapper, string, or date types, due to constraints on query syntax.
+                </p>
+            </div>
+            <div class="example"><a name="ref_guide_pc_extern_queryex"></a><p class="title"><b>Example&nbsp;5.17.&nbsp;
+                    Querying Externalization Fields
+                </b></p><div class="example-contents">
+                
+                <p>
+Assume the <code class="classname">Magazine</code> class has the same fields as in the
+previous example.
+                </p>
+<pre class="programlisting">
+// you can query using parameters
+Query q = em.createQuery("select m from Magazine m where m.url = :u");
+q.setParameter("u", new URL("http://www.solarmetric.com"));
+List results = q.getResultList();
+
+// or as a shortcut, you can use the externalized form directly
+q = em.createQuery("select m from Magazine m where m.url = 'http://www.solarmetric.com'");
+results = q.getResultList();
+</pre>
+            </div></div><br class="example-break">
+            <div class="section" title="6.5.1.&nbsp; External Values"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_pc_extern_values">6.5.1.&nbsp;
+                    External Values
+                </h4></div></div></div>
+                
+                <a class="indexterm" name="d5e12756"></a>
+                <p>
+Externalization often takes simple constant values and transforms them to
+constant values of a different type. An example would be storing a <code class="classname">
+boolean</code> field as a <code class="classname">char</code>, where <code class="literal">true
+</code> and <code class="literal">false</code> would be stored in the database as
+<code class="literal">'T'</code> and <code class="literal">'F'</code> respectively.
+                </p>
+                <p>
+OpenJPA allows you to define these simple translations in metadata, so that the
+field behaves as in <a class="link" href="ref_guide_pc_scos.html#ref_guide_pc_extern" title="6.5.&nbsp; Externalization">full-fledged
+externalization</a> without requiring externalizer and factory methods.
+External values supports translation of pre-defined simple types (primitives,
+primitive wrappers, and Strings), to other pre-defined simple values.
+                </p>
+                <p>
+Use the OpenJPA
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/ExternalValues.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.ExternalValues</code></a>
+annotation to define external value translations. The values are
+defined in a format similar to that of <a class="link" href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">
+configuration plugins</a>, except that the value pairs represent Java and
+datastore values. To convert the Java boolean values of <code class="literal">true</code>
+and <code class="literal">false</code> to the character values <code class="literal">T</code> and
+<code class="literal">F</code>, for example, you would use the extension value: <code class="literal">
+true=T,false=F</code>.
+                </p>
+                <p>
+If the type of the datastore value is different from the field's type, use the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/Type.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.Type</code></a> annotation
+to define the datastore type.
+                </p>
+                <div class="example"><a name="externvalues_ex"></a><p class="title"><b>Example&nbsp;5.18.&nbsp;
+                        Using External Values
+                    </b></p><div class="example-contents">
+                    
+                    <p>
+This example uses external value translation to transform a string field to an
+integer in the database.
+                    </p>
+<pre class="programlisting">
+public class Magazine {
+
+    @ExternalValues({"SMALL=5", "MEDIUM=8", "LARGE=10"})
+    @Type(int.class)
+    private String sizeWidth;
+
+    ...
+}
+</pre>
+                </div></div><br class="example-break">
+            </div>
+        </div>
+    </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_inverses.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_pc.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_fetch.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.&nbsp;
+            Managed Inverses
+        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;7.&nbsp;
+            Fetch Groups
+        </td></tr></table></div></body></html>
\ No newline at end of file

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

Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_perfpack_eager.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_perfpack_eager.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_perfpack_eager.html Mon Jun  1 20:19:00 2015
@@ -0,0 +1,291 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>8.&nbsp; Eager Fetching</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="ref_guide_pc.html" title="Chapter&nbsp;5.&nbsp; Persistent Classes"><link rel="prev" href="ref_guide_fetch.html" title="7.&nbsp; Fetch Groups"><link rel="next" href="ref_guide_meta.html" title="Chapter&nbsp;6.&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">8.&nbsp;
+            Eager Fetching
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_fetch.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;
+        Persistent Classes
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_meta.html">Next</a></td></tr></table><hr></div><div class="section" title="8.&nbsp; Eager Fetching"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_perfpack_eager">8.&nbsp;
+            Eager Fetching
+        </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_perfpack_eager.html#ref_guide_perfpack_eager_conf">8.1. 
+                Configuring Eager Fetching
+            </a></span></dt><dt><span class="section"><a href="ref_guide_perfpack_eager.html#ref_guide_perfpack_eager_consider">8.2. 
+                Eager Fetching Considerations and Limitations
+            </a></span></dt></dl></div>
+        
+        <a class="indexterm" name="d5e12932"></a>
+        <a class="indexterm" name="d5e12934"></a>
+        <a class="indexterm" name="d5e12937"></a>
+        <a class="indexterm" name="d5e12941"></a>
+        <p>
+Eager fetching is the ability to efficiently load subclass data and related
+objects along with the base instances being queried. Typically, OpenJPA has to
+make a trip to the database whenever a relation is loaded, or when you first
+access data that is mapped to a table other than the least-derived superclass
+table. If you perform a query that returns 100 <code class="classname">Person</code>
+objects, and then you have to retrieve the <code class="classname">Address</code> for
+each person, OpenJPA may make as many as 101 queries (the initial query, plus
+one for the address of each person returned). Or if some of the <code class="classname">
+Person</code> instances turn out to be <code class="classname">Employee</code>s,
+where <code class="classname">Employee</code> has additional data in its own joined
+table, OpenJPA once again might need to make extra database trips to access the
+additional employee data. With eager fetching, OpenJPA can reduce these cases to
+a single query.
+        </p>
+        <p>
+Eager fetching only affects relations in the active fetch groups, and is limited
+by the declared maximum fetch depth and field recursion depth (see
+<a class="xref" href="ref_guide_fetch.html" title="7.&nbsp; Fetch Groups">Section&nbsp;7, &#8220;
+            Fetch Groups
+        &#8221;</a>). In other words, relations that would
+not normally be loaded immediately when retrieving an object or accessing a
+field are not affected by eager fetching. In our example above, the address of
+each person would only be eagerly fetched if the query were configured to
+include the address field or its fetch group, or if the address were in the
+default fetch group. This allows you to control exactly which fields are eagerly
+fetched in different situations. Similarly, queries that exclude subclasses
+aren't affected by eager subclass fetching, described below.
+        </p>
+        <p>
+Eager fetching has three modes:
+        </p>
+        <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                <p>
+<code class="literal">none</code>: No eager fetching is performed. Related objects are
+always loaded in an independent select statement. No joined subclass data is
+loaded unless it is in the table(s) for the base type being queried. Unjoined
+subclass data is loaded using separate select statements rather than a SQL UNION
+operation.
+                </p>
+            </li><li class="listitem">
+                <p>
+                <a class="indexterm" name="d5e12960"></a>
+<code class="literal">join</code>: In this mode, OpenJPA joins to to-one relations in the
+configured fetch groups. If OpenJPA is loading data for a single instance, then
+OpenJPA will also join to any collection field in the configured fetch groups.
+When loading data for multiple instances, though, (such as when executing a
+<code class="classname">Query</code>) OpenJPA will not join to collections by default.
+Instead, OpenJPA defaults to <code class="literal">parallel</code> mode for collections,
+as described below. You can force OpenJPA use a join rather than parallel mode
+for a collection field using the metadata extension described in
+<a class="xref" href="ref_guide_mapping_ext.html#eager-fetch-mode" title="9.2.1.&nbsp; Eager Fetch Mode">Section&nbsp;9.2.1, &#8220;
+                    Eager Fetch Mode
+                &#8221;</a>.
+                </p>
+                <p>
+                <a class="indexterm" name="d5e12968"></a>
+Under <code class="literal">join</code> mode, OpenJPA uses a left outer join (or inner
+join, if the relations' field metadata declares the relation non-nullable) to
+select the related data along with the data for the target objects. This process
+works recursively for to-one joins, so that if <code class="classname">Person</code> has
+an <code class="classname">Address</code>, and <code class="classname">Address</code> has a
+<code class="classname">TelephoneNumber</code>, and the fetch groups are configured
+correctly, OpenJPA might issue a single select that joins across the tables for
+all three classes. To-many joins can not recursively spawn other to-many joins,
+but they can spawn recursive to-one joins.
+                </p>
+                <p>
+Under the <code class="literal">join</code> subclass fetch mode, subclass data in joined
+tables is selected by outer joining to all possible subclass tables of the type
+being queried. As you'll see below, subclass data fetching is configured 
+separately from relation fetching, and can be disabled for specific classes.
+                </p>
+                <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+                    <p>
+Some databases may not support outer joins. Also, OpenJPA can not use
+outer joins if you have set the <a class="link" href="ref_guide_conf_jdbc.html#openjpa.jdbc.DBDictionary" title="6.2.&nbsp; openjpa.jdbc.DBDictionary">
+<code class="literal"> DBDictionary</code></a>'s <code class="literal">JoinSyntax</code> to
+<code class="literal">traditional</code>. See <a class="xref" href="ref_guide_dbsetup_sql92.html" title="6.&nbsp; Setting the SQL Join Syntax">Section&nbsp;6, &#8220;
+            Setting the SQL Join Syntax
+        &#8221;</a>.
+                    </p>
+                </div>
+            </li><li class="listitem">
+                <p>
+                <a class="indexterm" name="d5e12986"></a>
+<code class="literal">parallel</code>: Under this mode, OpenJPA selects to-one relations
+and joined collections as outlined in the <code class="literal">join</code> mode
+description above. Unjoined collection fields, however, are eagerly fetched
+using a separate select statement for each collection, executed in parallel with
+the select statement for the target objects. The parallel selects use the
+<code class="literal">WHERE</code> conditions from the primary select, but add their own
+joins to reach the related data. Thus, if you perform a query that returns 100
+<code class="classname">Company</code> objects, where each company has a list of
+<code class="classname">Employee</code> objects and <code class="classname">Department</code>
+objects, OpenJPA will make 3 queries. The first will select the company objects,
+the second will select the employees for those companies, and the third will
+select the departments for the same companies. Just as for joins, this process
+can be recursively applied to the objects in the relations being eagerly
+fetched. Continuing our example, if the <code class="classname">Employee</code> class
+had a list of <code class="classname">Projects</code> in one of the fetch groups being
+loaded, OpenJPA would execute a single additional select in parallel to load the
+projects of all employees of the matching companies.
+                </p>
+                <p>
+Using an additional select to load each collection avoids transferring more data
+than necessary from the database to the application. If eager joins were used
+instead of parallel select statements, each collection added to the configured
+fetch groups would cause the amount of data being transferred to rise
+dangerously, to the point that you could easily overwhelm the network.
+                </p>
+                <p>
+Polymorphic to-one relations to table-per-class mappings use parallel eager
+fetching because proper joins are impossible. You can force other to-one
+relations to use parallel rather than join mode eager fetching using the
+metadata extension described in <a class="xref" href="ref_guide_mapping_ext.html#eager-fetch-mode" title="9.2.1.&nbsp; Eager Fetch Mode">Section&nbsp;9.2.1, &#8220;
+                    Eager Fetch Mode
+                &#8221;</a>.
+                </p>
+                <p>
+Parallel subclass fetch mode only applies to queries on joined inheritance
+hierarchies. Rather than outer-joining to
+subclass tables, OpenJPA will issue the query separately for each subclass. In
+all other situations, parallel subclass fetch mode acts just like join mode in
+regards to vertically-mapped subclasses.
+                </p>
+                <p>
+When OpenJPA knows that it is selecting for a single object only, it never uses
+<code class="literal">parallel</code> mode, because the additional selects can be made
+lazily just as efficiently. This mode only increases efficiency over <code class="literal">
+join</code> mode when multiple objects with eager relations are being loaded,
+or when multiple selects might be faster than joining to all possible
+subclasses.
+                </p>
+            </li></ul></div>
+        <div class="section" title="8.1.&nbsp; Configuring Eager Fetching"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_perfpack_eager_conf">8.1.&nbsp;
+                Configuring Eager Fetching
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e13006"></a>
+            <p>
+            <a class="indexterm" name="d5e13010"></a>
+            <a class="indexterm" name="d5e13012"></a>
+            <a class="indexterm" name="d5e13014"></a>
+            <a class="indexterm" name="d5e13017"></a>
+You can control OpenJPA's default eager fetch mode through the
+<a class="link" href="ref_guide_conf_jdbc.html#openjpa.jdbc.EagerFetchMode" title="6.4.&nbsp; openjpa.jdbc.EagerFetchMode"><code class="literal">
+openjpa.jdbc.EagerFetchMode</code></a> and
+<a class="link" href="ref_guide_conf_jdbc.html#openjpa.jdbc.SubclassFetchMode" title="6.16.&nbsp; openjpa.jdbc.SubclassFetchMode"><code class="literal">
+openjpa.jdbc.SubclassFetchMode</code></a> configuration properties. Set
+each of these properties to one of the mode names described in the previous
+section: <code class="literal">none, join, parallel</code>. If left unset, the eager
+fetch mode defaults to <code class="literal">parallel</code> and the subclass fetch mode
+defaults to <code class="literal">join</code> These are generally the most robust and
+performant strategies.
+            </p>
+            <p>
+You can easily override the default fetch modes at runtime for any lookup or
+query through OpenJPA's fetch configuration APIs. See
+<a class="xref" href="ref_guide_runtime.html" title="Chapter&nbsp;9.&nbsp; Runtime Extensions">Chapter&nbsp;9, <i>
+        Runtime Extensions
+    </i></a> for details.
+            </p>
+            <div class="example"><a name="ref_guide_perfpack_eager_def"></a><p class="title"><b>Example&nbsp;5.23.&nbsp;
+                    Setting the Default Eager Fetch Mode
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+&lt;property name="openjpa.jdbc.EagerFetchMode" value="parallel"/&gt;
+&lt;property name="openjpa.jdbc.SubclassFetchMode" value="join"/&gt;
+</pre>
+            </div></div><br class="example-break">
+            <div class="example"><a name="ref_guide_perfpack_eager_runtime"></a><p class="title"><b>Example&nbsp;5.24.&nbsp;
+                    Setting the Eager Fetch Mode at Runtime
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+import org.apache.openjpa.persistence.jdbc.*;
+
+...
+
+Query q = em.createQuery("select p from Person p where p.address.state = 'TX'");
+OpenJPAQuery kq = OpenJPAPersistence.cast(q);
+JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan();
+fetch.setEagerFetchMode(FetchMode.PARALLEL);
+fetch.setSubclassFetchMode(FetchMode.JOIN);
+List results = q.getResultList();
+</pre>
+            </div></div><br class="example-break">
+            <p>
+You can specify a default subclass fetch mode for an individual class with the
+metadata extension described in <a class="xref" href="ref_guide_mapping_ext.html#subclass-fetch-mode" title="9.1.1.&nbsp; Subclass Fetch Mode">Section&nbsp;9.1.1, &#8220;
+                    Subclass Fetch Mode
+                &#8221;</a>.
+Note, however, that you cannot "upgrade" the runtime fetch mode with your class
+setting. If the runtime fetch mode is <code class="literal">none</code>, no eager
+subclass data fetching will take place, regardless of your metadata setting.
+            </p>
+            <p>
+This applies to the eager fetch mode metadata extension as well (see
+<a class="xref" href="ref_guide_mapping_ext.html#eager-fetch-mode" title="9.2.1.&nbsp; Eager Fetch Mode">Section&nbsp;9.2.1, &#8220;
+                    Eager Fetch Mode
+                &#8221;</a>). You can use this extension to
+disable eager fetching on a field or to declare that a collection would rather
+use joins than parallel selects or vice versa. But an extension value of
+<code class="literal">join</code> won't cause any eager joining if the fetch
+configuration's setting is <code class="literal">none</code>.
+            </p>
+        </div>
+        <div class="section" title="8.2.&nbsp; Eager Fetching Considerations and Limitations"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_perfpack_eager_consider">8.2.&nbsp;
+                Eager Fetching Considerations and Limitations
+            </h3></div></div></div>
+            
+            <p>
+There are several important points that you should consider when using eager
+fetching:
+            </p>
+            <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                    <p>
+                    <a class="indexterm" name="d5e13048"></a>
+                    <a class="indexterm" name="d5e13051"></a>
+When you are using <code class="literal">parallel</code> eager fetch mode and you have
+large result sets enabled (see <a class="xref" href="ref_guide_dbsetup_lrs.html" title="10.&nbsp; Large Result Sets">Section&nbsp;10, &#8220;
+            Large Result Sets
+        &#8221;</a>)
+or you place a range on a query, OpenJPA performs the needed parallel selects on
+one page of results at a time. For example, suppose your <code class="literal">
+FetchBatchSize</code> is set to 20, and you perform a large result set query
+on a class that has collection fields in the configured fetch groups. OpenJPA
+will immediately cache the first <code class="literal">20</code> results of the query
+using <code class="literal">join</code> mode eager fetching only. Then, it will issue the
+extra selects needed to eager fetch your collection fields according to
+<code class="literal">parallel</code> mode. Each select will use a SQL <code class="literal">IN
+</code> clause (or multiple <code class="literal">OR</code> clauses if your class has a
+compound primary key) to limit the selected collection elements to those owned
+by the 20 cached results.
+                    </p>
+                    <p>
+Once you iterate past the first 20 results, OpenJPA will cache the next 20 and
+again issue any needed extra selects for collection fields, and so on. This
+pattern ensures that you get the benefits of eager fetching without bringing
+more data into memory than anticipated.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+Once OpenJPA eager-joins into a class, it cannot issue any further eager to-many
+joins or parallel selects from that class in the same query. To-one joins,
+however, can recurse to any level.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+Using a to-many join makes it impossible to determine the number of instances
+the result set contains without traversing the entire set. This is because each
+result object might be represented by multiple rows. Thus, queries with a range
+specification or queries configured for lazy result set traversal automatically
+turn off eager to-many joining.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+OpenJPA cannot eagerly join to polymorphic relations to non-leaf classes in a
+table-per-class inheritance hierarchy. You can work around this restriction
+using the mapping extensions described in <a class="xref" href="ref_guide_mapping_ext.html#nonpolymorphic" title="9.2.2.&nbsp; Nonpolymorphic">Section&nbsp;9.2.2, &#8220;
+                    Nonpolymorphic
+                &#8221;</a>.
+                    </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="ref_guide_fetch.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_pc.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_meta.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7.&nbsp;
+            Fetch Groups
+        &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;6.&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/ref_guide_perfpack_eager.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_remote.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_remote.html (added)
+++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_remote.html Mon Jun  1 20:19:00 2015
@@ -0,0 +1,420 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>Chapter&nbsp;12.&nbsp; Remote and Offline Operation</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="ref_guide.html" title="Part&nbsp;3.&nbsp;Reference Guide"><link rel="prev" href="ref_guide_encryption.html" title="Chapter&nbsp;11.&nbsp; Encryption Provider"><link rel="next" href="ref_guide_event.html" title="2.&nbsp; Remote Event Notification Framework"></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;12.&nbsp;
+        Remote and Offline Operation
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_encryption.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;3.&nbsp;Reference Guide</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_event.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;12.&nbsp; Remote and Offline Operation" id="ref_guide_remote"><div class="titlepage"><div><div><h2 class="title">Chapter&nbsp;12.&nbsp;
+        Remote and Offline Operation
+    </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_detach">1. 
+            Detach and Attach
+        </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_detach_behavior">1.1. 
+                Detach Behavior
+            </a></span></dt><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_attach_behavior">1.2. 
+                Attach Behavior
+            </a></span></dt><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_detach_graph">1.3. 
+                Defining the Detached Object Graph
+            </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_detach_state">1.3.1. 
+                    Detached State
+                </a></span></dt><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_detach_field">1.3.2. 
+                    Detached State Field
+                </a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="ref_guide_event.html">2. 
+            Remote Event Notification Framework
+        </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_event.html#ref_guide_event_conf">2.1. 
+                Remote Commit Provider Configuration
+            </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_event.html#ref_guide_event_conf_jms">2.1.1. 
+                    JMS
+                </a></span></dt><dt><span class="section"><a href="ref_guide_event.html#ref_guide_event_conf_tcp">2.1.2. 
+                    TCP
+                </a></span></dt><dt><span class="section"><a href="ref_guide_event.html#ref_guide_event_conf_common">2.1.3. 
+                    Common Properties
+                </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_event.html#ref_guide_event_customization">2.2. 
+                Customization
+            </a></span></dt></dl></dd></dl></div>
+    
+    <a class="indexterm" name="d5e16491"></a>
+    <a class="indexterm" name="d5e16493"></a>
+    <p>
+The standard JPA runtime environment was originally just 
+<span class="emphasis"><em>local</em></span> and 
+<span class="emphasis"><em>online</em></span>. It is <span class="emphasis"><em>local</em></span> in that components
+such as <code class="classname">EntityManager</code>s and queries connect directly to
+the datastore and execute their actions in the same JVM as the code using them.
+It is <span class="emphasis"><em>online</em></span> in that all changes to managed objects must be
+made in the context of an active <code class="classname"> EntityManager</code>. These
+two properties, combined with the fact that <code class="classname">
+EntityManager</code>s cannot be serialized for storage or network transfer,
+made the standard JPA runtime difficult to incorporate into some enterprise and
+client/server program designs.
+    </p>
+    <p>
+JPA has now provided <span class="emphasis"><em>offline</em></span> capability through the 
+detach() and merge() methods on the EntityManager interface. OpenJPA has
+extended this to include additional detach...() and merge...() methods. All of
+these are documented in 
+<a class="link" href="ref_guide_remote.html#ref_guide_detach" title="1.&nbsp; Detach and Attach">Detach and Attach APIs</a>. In addition,
+OpenJPA has added <span class="emphasis"><em>remote</em></span> capability in the form of
+<a class="link" href="ref_guide_event.html" title="2.&nbsp; Remote Event Notification Framework">Remote Commit Events</a>. The following
+sections explain these capabilities in detail.
+    </p>
+    <div class="section" title="1.&nbsp; Detach and Attach"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_detach">1.&nbsp;
+            Detach and Attach
+        </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_detach_behavior">1.1. 
+                Detach Behavior
+            </a></span></dt><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_attach_behavior">1.2. 
+                Attach Behavior
+            </a></span></dt><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_detach_graph">1.3. 
+                Defining the Detached Object Graph
+            </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_detach_state">1.3.1. 
+                    Detached State
+                </a></span></dt><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_detach_field">1.3.2. 
+                    Detached State Field
+                </a></span></dt></dl></dd></dl></div>
+        
+        <a class="indexterm" name="d5e16511"></a>
+        <a class="indexterm" name="d5e16513"></a>
+        <p>
+The JPA Overview describes the specification's standard detach and attach APIs
+in <a class="xref" href="jpa_overview_em_lifecycle.html" title="2.&nbsp; Entity Lifecycle Management">Section&nbsp;2, &#8220;
+            Entity Lifecycle Management
+        &#8221;</a>. This section enumerates
+OpenJPA's enhancements to the standard behavior.
+        </p>
+        <div class="section" title="1.1.&nbsp; Detach Behavior"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_detach_behavior">1.1.&nbsp;
+                Detach Behavior
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e16520"></a>
+<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+<p>
+In version 2.0, the detach behavior has changed from the previous
+version. See the migration section
+<a class="link" href="migration_considerations.html#migration_detach_behavior" title="1.1.2.&nbsp; Detach Behavior">Detach Behavior</a> for details.
+</p>
+</div>
+            <p>
+In JPA, objects detach automatically when they are serialized or when a
+<a class="link" href="jpa_overview_emfactory_perscontext.html" title="3.&nbsp; Persistence Context">persistence context</a>
+ends. The specification also allows objects to be explicitly detached using
+the following javax.persistence.EntityManager method:
+</p>
+<pre class="programlisting">
+public void detach(Object)
+</pre>
+			<p>
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top">
+<code class="classname">OpenJPAEntityManager</code></a>, however, provides
+additional detach methods.
+            </p>
+<pre class="programlisting">
+public &lt;T&gt; T detachCopy(T pc):
+public Object[] detachAll(Object... pcs):
+public Collection detachAll(Collection pcs):
+</pre>
+<p>
+The behavior of the detach operation is as follows:
+</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+		The detached objects are removed from the persistent context.
+	</li><li class="listitem">
+		The objects are <span class="emphasis"><em>not</em></span> flushed to the database.
+	</li><li class="listitem">
+		If Cascade=detach is specified for a referenced entity, the detach
+		operation is cascaded. Otherwise, it is not.
+	</li><li class="listitem">
+		For the detachCopy method only, the entity is copied for the return
+		value.
+	</li></ul></div><p>
+</p>
+        </div>
+        <div class="section" title="1.2.&nbsp; Attach Behavior"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_attach_behavior">1.2.&nbsp;
+                Attach Behavior
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e16542"></a>
+            <p>
+When attaching, OpenJPA uses several strategies to determine the optimal way to
+merge changes made to the detached instance. As you will see, these strategies
+can even be used to attach changes made to a transient instance which was never
+detached in the first place.
+            </p>
+            <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                    <p>
+If the instance was detached and <a class="link" href="ref_guide_remote.html#ref_guide_detach_graph" title="1.3.&nbsp; Defining the Detached Object Graph">
+detached state</a> is enabled, OpenJPA will use the detached state to
+determine the object's version and primary key values. In addition, this state
+will tell OpenJPA which fields were loaded at the time of detach, and in turn
+where to expect changes. Loaded detached fields with null values will set the
+attached instance's corresponding fields to null.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+If the instance has a <code class="literal">Version</code> field,
+OpenJPA will consider the object detached if the version field has a non-default
+value, and new otherwise.  Similarly, if the instance has 
+<code class="literal">GeneratedValue</code> primary key fields, OpenJPA will consider the
+object detached if any of these fields have non-default values, and new 
+otherwise.
+                    </p>
+                    <p>
+When attaching null fields in these cases, OpenJPA cannot distinguish between a
+field that was unloaded and one that was intentionally set to null. In this
+case, OpenJPA will use the current <a class="link" href="ref_guide_remote.html#ref_guide_detach_graph" title="1.3.&nbsp; Defining the Detached Object Graph">
+detach state</a> setting to determine how to handle null fields: fields that
+would have been included in the detached state are treated as loaded, and will
+in turn set the corresponding attached field to null.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+If neither of the above cases apply, OpenJPA will check to see if an instance
+with the same primary key values exists in the database. If so, the object is
+considered detached. Otherwise, it is considered new.
+                    </p>
+                </li></ul></div>
+            <p>
+These strategies will be assigned on a per-instance basis, such that during the
+attachment of an object graph more than one of the above strategies may be used.
+            </p>
+            <p>
+If you attempt to attach a versioned instance whose representation has changed
+in the datastore since detachment, OpenJPA will throw an optimistic concurrency
+exception upon commit or flush, just as if a normal optimistic conflict was
+detected. When attaching an instance whose database record has been deleted
+since detaching, or when attaching a detached instance into a manager that has a
+stale version of the object, OpenJPA will throw an optimistic concurrency
+exception from the attach method. In these cases, OpenJPA sets the <code class="literal">
+RollbackOnly</code> flag on the transaction.
+            </p>
+        </div>
+        <div class="section" title="1.3.&nbsp; Defining the Detached Object Graph"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_detach_graph">1.3.&nbsp;
+                Defining the Detached Object Graph
+            </h3></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_detach_state">1.3.1. 
+                    Detached State
+                </a></span></dt><dt><span class="section"><a href="ref_guide_remote.html#ref_guide_detach_field">1.3.2. 
+                    Detached State Field
+                </a></span></dt></dl></div>
+            
+            <a class="indexterm" name="d5e16563"></a>
+            <p>
+When detached objects lose their association with the OpenJPA runtime, they also
+lose the ability to load additional state from the datastore. It is important,
+therefore, to populate objects with all the persistent state you will need
+before detaching them. While you are free to do this manually, OpenJPA includes
+facilities for automatically populating objects when they detach.
+            </p>
+            <div class="section" title="1.3.1.&nbsp; Detached State"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_detach_state">1.3.1.&nbsp;
+                    Detached State
+                </h4></div></div></div>
+                
+                <a class="indexterm" name="d5e16569"></a>
+                <p>
+The <a class="link" href="ref_guide_conf_openjpa.html#openjpa.DetachState" title="5.30.&nbsp; openjpa.DetachState"><code class="literal">openjpa.DetachState</code>
+</a> configuration property determines which fields and relations are
+detached by default. All settings are recursive. They are:
+                </p>
+                <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
+                        <p>
+<code class="literal">loaded</code>: Detach all fields and relations that are already
+loaded, but don't include unloaded fields in the detached graph. This is the
+default.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">fetch-groups</code>: Detach all fields and relations in the current
+<a class="link" href="ref_guide_runtime.html" title="Chapter&nbsp;9.&nbsp; Runtime Extensions">fetch configuration</a>. For more
+information on custom fetch groups, see <a class="xref" href="ref_guide_fetch.html" title="7.&nbsp; Fetch Groups">Section&nbsp;7, &#8220;
+            Fetch Groups
+        &#8221;</a>.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">all</code>: Detach all fields and relations. Be very careful when
+using this mode; if you have a highly-connected domain model, you could end up
+bringing every object in the database into memory!
+                        </p>
+                    </li></ol></div>
+                <p>
+Any field that is not included in the set determined by the detach mode is set
+to its Java default value in the detached instance.
+                </p>
+                <p>
+The <code class="literal">openjpa.DetachState</code> option is actually a plugin string
+(see <a class="xref" href="ref_guide_conf_plugins.html" title="4.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
+            Plugin Configuration
+        &#8221;</a>) that allows you to also
+configure the following options related to detached state:
+                </p>
+                <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                        <p>
+<code class="literal">DetachedStateField</code>: As described in
+<a class="xref" href="ref_guide_remote.html#ref_guide_attach_behavior" title="1.2.&nbsp; Attach Behavior">Section&nbsp;1.2, &#8220;
+                Attach Behavior
+            &#8221;</a> above, OpenJPA can take
+advantage of a <span class="emphasis"><em>detached state field</em></span> to make the attach
+process more efficient. This field is added by the enhancer and is not visible
+to your application. Set this property to one of the following values:
+                        </p>
+                        <div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem">
+                                <p>
+<code class="literal">transient</code>: Use a transient detached state field. This gives
+the benefits of a detached state field to local objects that are never
+serialized, but retains serialization compatibility for client tiers without
+access to the enhanced versions of your classes or the OpenJPA runtime.
+This is the default.
+                                </p>
+                            </li><li class="listitem">
+                                <p>
+<code class="literal">true</code>: Use a non-transient detached state field so that
+objects crossing serialization barriers can still be attached efficiently. This
+requires, however, that your client tier have the enhanced versions of your
+classes and the OpenJPA runtime.
+                                </p>
+                            </li><li class="listitem">
+                                <p>
+<code class="literal">false</code>: Do not use a detached state field.  No OpenJPA runtime
+will be required for client tiers.
+                                </p>
+                            </li></ul></div>
+                        <p>
+The detached state field is also used to determine when proxies should be
+removed from entities during serialization.  See the 
+<a class="xref" href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_serial" title="6.4.4.&nbsp; Serialization">Section&nbsp;6.4.4, &#8220;
+                    Serialization
+                &#8221;</a> section for more details.
+                        </p>
+                        <p>
+You can override the setting of this property or declare your own detached state
+field on individual classes using OpenJPA's metadata extensions. See
+<a class="xref" href="ref_guide_remote.html#ref_guide_detach_field" title="1.3.2.&nbsp; Detached State Field">Section&nbsp;1.3.2, &#8220;
+                    Detached State Field
+                &#8221;</a> below.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">DetachedStateManager</code>: Whether to use a detached state
+manager. A detached state manager makes attachment much more efficient. Like a
+detached state field, however, it breaks serialization compatibility with the
+unenhanced class if it isn't transient.
+                        </p>
+                        <p>
+This setting piggybacks on the <code class="literal">DetachedStateField</code> setting
+above. If your detached state field is transient, the detached state manager
+will also be transient. If the detached state field is disabled, the detached
+state manager will also be disabled. This is typically what you'll want. By
+setting <code class="literal"> DetachedStateField</code> to true (or transient) and
+setting this property to false, however, you can use a detached state field
+<span class="bold"><strong>without</strong></span> using a detached state manager. This
+may be useful for debugging or for legacy OpenJPA users who find differences
+between OpenJPA's behavior with a detached state manager and OpenJPA's older
+behavior without one.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">AccessUnloaded</code>: Whether to allow access to unloaded fields
+of detached objects. Defaults to true. Set to false to throw an exception
+whenever an unloaded field is accessed. This option is only available when you
+use detached state managers, as determined by the settings above.
+                        </p>
+                    </li><li class="listitem">                    
+                        <p>
+<code class="literal">LiteAutoDetach</code>: <span class="bold"><strong>This option is ONLY valid for the <code class="literal">loaded</code> 
+DetachState setting.</strong></span> Detach all fields and relations as described by the loaded 
+property when an explicit detach is requested or when a 
+single Entity is being detached as part of serialization. When the entire 
+persistence context is being auto-detached ( <code class="literal">openjpa.AutoDetach</code> ), 
+the minimal amount of work will be completed to disassociate all Entities from 
+the persistence context. <span class="bold"><strong>It is highly recommended that all Entities have a 
+@Version field when using this property</strong></span>. In addition, care needs to be taken 
+when this value is set to true as the following caveats apply: 
+                </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem">
+                        <p>
+A relationship from a managed Entity to an unmanaged Entity which was detached by the lite detach setting will not be persisted.                                       
+                        </p>       
+                    </li><li class="listitem">
+                        <p>
+When merging a detached Entity back into the persistence context any lazily loaded fields that were marked to null when detached will not be persisted.                                       
+                        </p>       
+                    </li></ul></div><p>
+                        </p>
+                    </li><li class="listitem">                    
+                        <p>
+<code class="literal">DetachProxyFields</code>: <span class="bold"><strong>This option is ONLY valid when used in conjunction with the <code class="literal">LiteAutoDetach</code> 
+DetachState setting.</strong></span> When detaching the persistence context, all proxies will be left in place. Note, that 
+all <code class="literal">Large Result Sets</code> will be removed.
+                        </p>
+                        <div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem">
+                            <code class="literal">true(default)</code>: All proxies will be removed and LRS fields will be removed. 
+                        	</li><li class="listitem">
+                            <code class="literal">false</code>: All proxies will be left in place and LRS fields will be removed. 
+                        	</li></ul></div>                                                    
+                    </li></ul></div>
+                <div class="example"><a name="ref_guide_detach_graph_confex"></a><p class="title"><b>Example&nbsp;12.1.&nbsp;
+                        Configuring Detached State
+                    </b></p><div class="example-contents">
+                    
+<pre class="programlisting">
+&lt;property name="openjpa.DetachState" value="fetch-groups(DetachedStateField=true)"/&gt;
+</pre>
+                </div></div><br class="example-break">
+                <p>
+You can also alter the set of fields that will be included in the detached graph
+at runtime.
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html" target="_top">
+<code class="classname">OpenJPAEntityManager</code></a>s expose the following APIs
+for controlling detached state:
+                </p>
+<pre class="programlisting">
+public DetachStateType getDetachState();
+public void setDetachState(DetachStateType type);
+</pre>
+                <p>
+The <code class="classname">DetachStateType</code> enum contains the following values:
+                </p>
+<pre class="programlisting">
+enum DetachStateType {
+    FETCH_GROUPS,
+    LOADED,
+    ALL
+}
+</pre>
+            </div>
+            <div class="section" title="1.3.2.&nbsp; Detached State Field"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_detach_field">1.3.2.&nbsp;
+                    Detached State Field
+                </h4></div></div></div>
+                
+                <a class="indexterm" name="d5e16656"></a>
+                <p>
+When the detached state field is enabled, the OpenJPA enhancer adds an
+additional field to the enhanced version of your class. This field of type
+<code class="classname">Object</code>. OpenJPA uses this field for bookkeeping
+information, such as the versioning data needed to detect optimistic concurrency
+violations when the object is re-attached.
+                </p>
+                <p>
+It is possible to define this detached state field yourself. Declaring this
+field in your class metadata prevents the enhancer from adding any extra fields
+to the class, and keeps the enhanced class serialization-compatible with the
+unenhanced version. The detached state field must not be persistent. See
+<a class="xref" href="ref_guide_meta_ext.html#detached-state-field" title="4.1.3.&nbsp; Detached State">Section&nbsp;4.1.3, &#8220;
+                    Detached State
+                &#8221;</a> for details on how to declare a
+detached state field.
+                </p>
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+public class Magazine
+    implements Serializable {
+
+    private String name;
+    @DetachedState private Object state;
+    ...
+}
+</pre>
+            </div>
+        </div>
+    </div>
+    
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_encryption.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_event.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;11.&nbsp;
+        Encryption Provider
+    &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;
+            Remote Event Notification Framework
+        </td></tr></table></div></body></html>
\ No newline at end of file

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



Mime
View raw message