openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ilgro...@apache.org
Subject svn commit: r1004302 [31/41] - in /websites/production/openjpa/content/builds/2.4.2: ./ apache-openjpa/ apache-openjpa/docs/ apache-openjpa/docs/css/ apache-openjpa/docs/img/
Date Fri, 06 Jan 2017 19:19:22 GMT
Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_enterprise_methodql.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_enterprise_methodql.html (added)
+++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_enterprise_methodql.html Fri Jan  6 19:19:20 2017
@@ -0,0 +1,80 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>5.&nbsp; MethodQL</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_runtime.html" title="Chapter&nbsp;9.&nbsp; Runtime Extensions"><link rel="prev" href="ref_guide_savepoints.html" title="4.&nbsp; Savepoints"><link rel="next" href="ref_guide_sequence.html" title="6.&nbsp; Generators"></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">5.&nbsp;
+                MethodQL
+            </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_savepoints.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;9.&nbsp;
+        Runtime Extensions
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_sequence.html">Next</a></td></tr></table><hr></div><div class="section" id="ref_guide_enterprise_methodql"><div class="titlepage"><div><div><h2 class="title" style="clear: both">5.&nbsp;
+                MethodQL
+            </h2></div></div></div>
+            
+            <a class="indexterm" name="d5e15763"></a>
+            <a class="indexterm" name="d5e15765"></a>
+            <p>
+If JPQL and SQL queries do not match your needs, OpenJPA also allows you to name
+a Java method to use to load a set of objects. In a <span class="emphasis"><em>MethodQL
+</em></span> query, the query string names a static method to invoke to determine
+the matching objects:
+            </p>
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+...
+
+// the method query language is 'openjpa.MethodQL'.
+// set the query string to the target method to execute, prefixed by fullly-
+// qualified class name.
+// If a candidate class has been specified for the query, then if the class is 
+// in the candidate class' package or in the query imports, you can omit the 
+// package. If the method is in the candidate class, you can omit the class name 
+// and just specify the method name.
+
+  OpenJPAEntityManager oem = OpenJPAPersistence.cast(emf);
+  OpenJPAQuery q = oem.createQuery("openjpa.MethodQL", "com.xyz.Finder.getByName");
+
+// parameters are passed the same way as in standard queries
+// but you have to declare the parameters with their types on the implementation
+
+// Unwrap the implementation and declare parameters with types in a 
+// comma-separated list
+  q.unwrap(org.apache.openjpa.kernel.Query.class)
+   .declareParameters("String firstName, String lastName");
+
+  q.setParameter("firstName", "Fred").setParameter("lastName", "Lucas");
+
+// this executes the target method to get the results
+  List results = q.getResultList();
+
+// The result is returned as a list but the element(s) in the list is determined 
+// by the returned value of the target method
+ 
+</pre>
+            <p>
+For datastore queries, the method must have the following signature:
+            </p>
+<pre class="programlisting">
+public static <a class="ulink" href="../javadoc/org/apache/openjpa/lib/rop/ResultObjectProvider.html" target="_top">ResultObjectProvider</a> xxx(<a class="ulink" href="../javadoc/org/apache/openjpa/kernel/StoreContext.html" target="_top">StoreContext</a> ctx, <a class="ulink" href="../javadoc/org/apache/openjpa/meta/ClassMetaData.html" target="_top">ClassMetaData</a> meta, boolean subclasses, Map params, <a class="ulink" href="../javadoc/org/apache/openjpa/kernel/FetchConfiguration.html" target="_top">FetchConfiguration </a> fetch)
+</pre>
+            <p>
+The returned result object provider should produce objects of the candidate
+class that match the method's search criteria. If the returned objects do not
+have all fields in the given fetch configuration loaded, OpenJPA will make
+additional trips to the datastore as necessary to fill in the data for the
+missing fields.
+            </p>
+            <p>
+In-memory execution is slightly different, taking in one object at a time and
+returning a boolean on whether the object matches the query:
+            </p>
+<pre class="programlisting">
+public static boolean xxx(<a class="ulink" href="../javadoc/org/apache/openjpa/kernel/StoreContext.html" target="_top">StoreContext</a> ctx, <a class="ulink" href="../javadoc/org/apache/openjpa/meta/ClassMetaData.html" target="_top">ClassMetaData</a> meta, boolean subclasses, Object obj, Map params, <a class="ulink" href="../javadoc/org/apache/openjpa/kernel/FetchConfiguration.html" target="_top">FetchConfiguration</a> fetch)
+</pre>
+            <p>
+In both method versions, the given <code class="literal">params</code> map contains the
+names and values of all the parameters for the query.
+            </p>
+        </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_savepoints.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_runtime.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_sequence.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.&nbsp;
+            Savepoints
+        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;6.&nbsp;
+            Generators
+        </td></tr></table></div></body></html>
\ No newline at end of file

Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_enterprise_trans.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_enterprise_trans.html (added)
+++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_enterprise_trans.html Fri Jan  6 19:19:20 2017
@@ -0,0 +1,110 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>2.&nbsp; Integrating with the Transaction Manager</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_deploy.html" title="Chapter&nbsp;8.&nbsp; Deployment"><link rel="prev" href="ref_guide_deploy.html" title="Chapter&nbsp;8.&nbsp; Deployment"><link rel="next" href="ref_guide_enterprise_xa.html" title="3.&nbsp; XA Transactions"></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;
+            Integrating with the Transaction Manager
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_deploy.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;8.&nbsp;
+        Deployment
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_enterprise_xa.html">Next</a></td></tr></table><hr></div><div class="section" id="ref_guide_enterprise_trans"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.&nbsp;
+            Integrating with the Transaction Manager
+        </h2></div></div></div>
+		
+		<a class="indexterm" name="d5e15209"></a>
+		<a class="indexterm" name="d5e15212"></a>
+		<a class="indexterm" name="d5e15215"></a>
+		<a class="indexterm" name="d5e15218"></a>
+		<p>
+OpenJPA <code class="classname">EntityManager</code>s have the ability to automatically
+synchronize their transactions with an external transaction manager.  Whether 
+or not <code class="classname">EntityManager</code>s from a given <code class="classname">
+EntityManagerFactory</code> exhibit this behavior by default depends on 
+the transaction type you set for the factory's persistence unit in
+your <code class="filename">persistence.xml</code> file.  OpenJPA uses the given
+transaction type internally to set the
+<a class="link" href="ref_guide_conf_openjpa.html#openjpa.TransactionMode" title="5.69.&nbsp; openjpa.TransactionMode"><code class="literal">openjpa.TransactionMode
+</code></a> configuration property.  This property accepts the following
+modes:
+        </p>
+		<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+				<p>
+<code class="literal">local</code>: Perform transaction operations locally.
+				</p>
+			</li><li class="listitem">
+				<p>
+<code class="literal">managed</code>: Integrate with the application server's managed 
+global transactions.  
+				</p>
+			</li></ul></div> 
+        <p>
+You can override the global transaction mode setting when you obtain an
+<code class="classname">EntityManager</code> using the 
+<a class="ulink" href="http://download.oracle.com/javaee/6/api/javax/persistence/EntityManagerFactory.html" target="_top">
+<code class="classname">EntityManagerFactory</code></a>'s
+<code class="methodname">createEntityManager(Map props)</code> method.  Simply set the
+<code class="literal">openjpa.TransactionMode</code> key of the given <code class="classname">Map
+</code> to the desired value.  
+		</p>
+        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+            <p>
+You can also override the <code class="literal">openjpa.ConnectionUserName</code>,
+<code class="literal">openjpa.ConnectionPassword</code>, and <code class="literal">
+openjpa.ConnectionRetainMode</code> settings using the given <code class="classname">
+Map</code>. 
+            </p>
+        </div>
+		<p>
+<a class="indexterm" name="d5e15248"></a>
+In order to use global transactions, OpenJPA must be able to access the 
+application server's <code class="classname">
+javax.transaction.TransactionManager</code>.  OpenJPA can automatically 
+discover the transaction manager for most major application servers.  
+Occasionally, however, you might have to point OpenJPA to the transaction 
+manager for an unrecognized or non-standard application server setup.  This is 
+accomplished through the <a class="link" href="ref_guide_conf_openjpa.html#openjpa.ManagedRuntime" title="5.45.&nbsp; openjpa.ManagedRuntime"><code class="literal">
+openjpa.ManagedRuntime</code></a> configuration property.  This
+property describes an 
+<a class="ulink" href="../javadoc/org/apache/openjpa/ee/ManagedRuntime.html" target="_top"><code class="classname">
+org.apache.openjpa.ee.ManagedRuntime</code></a> implementation to use
+for transaction manager discovery.  You can specify your own implementation, 
+or use one of the built-ins:
+		</p>
+		<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+				<p>
+<code class="literal">auto</code>: This is the default.  It is an alias for the
+<a class="ulink" href="../javadoc/org/apache/openjpa/ee/AutomaticManagedRuntime.html" target="_top">
+<code class="classname">org.apache.openjpa.ee.AutomaticManagedRuntime</code></a>
+class.  This managed runtime is able to automatically integrate with several 
+common application servers.
+				</p>
+			</li><li class="listitem">
+				<p>
+<code class="literal">invocation</code>: An alias for the 
+<a class="ulink" href="../javadoc/org/apache/openjpa/ee/InvocationManagedRuntime.html" target="_top">
+<code class="classname">org.apache.openjpa.ee.InvocationManagedRuntime</code></a>
+class.  You can configure this runtime to invoke any static
+method in order to obtain the appserver's transaction manager.
+				</p>
+			</li><li class="listitem">
+				<p>
+<code class="literal">jndi</code>: An alias for the 
+<a class="ulink" href="../javadoc/org/apache/openjpa/ee/JNDIManagedRuntime.html" target="_top">
+<code class="classname">org.apache.openjpa.ee.JNDIManagedRuntime</code></a>
+class.  You can configure this runtime to look up the transaction manager at 
+any JNDI location.
+				</p>
+			</li></ul></div>
+		<p>
+See the Javadoc for of each class for details on the bean properties 
+you can pass to these plugins in your configuration string.  
+		</p>
+		<div class="example" id="ref_guide_enterprise_transex"><p class="title"><b>Example&nbsp;8.1.&nbsp;Configuring Transaction Manager Integration</b></p><div class="example-contents">
+			
+<pre class="programlisting">
+&lt;property name="openjpa.TransactionMode" value="managed"/&gt;
+&lt;property name="openjpa.ManagedRuntime" value="jndi(TransactionManagerName=java:/TransactionManager)"/&gt;
+</pre>
+		</div></div><br class="example-break">
+	</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_deploy.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_deploy.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_enterprise_xa.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;8.&nbsp;
+        Deployment
+    &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;
+            XA Transactions
+        </td></tr></table></div></body></html>
\ No newline at end of file

Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_enterprise_xa.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_enterprise_xa.html (added)
+++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_enterprise_xa.html Fri Jan  6 19:19:20 2017
@@ -0,0 +1,92 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>3.&nbsp; XA Transactions</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_deploy.html" title="Chapter&nbsp;8.&nbsp; Deployment"><link rel="prev" href="ref_guide_enterprise_trans.html" title="2.&nbsp; Integrating with the Transaction Manager"><link rel="next" href="ref_guide_runtime.html" title="Chapter&nbsp;9.&nbsp; Runtime Extensions"></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;
+            XA Transactions
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_enterprise_trans.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;8.&nbsp;
+        Deployment
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_runtime.html">Next</a></td></tr></table><hr></div><div class="section" id="ref_guide_enterprise_xa"><div class="titlepage"><div><div><h2 class="title" style="clear: both">3.&nbsp;
+            XA Transactions
+        </h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="ref_guide_enterprise_xa.html#ref_guide_enterprise_xa_req">3.1. 
+                Using OpenJPA with XA Transactions
+            </a></span></dt></dl></div>
+        
+        <a class="indexterm" name="d5e15277"></a>
+        <a class="indexterm" name="d5e15280"></a>
+        <p>
+The X/Open Distributed Transaction Processing (X/Open DTP) model, designed by
+<a class="ulink" href="http://www.opengroup.org/" target="_top">The Open Group</a> (a vendor consortium),
+defines a standard communication architecture that provides the following:
+        </p>
+        <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+                <p>
+Concurrent execution of applications on shared resources.
+                </p>
+            </li><li class="listitem">
+                <p>
+Coordination of transactions across applications.
+                </p>
+            </li><li class="listitem">
+                <p>
+Components, interfaces, and protocols that define the architecture and provide
+portability of applications.
+                </p>
+            </li><li class="listitem">
+                <p>
+Atomicity of transaction systems.
+                </p>
+            </li><li class="listitem">
+                <p>
+Single-thread control and sequential function-calling.
+                </p>
+            </li></ul></div>
+        <p>
+The X/Open DTP XA standard defines the application programming interfaces that a
+resource manager uses to communicate with a transaction manager. The XA
+interfaces enable resource managers to join transactions, to perform two-phase
+commit, and to recover in-doubt transactions following a failure.
+        </p>
+        <div class="section" id="ref_guide_enterprise_xa_req"><div class="titlepage"><div><div><h3 class="title">3.1.&nbsp;
+                Using OpenJPA with XA Transactions
+            </h3></div></div></div>
+            
+            <p>
+OpenJPA supports XA-compliant transactions when used in a properly configured
+managed environment. The following components are required:
+            </p>
+            <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+                    <p>
+A managed environment that provides an XA compliant transaction manager.
+Examples of this are application servers such as WebLogic or JBoss.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+Instances of a <code class="classname">javax.sql.XADataSource</code> for each of the
+<code class="classname">DataSource</code>s that OpenJPA will use.
+                    </p>
+                </li></ul></div>
+            <p>
+Given these components, setting up OpenJPA to participate in distributed
+transactions is a simple two-step process:
+            </p>
+            <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
+					<p>
+Integrate OpenJPA with your application server's transaction manager, as 
+detailed in <a class="xref" href="ref_guide_enterprise_trans.html" title="2.&nbsp; Integrating with the Transaction Manager">Section&nbsp;2, &#8220;
+            Integrating with the Transaction Manager
+        &#8221;</a> above.
+					</p>
+				</li><li class="listitem">
+                    <p>
+Point OpenJPA at an enlisted <code class="classname">XADataSource</code>, and configure
+a second non-enlisted data source. See
+<a class="xref" href="ref_guide_dbsetup_thirdparty.html#ref_guide_dbsetup_thirdparty_enlist" title="2.1.&nbsp; Managed and XA DataSources">Section&nbsp;2.1, &#8220;
+                Managed and XA DataSources
+            &#8221;</a>.
+                    </p>
+                </li></ol></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_enterprise_trans.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_deploy.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_runtime.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.&nbsp;
+            Integrating with the Transaction Manager
+        &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;9.&nbsp;
+        Runtime Extensions
+    </td></tr></table></div></body></html>
\ No newline at end of file

Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_event.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_event.html (added)
+++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_event.html Fri Jan  6 19:19:20 2017
@@ -0,0 +1,256 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>2.&nbsp; Remote Event Notification Framework</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_remote.html" title="Chapter&nbsp;12.&nbsp; Remote and Offline Operation"><link rel="prev" href="ref_guide_remote.html" title="Chapter&nbsp;12.&nbsp; Remote and Offline Operation"><link rel="next" href="ref_guide_slice.html" title="Chapter&nbsp;13.&nbsp; Slice: Distributed Persistence"></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;
+            Remote Event Notification Framework
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_remote.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;12.&nbsp;
+        Remote and Offline Operation
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_slice.html">Next</a></td></tr></table><hr></div><div class="section" id="ref_guide_event"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.&nbsp;
+            Remote Event Notification Framework
+        </h2></div></div></div><div class="toc"><dl class="toc"><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></div>
+        
+        <a class="indexterm" name="d5e16716"></a>
+        <a class="indexterm" name="d5e16719"></a>
+        <p>
+        <a class="indexterm" name="d5e16724"></a>
+        <a class="indexterm" name="d5e16728"></a>
+The remote event notification framework allows a subset of the information
+available through OpenJPA's transaction events (see
+<a class="xref" href="ref_guide_runtime_pm_event.html" title="7.&nbsp; Transaction Events">Section&nbsp;7, &#8220;
+            Transaction Events
+        &#8221;</a>) to be broadcast to remote
+listeners. OpenJPA's <a class="link" href="ref_guide_caching.html#ref_guide_cache" title="1.&nbsp; Data Cache">data cache</a>, for
+example, uses remote events to remain synchronized when deployed in multiple
+JVMs.
+        </p>
+        <p>
+To enable remote events, you must configure the <code class="classname"> EntityManagerFactory
+</code> to use a <code class="literal">RemoteCommitProvider</code> (see below).
+        </p>
+        <p>
+When a <code class="literal">RemoteCommitProvider</code> is properly configured, you can
+register
+<a class="ulink" href="../javadoc/org/apache/openjpa/event/RemoteCommitListener.html" target="_top">
+<code class="classname">RemoteCommitListener</code></a>s that will be alerted with
+a list of modified object ids whenever a transaction on a remote machine
+successfully commits.
+        </p>
+        <div class="section" id="ref_guide_event_conf"><div class="titlepage"><div><div><h3 class="title">2.1.&nbsp;
+                Remote Commit Provider Configuration
+            </h3></div></div></div><div class="toc"><dl class="toc"><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></div>
+            
+            <a class="indexterm" name="d5e16743"></a>
+            <p>
+OpenJPA includes built in remote commit providers for JMS and TCP communication.
+            </p>
+            <div class="section" id="ref_guide_event_conf_jms"><div class="titlepage"><div><div><h4 class="title">2.1.1.&nbsp;
+                    JMS
+                </h4></div></div></div>
+                
+                <a class="indexterm" name="d5e16750"></a>
+                <p>
+The JMS remote commit provider can be configured by setting the
+<a class="link" href="ref_guide_conf_openjpa.html#openjpa.RemoteCommitProvider" title="5.61.&nbsp; openjpa.RemoteCommitProvider"><code class="literal">
+openjpa.RemoteCommitProvider</code></a> property to contain the
+appropriate configuration properties. The JMS provider understands the following
+properties:
+                </p>
+                <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+                        <p>
+<code class="literal">Topic</code>: The topic that the remote commit provider should
+publish notifications to and subscribe to for notifications sent from other
+JVMs. Defaults to <code class="literal">topic/OpenJPACommitProviderTopic</code>
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">TopicConnectionFactory</code>: The JNDI name of a <code class="classname">
+javax.jms.TopicConnectionFactory</code> factory to use for finding topics.
+Defaults to <code class="literal"> java:/ConnectionFactory</code>. This setting may vary
+depending on the application server in use; consult the application server's
+documentation for details of the default JNDI name for the <code class="classname">
+javax.jms.TopicConnectionFactory</code> instance. For example, under
+Weblogic, the JNDI name for the TopicConnectionFactory is <code class="literal">
+javax.jms.TopicConnectionFactory</code>.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">ExceptionReconnectAttempts</code>: The number of times to attempt
+to reconnect if the JMS system notifies OpenJPA of a serious connection error.
+Defaults to 0, meaning OpenJPA will log the error but otherwise ignore it,
+hoping the connection is still valid.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">*</code>: All other configuration properties will be interpreted as
+settings to pass to the JNDI <code class="classname">InitialContext</code> on
+construction. For example, you might set the <code class="literal">java.naming.provider.url
+</code> property to the URL of the context provider.
+                        </p>
+                    </li></ul></div>
+                <p>
+To configure a factory to use the JMS provider, your properties might look like
+the following:
+                </p>
+                <div class="example" id="ref_guide_event_conf_jmsex"><p class="title"><b>Example&nbsp;12.2.&nbsp;
+                        JMS Remote Commit Provider Configuration
+                    </b></p><div class="example-contents">
+                    
+<pre class="programlisting">
+&lt;property name="openjpa.RemoteCommitProvider"
+    value="jms(ExceptionReconnectAttempts=5)"/&gt;
+</pre>
+                </div></div><br class="example-break">
+                <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
+                    <p>
+Because of the nature of JMS, it is important that you invoke <code class="methodname">
+EntityManagerFactory.close</code> when finished with a factory. If you do
+not do so, a daemon thread will stay up in the JVM, preventing the JVM from
+exiting.
+                    </p>
+                </div>
+            </div>
+            <div class="section" id="ref_guide_event_conf_tcp"><div class="titlepage"><div><div><h4 class="title">2.1.2.&nbsp;
+                    TCP
+                </h4></div></div></div>
+                
+                <a class="indexterm" name="d5e16786"></a>
+                <p>
+The TCP remote commit provider has several options that are defined as host
+specifications containing a host name or IP address and an optional port
+separated by a colon. For example, the host specification <code class="literal">
+saturn.bea.com:1234</code> represents an <code class="classname">InetAddress</code>
+retrieved by invoking <code class="methodname">InetAddress.getByName("saturn.bea.com")
+</code> and a port of 1234.
+                </p>
+                <p>
+                <a class="indexterm" name="d5e16795"></a>
+The TCP provider can be configured by setting the <code class="literal">
+openjpa.RemoteCommitProvider</code> plugin property to contain the
+appropriate configuration settings. The TCP provider understands the following
+properties:
+                </p>
+                <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+                        <p>
+<code class="literal">Port</code>: The TCP port that the provider should listen on for
+commit notifications. Defaults to 5636.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">Addresses</code>: A semicolon-separated list of IP addresses to
+which notifications should be sent. No default value.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">NumBroadcastThreads</code>: The number of threads to create for the
+purpose of transmitting events to peers. You should increase this value as the
+number of concurrent transactions increases. The maximum number of concurrent
+transactions is a function of the size of the connection pool. See the
+<code class="literal">MaxActive</code> property of <code class="literal">
+openjpa.ConnectionFactoryProperties</code> in
+<a class="xref" href="ref_guide_dbsetup.html#ref_guide_dbsetup_builtin" title="1.&nbsp; Using the OpenJPA DataSource">Section&nbsp;1, &#8220;
+            Using the OpenJPA DataSource
+        &#8221;</a>. Setting a value of 0 will
+result in behavior where the thread invoking <code class="methodname">commit</code>
+will perform the broadcast directly. Defaults to 2.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">RecoveryTimeMillis</code>: Amount of time to wait in milliseconds
+before attempting to reconnect to a peer of the cluster when connectivity to the
+peer is lost. Defaults to 15000.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">MaxIdle</code>: The number of TCP sockets (channels) to keep open
+to each peer in the cluster for the transmission of events. Defaults to 2.
+                        </p>
+                    </li><li class="listitem">
+                        <p>
+<code class="literal">MaxActive</code>: The maximum allowed number of TCP sockets
+(channels) to open simultaneously between each peer in the cluster. Defaults to
+2.
+                        </p>
+                    </li></ul></div>
+                <p>
+To configure a factory to use the TCP provider, your properties might look like
+the following:
+                </p>
+                <div class="example" id="ref_guide_event_conf_tcpex"><p class="title"><b>Example&nbsp;12.3.&nbsp;
+                        TCP Remote Commit Provider Configuration
+                    </b></p><div class="example-contents">
+                    
+<pre class="programlisting">
+&lt;property name="openjpa.RemoteCommitProvider"
+    value="tcp(Addresses=10.0.1.10;10.0.1.11;10.0.1.12;10.0.1.13)"/&gt;
+</pre>
+                </div></div><br class="example-break">
+            </div>
+            <div class="section" id="ref_guide_event_conf_common"><div class="titlepage"><div><div><h4 class="title">2.1.3.&nbsp;
+                    Common Properties
+                </h4></div></div></div>
+                
+                <a class="indexterm" name="d5e16827"></a>
+                <p>
+In addition to the provider-specific configuration options above, all providers
+accept the following plugin properties:
+                </p>
+                <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+                        <p>
+<code class="literal">TransmitPersistedObjectIds</code>: Whether remote commit events
+will include the object ids of instances persisted in the transaction. By
+default only the class names of types persisted in the transaction are sent.
+This results in smaller events and more efficient network utilization. If you
+have registered your own remote commit listeners, however, you may require the
+persisted object ids as well.
+                        </p>
+                    </li></ul></div>
+                <p>
+To transmit persisted object ids in our remote commit events using the JMS
+provider, we modify the previous example as follows:
+                </p>
+                <div class="example" id="ref_guide_event_conf_jms2ex"><p class="title"><b>Example&nbsp;12.4.&nbsp;
+                        JMS Remote Commit Provider transmitting Persisted Object Ids
+                    </b></p><div class="example-contents">
+                    
+<pre class="programlisting">
+&lt;property name="openjpa.RemoteCommitProvider"
+    value="jms(ExceptionReconnectAttempts=5, TransmitPersistedObjectIds=true)"/&gt;
+</pre>
+                </div></div><br class="example-break">
+            </div>
+        </div>
+        <div class="section" id="ref_guide_event_customization"><div class="titlepage"><div><div><h3 class="title">2.2.&nbsp;
+                Customization
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e16842"></a>
+            <p>
+You can develop additional mechanisms for remote event notification be by
+creating an implementation of the
+<a class="ulink" href="../javadoc/org/apache/openjpa/event/RemoteCommitProvider.html" target="_top">
+<code class="classname"> RemoteCommitProvider</code></a> interface, possibly by
+extending the
+<a class="ulink" href="../javadoc/org/apache/openjpa/event/AbstractRemoteCommitProvider.html" target="_top">
+<code class="classname">AbstractRemoteCommitProvider</code></a> abstract class..
+            </p>
+        </div>
+    </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_remote.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_remote.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_slice.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;12.&nbsp;
+        Remote and Offline Operation
+    &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;13.&nbsp;
+    Slice: Distributed Persistence
+  </td></tr></table></div></body></html>
\ No newline at end of file

Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_fetch.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_fetch.html (added)
+++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_fetch.html Fri Jan  6 19:19:20 2017
@@ -0,0 +1,360 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>7.&nbsp; Fetch Groups</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_pc.html" title="Chapter&nbsp;5.&nbsp; Persistent Classes"><link rel="prev" href="ref_guide_pc_scos.html" title="6.&nbsp; Persistent Fields"><link rel="next" href="ref_guide_perfpack_eager.html" title="8.&nbsp; Eager Fetching"></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">7.&nbsp;
+            Fetch Groups
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_pc_scos.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_perfpack_eager.html">Next</a></td></tr></table><hr></div><div class="section" id="ref_guide_fetch"><div class="titlepage"><div><div><h2 class="title" style="clear: both">7.&nbsp;
+            Fetch Groups
+        </h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="ref_guide_fetch.html#ref_guide_fetch_custom">7.1. 
+                Custom Fetch Groups
+            </a></span></dt><dt><span class="section"><a href="ref_guide_fetch.html#ref_guide_fetch_conf">7.2. 
+                Custom Fetch Group Configuration
+            </a></span></dt><dt><span class="section"><a href="ref_guide_fetch.html#ref_guide_fetch_single_field">7.3. 
+                Per-field Fetch Configuration
+            </a></span></dt><dt><span class="section"><a href="ref_guide_fetch.html#ref_guide_fetch_impl">7.4. 
+                Implementation Notes
+            </a></span></dt></dl></div>
+        
+        <a class="indexterm" name="d5e12836"></a>
+        <p>
+Fetch groups are sets of fields that load together. They can be used to pool
+together associated fields in order to provide performance improvements over
+standard data fetching. Specifying fetch groups allows for tuning of lazy
+loading and eager fetching behavior.
+        </p>
+        <p>
+The JPA Overview's <a class="xref" href="jpa_overview_meta_field.html#jpa_overview_meta_fetch" title="2.7.1.&nbsp; Fetch Type">Section&nbsp;2.7.1, &#8220;
+                    Fetch Type
+                &#8221;</a> describes how
+to use JPA metadata annotations to control whether a field is fetched eagerly or
+lazily. Fetch groups add a dynamic aspect to this standard ability. As you will
+see, OpenJPA's JPA extensions allow you can add and remove fetch groups at
+runtime to vary the sets of fields that are eagerly loaded.
+        </p>
+        <div class="section" id="ref_guide_fetch_custom"><div class="titlepage"><div><div><h3 class="title">7.1.&nbsp;
+                Custom Fetch Groups
+            </h3></div></div></div>
+            
+            <p>
+OpenJPA places any field that is eagerly loaded according to the JPA metadata
+rules into the built-in <span class="emphasis"><em>default</em></span> fetch group. As its name
+implies, the default fetch group is active by default.  You may also
+define your own named fetch groups and activate or deactivate them at runtime,
+as described later in this chapter. OpenJPA will eagerly-load the fields in all
+active fetch groups when loading objects from the datastore.
+            </p>
+            <p>
+You create fetch groups with the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/FetchGroup.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.FetchGroup</code></a>
+annotation. If your class only has one custom fetch group, you can place this
+annotation directly on the class declaration. Otherwise, use the
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/FetchGroups.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.FetchGroups</code></a>
+annotation to declare an array of individual <code class="classname">FetchGroup</code>
+values. The <code class="classname">FetchGroup</code> annotation has the following
+properties:
+            </p>
+            <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+                    <p>
+<code class="literal">String name</code>: The name of the fetch group. Fetch group names
+are global, and are expected to be shared among classes. For example, a shopping
+website may use a <span class="emphasis"><em>detail</em></span> fetch group in each product class
+to efficiently load all the data needed to display a product's "detail" page.
+The website might also define a sparse <span class="emphasis"><em>list</em></span> fetch group
+containing only the fields needed to display a table of products, as in a search
+result.
+                    </p>
+                    <p>
+The following names are reserved for use by OpenJPA: <code class="literal">default</code>
+, <code class="literal">values</code>, <code class="literal">all</code>, <code class="literal">none</code>,
+and any name beginning with <code class="literal">jdo</code>, <code class="literal">jpa</code>, or
+<code class="literal">openjpa</code>.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">FetchAttribute[] attributes</code>: The set of persistent fields or
+properties in the fetch group.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">String[] fetchGroups</code>: Other fetch groups whose fields to
+include in this group.
+                    </p>
+                </li></ul></div>
+            <p>
+As you might expect, listing a
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/FetchAttribute.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.FetchAttribute</code></a>
+within a <code class="classname">FetchGroup</code> includes the corresponding persistent
+field or property in the fetch group. Each <code class="classname">FetchAttribute</code>
+has the following properties:
+            </p>
+            <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+                    <p>
+<code class="literal">String name</code>: The name of the persistent field or property to
+include in the fetch group.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+<code class="literal">recursionDepth</code>: If the attribute represents a relation, the
+maximum number of same-typed relations to eager-fetch from this field.  Defaults
+to 1.  For example, consider an <code class="classname">Employee</code> class with a
+<code class="literal">manager</code> field, also of type <code class="classname">Employee</code>.
+When we load an <code class="classname">Employee</code> and the <code class="literal">
+manager</code> field is in an active fetch group, the recursion depth (along
+with the max fetch depth setting, described below) determines whether we only
+retrieve the target <code class="classname">Employee</code> and his manager (depth 1),
+or whether we also retrieve the manager's manager (depth 2), or the manager's
+manager's manager (depth 3), etc.  Use -1 for unlimited depth.
+                    </p>
+                </li></ul></div>
+            <div class="example" id="ref_guide_fetch_customgroups"><p class="title"><b>Example&nbsp;5.19.&nbsp;
+                    Custom Fetch Group Metadata
+                </b></p><div class="example-contents">
+                
+                <p>
+Creates a <span class="emphasis"><em>detail</em></span> fetch group consisting of the
+<code class="literal">publisher</code> and <code class="literal">articles</code> relations.
+                </p>
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@FetchGroups({
+    @FetchGroup(name="detail", attributes={
+        @FetchAttribute(name="publisher"),
+        @FetchAttribute(name="articles")
+    }),
+    ...
+})
+public class Magazine {
+   ...
+}
+</pre>
+            </div></div><br class="example-break">
+            <p>
+A field can be a member of any number of fetch groups.  A field can also
+declare a <span class="emphasis"><em>load fetch group</em></span>.
+When you access a lazy-loaded field for the first time, OpenJPA makes a
+datastore trip to fetch that field's data.  Sometimes, however, you know
+that whenever you access a lazy field A, you're likely to access lazy fields B
+and C as well.  Therefore, it would be more efficient to fetch the data for A,
+B, and C in the same datastore trip.  By setting A's load fetch group to the
+name of a <a class="link" href="ref_guide_fetch.html" title="7.&nbsp; Fetch Groups">fetch group</a> containing B and
+C, you can tell OpenJPA to load all of these fields together when A is first
+accessed.
+            </p>
+            <p>
+Use OpenJPA's
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/LoadFetchGroup.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.LoadFetchGroup</code></a>
+annotation to specify the load fetch group of any persistent field. The value of
+the annotation is the name of a declared fetch group whose members should be
+loaded along with the annotated field.
+            </p>
+            <div class="example" id="ref_guide_fetch_loadgroup"><p class="title"><b>Example&nbsp;5.20.&nbsp;
+                    Load Fetch Group Metadata
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@FetchGroups({
+    @FetchGroup(name="detail", attributes={
+        @FetchAttribute(name="publisher"),
+        @FetchAttribute(name="articles")
+    }),
+    ...
+})
+public class Magazine {
+
+   @ManyToOne(fetch=FetchType.LAZY)
+   @LoadFetchGroup("detail")
+   private Publisher publisher;
+
+   ...
+}
+</pre>
+            </div></div><br class="example-break">
+        </div>
+        <div class="section" id="ref_guide_fetch_conf"><div class="titlepage"><div><div><h3 class="title">7.2.&nbsp;
+                Custom Fetch Group Configuration
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12908"></a>
+            <p>
+            <a class="indexterm" name="d5e12912"></a>
+You can control the default set of fetch groups with the
+<a class="link" href="ref_guide_conf_openjpa.html#openjpa.FetchGroups" title="5.35.&nbsp; openjpa.FetchGroups"><code class="literal">openjpa.FetchGroups</code>
+</a> configuration property. Set this property to a comma-separated list of
+fetch group names.
+            </p>
+            <p>
+You can also set the system's default maximum fetch depth with the
+<a class="link" href="ref_guide_conf_openjpa.html#openjpa.MaxFetchDepth" title="5.47.&nbsp; openjpa.MaxFetchDepth"><code class="literal">openjpa.MaxFetchDepth</code>
+</a> configuration property.  The maximum fetch depth determines how "deep"
+into the object graph to traverse when loading an instance.  For example, with
+a <code class="literal">MaxFetchDepth</code> of 1, OpenJPA will load at most the target 
+instance and its immediate relations.  With a <code class="literal">MaxFetchDepth</code>
+of 2, OpenJPA may load the target instance, its immediate relations, and
+the relations of those relations.  This works to arbitrary depth.  In fact,
+the default <code class="literal">MaxFetchDepth</code> value is -1, which symbolizes 
+infinite depth.  Under this setting, OpenJPA will fetch configured relations 
+until it reaches the edges of the object graph.  Of course, which relation 
+fields are loaded depends on whether the fields are eager or lazy, and on the 
+active fetch groups.  A fetch group member's recursion depth may also limit 
+the fetch depth to something less than the configured maximum.
+            </p>
+            <p>
+OpenJPA's <code class="classname">OpenJPAEntityManager</code> and <code class="classname">
+OpenJPAQuery</code> extensions to the standard <code class="classname">EntityManager
+</code> and <code class="classname">Query</code> interfaces provide access to a
+<a class="ulink" href="../javadoc/org/apache/openjpa/persistence/FetchPlan.html" target="_top">
+<code class="classname">org.apache.openjpa.persistence.FetchPlan</code></a> object.
+The <code class="classname">FetchPlan</code> maintains the set of active fetch groups 
+and the maximum fetch depth. It begins with the groups and depth defined in the
+<code class="literal">openjpa.FetchGroups</code> and <code class="literal">openjpa.MaxFetchDepth
+</code> properties, but allows you to add or remove groups and change the
+maximum fetch depth for an individual <code class="classname">EntityManager</code> or
+<code class="classname">Query</code> through the methods below.
+            </p>
+<pre class="programlisting">
+public FetchPlan addFetchGroup(String group);
+public FetchPlan addFetchGroups(String... groups);
+public FetchPlan addFetchGroups(Collection groups);
+public FetchPlan removeFetchGrop(String group);
+public FetchPlan removeFetchGroups(String... groups);
+public FetchPlan removeFetchGroups(Collection groups);
+public FetchPlan resetFetchGroups();
+public Collection&lt;String&gt; getFetchGroups();
+public void clearFetchGroups();
+public FetchPlan setMaxFetchDepth(int depth);
+public int getMaxFetchDepth();
+</pre>
+            <p>
+<a class="xref" href="ref_guide_runtime.html" title="Chapter&nbsp;9.&nbsp; Runtime Extensions">Chapter&nbsp;9, <i>
+        Runtime Extensions
+    </i></a> details the <code class="classname">
+OpenJPAEntityManager</code>, <code class="classname">OpenJPAQuery</code>, and
+<code class="classname">FetchPlan</code> interfaces.
+            </p>
+            <div class="example" id="ref_guide_fetch_conf_query"><p class="title"><b>Example&nbsp;5.21.&nbsp;
+                    Using the FetchPlan
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAQuery kq = OpenJPAPersistence.cast(em.createQuery(...));
+kq.getFetchPlan().setMaxFetchDepth(3).addFetchGroup("detail");
+List results = kq.getResultList();
+</pre>
+            </div></div><br class="example-break">
+        </div>
+        <div class="section" id="ref_guide_fetch_single_field"><div class="titlepage"><div><div><h3 class="title">7.3.&nbsp;
+                Per-field Fetch Configuration
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12946"></a>
+            <p>
+In addition to controlling fetch configuration on a per-fetch-group basis, you
+can configure OpenJPA to include particular fields in the current fetch
+plan. This allows you to add individual fields that are not in the
+default fetch group or in any other active fetch groups to the set of
+fields that will be eagerly loaded from the database.
+            </p>
+            <p>
+OpenJPA <code class="classname">FetchPlan</code> methods:
+            </p>
+<pre class="programlisting">
+public FetchPlan addField(String field);
+public FetchPlan addFields(String... fields);
+public FetchPlan addFields(Class cls, String... fields);
+public FetchPlan addFields(Collection fields);
+public FetchPlan addFields(Class cls, Collection fields);
+public FetchPlan removeField(String field);
+public FetchPlan removeFields(String... fields);
+public FetchPlan removeFields(Class cls, String... fields);
+public FetchPlan removeFields(Collection fields);
+public FetchPlan removeFields(Class cls, Collection fields);
+public Collection&lt;String&gt; getFields();
+public void clearFields();
+</pre>
+            <p>
+The methods that take only string arguments use the fully-qualified field name,
+such as <code class="literal">org.mag.Magazine.publisher</code>. Similarly, <code class="methodname">
+getFields</code> returns the set of fully-qualified field names. In all
+methods, the named field must be defined in the class specified in the
+invocation, not a superclass. So, if the field <code class="literal">publisher</code> is
+defined in base class <code class="classname">Publication</code> rather than subclass
+<code class="classname">Magazine</code>, you must invoke <code class="literal">addField
+(Publication.class, "publisher")</code> and not <code class="literal">addField
+(Magazine.class, "publisher")</code>. This is stricter than Java's default
+field-masking algorithms, which would allow the latter method behavior if
+<code class="literal">Magazine</code> did not also define a field called <code class="literal">
+publisher</code>.
+            </p>
+            
+            <p>
+To include the fields defined in a super class by the subclass or to distinguish
+between fields that are defined in <span class="emphasis"><em>both</em></span> super- and subclass,
+set <code class="literal">setExtendedPathLookup(boolean)</code> on <code class="literal">FetchPlan
+</code> to <code class="literal">true</code>. By default, this option is set to
+<code class="literal">false</code>, to reduce more extensive lookups for predominant use 
+cases.           
+            </p>
+            
+            <p>
+In order to avoid the cost of reflection, OpenJPA does not perform any
+validation of the field name / class name pairs that you put into the fetch
+configuration. If you specify non-existent class / field pairs, nothing adverse
+will happen, but you will receive no notification of the fact that the specified
+configuration is not being used.
+            </p>         
+            <div class="example" id="ref_guide_fetch-conf_per_field"><p class="title"><b>Example&nbsp;5.22.&nbsp;
+                    Adding an Eager Field
+                </b></p><div class="example-contents">
+                
+<pre class="programlisting">
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager kem = OpenJPAPersistence.cast(em);
+kem.getFetchPlan().addField(Magazine.class, "publisher");
+Magazine mag = em.find(Magazine.class, magId);
+</pre>
+            </div></div><br class="example-break">
+        </div>
+        <div class="section" id="ref_guide_fetch_impl"><div class="titlepage"><div><div><h3 class="title">7.4.&nbsp;
+                Implementation Notes
+            </h3></div></div></div>
+            
+            <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
+                    <p>
+Even when a direct relation is not eagerly fetched, OpenJPA selects the foreign
+key columns and caches the values. This way when you do traverse the relation,
+OpenJPA can often find the related object in its cache, or at least avoid joins
+when loading the related object from the database.
+                    </p>
+                </li><li class="listitem">
+                    <p>
+The above implicit foreign key-selecting behavior does not always apply when the
+relation is in a subclass table. If the subclass table would not otherwise be
+joined into the select, OpenJPA avoids the extra join just to select the foreign
+key values.
+                    </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_pc_scos.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_perfpack_eager.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6.&nbsp;
+            Persistent Fields
+        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;8.&nbsp;
+            Eager Fetching
+        </td></tr></table></div></body></html>
\ No newline at end of file

Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_instrumentation.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_instrumentation.html (added)
+++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_instrumentation.html Fri Jan  6 19:19:20 2017
@@ -0,0 +1,88 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>Chapter&nbsp;16.&nbsp; Instrumentation</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide.html" title="Part&nbsp;3.&nbsp;Reference Guide"><link rel="prev" href="ref_guide_optimization.html" title="Chapter&nbsp;15.&nbsp; Optimization Guidelines"><link rel="next" href="ref_guide_instrumentation_custom.html" title="2.&nbsp; Custom Providers and Instruments"></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;16.&nbsp;
+        Instrumentation
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_optimization.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_instrumentation_custom.html">Next</a></td></tr></table><hr></div><div class="chapter" id="ref_guide_instrumentation"><div class="titlepage"><div><div><h2 class="title">Chapter&nbsp;16.&nbsp;
+        Instrumentation
+    </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="ref_guide_instrumentation.html#ref_guide_instrumentation_config">1. 
+            Configuration
+        </a></span></dt><dd><dl><dt><span class="section"><a href="ref_guide_instrumentation.html#ref_guide_instrumentation_config_jmx">1.1. 
+                JMX Platform MBean Enablement
+            </a></span></dt></dl></dd><dt><span class="section"><a href="ref_guide_instrumentation_custom.html">2. 
+            Custom Providers and Instruments
+        </a></span></dt></dl></div>
+    
+        <a class="indexterm" name="d5e17544"></a>
+    <p>
+	OpenJPA provides the ability to instrument various aspects of runtime 
+    operation.  Instrumentation involves an instrumentation provider for base instrumentation
+    capabilities and instruments for instrumenting various aspects of OpenJPA.  OpenJPA
+    includes a default instrumentation provider for JMX Platform MBeans.  MBean-based instruments
+    are provided for the data cache, query cache, and query SQL cache.  When enabled,
+    JMX-based remote monitoring tools such as 
+    <a class="ulink" href="http://download.oracle.com/javase/6/docs/technotes/tools/share/jconsole.html" target="_top"> 
+    <code class="classname">JConsole</code></a> can be used to monitor various
+    metrics tracked by OpenJPA's caches by accessing MBeans registered under domain 
+    <code class="classname">org.apache.openjpa</code>.  Additionally, custom applications can gather metrics by using the 
+    JMX API to query OpenJPA's MBeans.  The <code class="classname">openjpa-integration-jmx</code> 
+    integration module contains an example of how to access the cache MBeans within program code.
+    </p>
+    <div class="section" id="ref_guide_instrumentation_config"><div class="titlepage"><div><div><h2 class="title" style="clear: both">1.&nbsp;
+            Configuration
+        </h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="ref_guide_instrumentation.html#ref_guide_instrumentation_config_jmx">1.1. 
+                JMX Platform MBean Enablement
+            </a></span></dt></dl></div>
+        
+        <a class="indexterm" name="d5e17553"></a>
+        <p>
+        Instrumentation is enabled using the <a class="link" href="ref_guide_conf_openjpa.html#openjpa.Instrumentation" title="5.40.&nbsp; openjpa.Instrumentation"><code class="literal">openjpa.Instrumentation</code> </a>
+        configuration property.  The base value is the instrumentation provider.  The
+        alias "jmx" enables the JMX Platform MBean provider.  Instruments are specified 
+        on the <code class="literal">Instrument</code> attribute of the provider.  Multiple instruments can be specified
+        by enclosing the value in single quotes and specifying each instrument or instrument
+        alias as a comma separated list.  For example:
+        </p>
+        <pre class="programlisting">
+            &lt;!--  Enable caches and cache statistics --&gt;
+            &lt;property name="openjpa.DataCache" value="true(EnableStatistics=true)"/&gt;
+            &lt;property name="openjpa.QueryCache" value="true(EnableStatistics=true)"/&gt;
+            &lt;property name="openjpa.jdbc.QuerySQLCache" value="true(EnableStatistics=true)"/&gt;
+
+            &lt;!--  Enable jmx provider and instruments for Data, Query, and QuerySQL caches --&gt;
+            &lt;property name="openjpa.Instrumentation" value="jmx(Instrument='DataCache,QueryCache,QuerySQLCache')"/&gt;
+        </pre>
+        <div class="section" id="ref_guide_instrumentation_config_jmx"><div class="titlepage"><div><div><h3 class="title">1.1.&nbsp;
+                JMX Platform MBean Enablement
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e17562"></a>
+            <p>
+            The built-in JMX Platform MBean provider can be used to monitor OpenJPA
+            runtime information out-of-band.  This provider is based upon the Platform MBean support included
+            in the JDK.  The JDK provides options for enabling secure connectivity and authentication.
+            These options require additional configuration options and may require encryption
+            keys to be installed on the local and remote systems.  To enable simple, non-secure, non-authenticated
+            monitoring of your application, specify the -Dcom.sun.management.jmxremote.authenticate=false and 
+            -Dcom.sun.management.jmxremote.ssl=false directives on the java command line invocation.  To enable
+            remote instrumentation on a specific port, specify which port to use on the directive 
+            -Dcom.sun.management.jmxremote.port=&lt;port&gt;.
+            For example:
+            </p><pre class="programlisting">
+            java -cp openjpa-all-2.2.0.jar:myApplication.jar -Dcom.sun.management.jmxremote.authenticate=false
+            -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.port=8888 com.my.app.Main
+            </pre><p>
+            </p>
+            <p>
+            Additional information regarding the use and configuration of JMX Platform MBeans
+            can be found in the 
+            <a class="ulink" href="http://download.oracle.com/javase/6/docs/technotes/guides/jmx/overview/JMXoverviewTOC.html" target="_top">
+            <code class="literal">Java Management Extensions (JMX) Technology Overview</code></a>.
+            </p>
+        </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_optimization.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_instrumentation_custom.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;15.&nbsp;
+        Optimization Guidelines
+    &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;
+            Custom Providers and Instruments
+        </td></tr></table></div></body></html>
\ No newline at end of file

Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_instrumentation_custom.html
==============================================================================
--- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_instrumentation_custom.html (added)
+++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_instrumentation_custom.html Fri Jan  6 19:19:20 2017
@@ -0,0 +1,53 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>2.&nbsp; Custom Providers and Instruments</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_instrumentation.html" title="Chapter&nbsp;16.&nbsp; Instrumentation"><link rel="prev" href="ref_guide_instrumentation.html" title="Chapter&nbsp;16.&nbsp; Instrumentation"><link rel="next" href="appendices.html" title="Part&nbsp;4.&nbsp;Appendices"></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;
+            Custom Providers and Instruments
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_instrumentation.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;16.&nbsp;
+        Instrumentation
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="appendices.html">Next</a></td></tr></table><hr></div><div class="section" id="ref_guide_instrumentation_custom"><div class="titlepage"><div><div><h2 class="title" style="clear: both">2.&nbsp;
+            Custom Providers and Instruments
+        </h2></div></div></div>
+        
+        <a class="indexterm" name="d5e17572"></a>
+        <p>
+        OpenJPA includes built-in support for a JMX Platform MBean provider, but a custom instrumentation
+        providers can be created by implementing the 
+        <a class="ulink" href="../javadoc/org/apache/openjpa/lib/instrumentation/InstrumentationProvider.html" target="_top">
+        <code class="classname">InstrumentationProvider</code></a> interface or more simply by extending
+        <a class="ulink" href="../javadoc/org/apache/openjpa/lib/instrumentation/AbstractInstrumentationProvider.html" target="_top">
+        <code class="classname">AbstractInstrumentationProvider</code></a>.  To use the custom instrumentation provider,
+        include the class in your classpath and specify the class name as the base value on the 
+        <a class="link" href="ref_guide_conf_openjpa.html#openjpa.Instrumentation" title="5.40.&nbsp; openjpa.Instrumentation"><code class="literal">openjpa.Instrumentation</code></a> configuration property.
+        </p>
+        <p>
+        OpenJPA includes instruments for various caches, but you can also create your own instruments.  To
+        create a custom instrument you need to implement the
+        <a class="ulink" href="../javadoc/org/apache/openjpa/lib/instrumentation/Instrument.html" target="_top">
+        <code class="classname">Instrument</code></a> interface or more simply extend
+        <a class="ulink" href="../javadoc/org/apache/openjpa/lib/instrumentation/AbstractInstrument.html" target="_top">
+        <code class="classname">AbstractInstrument</code></a>.  If you are building a Platform MBean JMX-based
+        instrument this effort can be simplified by extending
+        <a class="ulink" href="../javadoc/org/apache/openjpa/instrumentation/jmx/JMXInstrument.html" target="_top">
+        <code class="classname">JMXInstrument</code></a>.  If you create your own custom
+        provider, class name aliases can be registered within the provider to simplify configuration.  For example,
+        the instrument <code class="classname">com.my.app.MySQLInstrument</code> could be aliased as 
+        <code class="classname">MySQLInstrument</code> within custom provider 
+        <code class="classname">com.my.app.InstrumentationProvider</code>.
+        </p>
+        <p>
+        OpenJPA provides the ability to plug in custom instruments and gives instruments direct access to the 
+        configuration, but it is up to the creator of the instrument to add the internal monitoring.  This often
+        requires modifying or extending base OpenJPA classes (such as the Broker) or using a byte-code weaving 
+        tool such as AspectJ to produce aspect-based instruments.
+        </p>
+        <p>
+        Here is an example of how a custom instrumentation provider could be enabled with an instrument class
+        aliased by the provider as <code class="classname">MySQLInstrument</code>.
+        </p>
+        <pre class="programlisting">
+            &lt;!--  Enable custom provider and instrument --&gt;
+            &lt;property name="openjpa.Instrumentation" value="com.my.app.InstrumentationProvider(Instrument='MySQLInstrument')"/&gt;
+        </pre>
+    </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_instrumentation.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_instrumentation.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="appendices.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;16.&nbsp;
+        Instrumentation
+    &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Part&nbsp;4.&nbsp;Appendices</td></tr></table></div></body></html>
\ No newline at end of file



Mime
View raw message