You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by kw...@apache.org on 2014/05/15 00:22:26 UTC
svn commit: r908837 [27/37] -
/websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_methodql.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_methodql.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_methodql.html Wed May 14 22:22:23 2014
@@ -0,0 +1,80 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>5. MethodQL</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide_runtime.html" title="Chapter 9. Runtime Extensions"><link rel="prev" href="ref_guide_savepoints.html" title="4. Savepoints"><link rel="next" href="ref_guide_sequence.html" title="6. 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.
+ MethodQL
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_savepoints.html">Prev</a> </td><th width="60%" align="center">Chapter 9.
+ Runtime Extensions
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_sequence.html">Next</a></td></tr></table><hr></div><div class="section" title="5. MethodQL"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_enterprise_methodql">5.
+ MethodQL
+ </h2></div></div></div>
+
+ <a class="indexterm" name="d5e15655"></a>
+ <a class="indexterm" name="d5e15657"></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> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_runtime.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_sequence.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.
+ Savepoints
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 6.
+ Generators
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_methodql.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_trans.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_trans.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_trans.html Wed May 14 22:22:23 2014
@@ -0,0 +1,110 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>2. 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-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide_deploy.html" title="Chapter 8. Deployment"><link rel="prev" href="ref_guide_deploy.html" title="Chapter 8. Deployment"><link rel="next" href="ref_guide_enterprise_xa.html" title="3. 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.
+ Integrating with the Transaction Manager
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_deploy.html">Prev</a> </td><th width="60%" align="center">Chapter 8.
+ Deployment
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_enterprise_xa.html">Next</a></td></tr></table><hr></div><div class="section" title="2. Integrating with the Transaction Manager"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_enterprise_trans">2.
+ Integrating with the Transaction Manager
+ </h2></div></div></div>
+
+ <a class="indexterm" name="d5e15101"></a>
+ <a class="indexterm" name="d5e15104"></a>
+ <a class="indexterm" name="d5e15107"></a>
+ <a class="indexterm" name="d5e15110"></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. openjpa.TransactionMode"><code class="literal">openjpa.TransactionMode
+</code></a> configuration property. This property accepts the following
+modes:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist" 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" title="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="d5e15140"></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. 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" 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"><a name="ref_guide_enterprise_transex"></a><p class="title"><b>Example 8.1. Configuring Transaction Manager Integration</b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.TransactionMode" value="managed"/>
+<property name="openjpa.ManagedRuntime" value="jndi(TransactionManagerName=java:/TransactionManager)"/>
+</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> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_deploy.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_enterprise_xa.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 8.
+ Deployment
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 3.
+ XA Transactions
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_trans.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_xa.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_xa.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_xa.html Wed May 14 22:22:23 2014
@@ -0,0 +1,92 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>3. XA Transactions</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide_deploy.html" title="Chapter 8. Deployment"><link rel="prev" href="ref_guide_enterprise_trans.html" title="2. Integrating with the Transaction Manager"><link rel="next" href="ref_guide_runtime.html" title="Chapter 9. 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.
+ XA Transactions
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_enterprise_trans.html">Prev</a> </td><th width="60%" align="center">Chapter 8.
+ Deployment
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_runtime.html">Next</a></td></tr></table><hr></div><div class="section" title="3. XA Transactions"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_enterprise_xa">3.
+ XA Transactions
+ </h2></div></div></div><div class="toc"><dl><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="d5e15169"></a>
+ <a class="indexterm" name="d5e15172"></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" 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" title="3.1. Using OpenJPA with XA Transactions"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_enterprise_xa_req">3.1.
+ 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" 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. Integrating with the Transaction Manager">Section 2, “
+ Integrating with the Transaction Manager
+ ”</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. Managed and XA DataSources">Section 2.1, “
+ Managed and XA DataSources
+ ”</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> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_deploy.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_runtime.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.
+ Integrating with the Transaction Manager
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 9.
+ Runtime Extensions
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_enterprise_xa.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_event.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_event.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_event.html Wed May 14 22:22:23 2014
@@ -0,0 +1,256 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>2. Remote Event Notification Framework</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide_remote.html" title="Chapter 12. Remote and Offline Operation"><link rel="prev" href="ref_guide_remote.html" title="Chapter 12. Remote and Offline Operation"><link rel="next" href="ref_guide_slice.html" title="Chapter 13. 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.
+ Remote Event Notification Framework
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_remote.html">Prev</a> </td><th width="60%" align="center">Chapter 12.
+ Remote and Offline Operation
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_slice.html">Next</a></td></tr></table><hr></div><div class="section" title="2. Remote Event Notification Framework"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_event">2.
+ Remote Event Notification Framework
+ </h2></div></div></div><div class="toc"><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></div>
+
+ <a class="indexterm" name="d5e16608"></a>
+ <a class="indexterm" name="d5e16611"></a>
+ <p>
+ <a class="indexterm" name="d5e16616"></a>
+ <a class="indexterm" name="d5e16620"></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. Transaction Events">Section 7, “
+ Transaction Events
+ ”</a>) to be broadcast to remote
+listeners. OpenJPA's <a class="link" href="ref_guide_caching.html#ref_guide_cache" title="1. 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" title="2.1. Remote Commit Provider Configuration"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_event_conf">2.1.
+ Remote Commit Provider Configuration
+ </h3></div></div></div><div class="toc"><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></div>
+
+ <a class="indexterm" name="d5e16635"></a>
+ <p>
+OpenJPA includes built in remote commit providers for JMS and TCP communication.
+ </p>
+ <div class="section" title="2.1.1. JMS"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_event_conf_jms">2.1.1.
+ JMS
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e16642"></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. 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" 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"><a name="ref_guide_event_conf_jmsex"></a><p class="title"><b>Example 12.2.
+ JMS Remote Commit Provider Configuration
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.RemoteCommitProvider"
+ value="jms(ExceptionReconnectAttempts=5)"/>
+</pre>
+ </div></div><br class="example-break">
+ <div class="note" title="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" title="2.1.2. TCP"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_event_conf_tcp">2.1.2.
+ TCP
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e16678"></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="d5e16687"></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" 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. Using the OpenJPA DataSource">Section 1, “
+ Using the OpenJPA DataSource
+ ”</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"><a name="ref_guide_event_conf_tcpex"></a><p class="title"><b>Example 12.3.
+ TCP Remote Commit Provider Configuration
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.RemoteCommitProvider"
+ value="tcp(Addresses=10.0.1.10;10.0.1.11;10.0.1.12;10.0.1.13)"/>
+</pre>
+ </div></div><br class="example-break">
+ </div>
+ <div class="section" title="2.1.3. Common Properties"><div class="titlepage"><div><div><h4 class="title" id="ref_guide_event_conf_common">2.1.3.
+ Common Properties
+ </h4></div></div></div>
+
+ <a class="indexterm" name="d5e16719"></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" 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"><a name="ref_guide_event_conf_jms2ex"></a><p class="title"><b>Example 12.4.
+ JMS Remote Commit Provider transmitting Persisted Object Ids
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.RemoteCommitProvider"
+ value="jms(ExceptionReconnectAttempts=5, TransmitPersistedObjectIds=true)"/>
+</pre>
+ </div></div><br class="example-break">
+ </div>
+ </div>
+ <div class="section" title="2.2. Customization"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_event_customization">2.2.
+ Customization
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e16734"></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> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_remote.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_slice.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 12.
+ Remote and Offline Operation
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 13.
+ Slice: Distributed Persistence
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_event.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_fetch.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_fetch.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_fetch.html Wed May 14 22:22:23 2014
@@ -0,0 +1,360 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>7. Fetch Groups</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide_pc.html" title="Chapter 5. Persistent Classes"><link rel="prev" href="ref_guide_pc_scos.html" title="6. Persistent Fields"><link rel="next" href="ref_guide_perfpack_eager.html" title="8. 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.
+ Fetch Groups
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_pc_scos.html">Prev</a> </td><th width="60%" align="center">Chapter 5.
+ Persistent Classes
+ </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_perfpack_eager.html">Next</a></td></tr></table><hr></div><div class="section" title="7. Fetch Groups"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_fetch">7.
+ Fetch Groups
+ </h2></div></div></div><div class="toc"><dl><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="d5e12728"></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. Fetch Type">Section 2.7.1, “
+ Fetch Type
+ ”</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" title="7.1. Custom Fetch Groups"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_fetch_custom">7.1.
+ 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" 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" 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"><a name="ref_guide_fetch_customgroups"></a><p class="title"><b>Example 5.19.
+ 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. 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"><a name="ref_guide_fetch_loadgroup"></a><p class="title"><b>Example 5.20.
+ 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" title="7.2. Custom Fetch Group Configuration"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_fetch_conf">7.2.
+ Custom Fetch Group Configuration
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e12800"></a>
+ <p>
+ <a class="indexterm" name="d5e12804"></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. 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. 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<String> getFetchGroups();
+public void clearFetchGroups();
+public FetchPlan setMaxFetchDepth(int depth);
+public int getMaxFetchDepth();
+</pre>
+ <p>
+<a class="xref" href="ref_guide_runtime.html" title="Chapter 9. Runtime Extensions">Chapter 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"><a name="ref_guide_fetch_conf_query"></a><p class="title"><b>Example 5.21.
+ 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" title="7.3. Per-field Fetch Configuration"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_fetch_single_field">7.3.
+ Per-field Fetch Configuration
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e12838"></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<String> 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"><a name="ref_guide_fetch-conf_per_field"></a><p class="title"><b>Example 5.22.
+ 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" title="7.4. Implementation Notes"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_fetch_impl">7.4.
+ Implementation Notes
+ </h3></div></div></div>
+
+ <div class="itemizedlist"><ul class="itemizedlist" 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> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_pc.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_perfpack_eager.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6.
+ Persistent Fields
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 8.
+ Eager Fetching
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_fetch.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_instrumentation.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_instrumentation.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_instrumentation.html Wed May 14 22:22:23 2014
@@ -0,0 +1,88 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>Chapter 16. Instrumentation</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide.html" title="Part 3. Reference Guide"><link rel="prev" href="ref_guide_optimization.html" title="Chapter 15. Optimization Guidelines"><link rel="next" href="ref_guide_instrumentation_custom.html" title="2. 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 16.
+ Instrumentation
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_optimization.html">Prev</a> </td><th width="60%" align="center">Part 3. Reference Guide</th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_instrumentation_custom.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 16. Instrumentation" id="ref_guide_instrumentation"><div class="titlepage"><div><div><h2 class="title">Chapter 16.
+ Instrumentation
+ </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><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="d5e17436"></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" title="1. Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_instrumentation_config">1.
+ Configuration
+ </h2></div></div></div><div class="toc"><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></div>
+
+ <a class="indexterm" name="d5e17445"></a>
+ <p>
+ Instrumentation is enabled using the <a class="link" href="ref_guide_conf_openjpa.html#openjpa.Instrumentation" title="5.40. 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">
+ <!-- Enable caches and cache statistics -->
+ <property name="openjpa.DataCache" value="true(EnableStatistics=true)"/>
+ <property name="openjpa.QueryCache" value="true(EnableStatistics=true)"/>
+ <property name="openjpa.jdbc.QuerySQLCache" value="true(EnableStatistics=true)"/>
+
+ <!-- Enable jmx provider and instruments for Data, Query, and QuerySQL caches -->
+ <property name="openjpa.Instrumentation" value="jmx(Instrument='DataCache,QueryCache,QuerySQLCache')"/>
+ </pre>
+ <div class="section" title="1.1. JMX Platform MBean Enablement"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_instrumentation_config_jmx">1.1.
+ JMX Platform MBean Enablement
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e17454"></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=<port>.
+ 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> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_instrumentation_custom.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 15.
+ Optimization Guidelines
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> 2.
+ Custom Providers and Instruments
+ </td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_instrumentation.html
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_instrumentation_custom.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_instrumentation_custom.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_instrumentation_custom.html Wed May 14 22:22:23 2014
@@ -0,0 +1,53 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>2. Custom Providers and Instruments</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide_instrumentation.html" title="Chapter 16. Instrumentation"><link rel="prev" href="ref_guide_instrumentation.html" title="Chapter 16. Instrumentation"><link rel="next" href="appendices.html" title="Part 4. 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.
+ Custom Providers and Instruments
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_instrumentation.html">Prev</a> </td><th width="60%" align="center">Chapter 16.
+ Instrumentation
+ </th><td width="20%" align="right"> <a accesskey="n" href="appendices.html">Next</a></td></tr></table><hr></div><div class="section" title="2. Custom Providers and Instruments"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_instrumentation_custom">2.
+ Custom Providers and Instruments
+ </h2></div></div></div>
+
+ <a class="indexterm" name="d5e17464"></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. 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">
+ <!-- Enable custom provider and instrument -->
+ <property name="openjpa.Instrumentation" value="com.my.app.InstrumentationProvider(Instrument='MySQLInstrument')"/>
+ </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> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_instrumentation.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="appendices.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 16.
+ Instrumentation
+ </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> Part 4. Appendices</td></tr></table></div></body></html>
\ No newline at end of file
Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_instrumentation_custom.html
------------------------------------------------------------------------------
svn:mime-type = text/plain