openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mprud...@apache.org
Subject svn commit: r433761 [16/18] - in /incubator/openjpa/trunk/openjpa-project: ./ src/doc/manual/
Date Tue, 22 Aug 2006 21:28:55 GMT
Added: incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml?rev=433761&view=auto
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml (added)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/ref_guide_remote.xml Tue Aug 22
14:28:53 2006
@@ -0,0 +1,604 @@
+
+    <chapter id="ref_guide_remote">
+      <title>Remote and Offline Operation</title>
+      <indexterm zone="ref_guide_remote">
+        <primary>remote</primary>
+      </indexterm>
+      <indexterm>
+        <primary>offline</primary>
+        <see>remote</see>
+      </indexterm>
+      <para>
+  The standard JPA runtime environment is 
+  <emphasis>local</emphasis> and <emphasis>online</emphasis>.  It
is 
+  <emphasis>local</emphasis> in that components such as 
+  <classname>EntityManager</classname>s and queries connect directly to
+  the datastore and execute their actions in the same JVM as the code using 
+  them.  It is <emphasis>online</emphasis> in that all changes to managed 
+  objects must be made in the context of an active <classname>
+  EntityManager</classname>.  
+  These two properties, combined with the fact that <classname>
+  EntityManager</classname>s cannot be serialized for storage or network 
+  transfer, make the standard JPA runtime difficult to 
+  incorporate into some enterprise and client/server program designs.
+  </para>
+      <para>
+  OpenJPA extends the standard runtime to add <emphasis>remote</emphasis>
+  and <emphasis>offline</emphasis> capabilities in the form of enhanced
+  <link linkend="ref_guide_detach">Detach and Attach APIs</link> and
+  <link linkend="ref_guide_event">Remote Commit Events</link>.
+  The following sections explain these capabilities in detail.
+  </para>
+      <section id="ref_guide_detach">
+        <title>Detach and Attach</title>
+        <indexterm zone="ref_guide_detach">
+          <primary>detachment</primary>
+        </indexterm>
+        <indexterm>
+          <primary>attachment</primary>
+          <see>detachment</see>
+        </indexterm>
+<!-- ### EJBDOC : more specific links to EM detach discussion -->
+        <para>
+    The JPA Overview describes the specification's standard 
+    detach and attach APIs in <xref linkend="jpa_overview_em"/>.  
+    This section enumerates OpenJPA's enhancements to the standard behavior.
+    </para>
+        <section id="ref_guide_detach_behavior">
+          <title>Detach Behavior</title>
+          <indexterm zone="ref_guide_detach_behavior">
+            <primary>detachment</primary>
+            <secondary>behavior</secondary>
+          </indexterm>
+          <para>
+      In JPA, objects detach automatically when they are
+      serialized or when a <link linkend="jpa_overview_emfactory_perscontext">persistence

+      context</link> ends.  The specification does not define any way to
+      explicitly detach objects.  The extended 
+      <ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><classname>OpenJPAEntityManager</classname></ulink>,
however, allows 
+      you to explicitly detach objects at any time.
+      </para>
+          <programlisting format="linespecific">
+public Object detach (Object pc):
+public Object[] detachAll (Object... pcs):
+public Collection detachAll (Collection pcs):
+</programlisting>
+          <para>
+      Each detach method returns detached copies of the given instances.
+      The copy mechanism is similar to serialization, except that only 
+      certain fields are traversed. We will see how to control which 
+      fields are detached in a later section.
+      </para>
+          <para><indexterm><primary>detachment</primary><secondary>of
dirty objects</secondary></indexterm>
+      When detaching an instance that has been modified in the current
+      transaction (and thus made dirty), the current transaction
+      is flushed. This means that when subsequently re-attaching 
+      the detached instances, OpenJPA assumes that the transaction from 
+      which they were originally detached was committed; if 
+      it has been rolled back, then the re-attachment process will throw 
+      an optimistic concurrency exception.
+      </para>
+          <para>
+      You can stop OpenJPA from assuming the transaction will commit by
+      invoking <methodname>OpenJPAEntityManager.setRollbackOnly</methodname>

+      prior to detaching your objects.  Setting the 
+      <literal>RollbackOnly</literal> flag prevents OpenJPA from flushing 
+      when detaching dirty objects; instead OpenJPA just runs its pre-flush 
+      actions (see the 
+      <methodname>OpenJPAEntityManager.preFlush</methodname>
+      <ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html">
+      Javadoc</ulink> for details).
+      </para>
+          <para>
+      This allows you to use the same 
+      instances in multiple attach/modify/detach/rollback cycles.  
+      Alternatively, you might also prevent a flush by making your 
+      modifications outside of a transaction (with 
+      <literal>NontransactionalWrite</literal> enabled) before detaching.
+      </para>
+        </section>
+        <section id="ref_guide_attach_behavior">
+          <title>Attach Behavior</title>
+          <indexterm zone="ref_guide_attach_behavior">
+            <primary>attachment</primary>
+            <secondary>behavior</secondary>
+          </indexterm>
+          <para>
+      When attaching, OpenJPA uses several strategies to determine the 
+      optimal way to merge changes made to the detached instance.  As 
+      you will see, these strategies can even be used to attach changes 
+      made to a transient instance which was never detached in the first 
+      place.
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para>
+          If the instance was detached and 
+          <link linkend="ref_guide_detach_graph">detached state</link>
+          is enabled, OpenJPA will use the detached state to determine 
+          the object's version and primary key values.  In addition,
+          this state will tell OpenJPA which fields were loaded at the 
+          time of detach, and in turn where to expect changes.  Loaded
+          detached fields with null values will set the attached
+          instance's corresponding fields to null.
+          </para>
+            </listitem>
+            <listitem>
+              <para>
+          If the instance has
+          <phrase>
+          a <literal>Version</literal> field,
+          </phrase>
+          
+          
+          OpenJPA will consider the object detached if the version
+          field has a non-default value, and new otherwise.  
+          </para>
+              <para>
+          When attaching null fields in these cases, OpenJPA cannot 
+          distinguish between a field that was unloaded and one that
+          was intentionally set to null. In this case, OpenJPA will use 
+          the current 
+          <link linkend="ref_guide_detach_graph">detach state</link>
+          setting to determine how to handle null fields: 
+          fields that would have been included in the detached state 
+          are treated as loaded, and will in turn set the 
+          corresponding attached field to null.
+          </para>
+            </listitem>
+            <listitem>
+              <para>
+          If neither of the above cases apply, OpenJPA will check to
+          see if an instance with the same primary key values exists
+          in the database.  If so, the object is considered detached.
+          Otherwise, it is considered new.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <para>
+      These strategies will be assigned on a per-instance basis,
+      such that during the attachment of an object graph more than
+      one of the above strategies may be used.
+      </para>
+          <para>
+      If you attempt to attach a versioned instance whose representation 
+      has changed in the datastore since detachment, OpenJPA will throw an
+      optimistic concurrency exception upon commit or flush, just as if 
+      a normal optimistic conflict was detected. When attaching an 
+      instance whose database record has 
+      been deleted since detaching, or when attaching a detached 
+      instance into a manager that has a stale version of the object, 
+      OpenJPA will throw an optimistic concurrency exception
+      from the attach method. In these cases, OpenJPA sets the 
+      <literal>RollbackOnly</literal> flag on the transaction.
+      </para>
+        </section>
+        <section id="ref_guide_detach_graph">
+          <title>Defining the Detached Object Graph</title>
+          <indexterm zone="ref_guide_detach_graph">
+            <primary>detachment</primary>
+            <secondary>defining the object graph</secondary>
+          </indexterm>
+          <para>
+      When detached objects lose their association with the OpenJPA
+      runtime, they also lose the ability to load additional state
+      from the datastore.  It is important, therefore, to populate objects
+      with all the persistent state you will need before detaching them.
+      While you are free to do this manually, OpenJPA includes
+      facilities for automatically populating objects when they detach.
+      The <link linkend="openjpa.DetachState"><literal>openjpa.DetachState
+      </literal></link> configuration property determines which fields
+      and relations are detached by default.   All settings are recursive.
+      They are:
+      </para>
+          <orderedlist>
+            <listitem>
+              <para><literal>loaded</literal>: Detach all fields and relations

+          that are already loaded, but don't include unloaded fields 
+          in the detached graph.  This is the default.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>fgs</literal>: Detach all fields and relations
in 
+          the default fetch group, and any other fetch groups that 
+          you have added to the current
+          <link linkend="ref_guide_runtime">fetch 
+          configuration</link>.  For more information on custom 
+          fetch groups, see <xref linkend="ref_guide_fetch"/>.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>all</literal>: Detach all fields and relations.
 
+          Be very careful when
+          using this mode; if you have a highly-connected domain 
+          model, you could end up bringing every object in the
+          database into memory!
+          </para>
+            </listitem>
+          </orderedlist>
+          <para>
+        Any field that is not included in the set determined by the detach
+      mode is set to its Java default value in the detached instance.
+      </para>
+          <para>
+      The <literal>openjpa.DetachState</literal> option is actually a 
+      plugin string (see <xref linkend="ref_guide_conf_plugins"/>) that
+      allows you to also configure the following options related to
+      detached state:
+      </para>
+          <itemizedlist>
+            <listitem>
+              <para><literal>DetachedStateField</literal>: As described
in 
+          <xref linkend="ref_guide_attach_behavior"/> above, OpenJPA can
+          take advantage of a <emphasis>detached state field
+          </emphasis> to make the attach process more efficient.
+          This field is added by the enhancer and is not visible to
+          your application.  Set this property to one of the
+          following values:
+          </para>
+              <itemizedlist>
+                <listitem>
+                  <para><literal>transient</literal>: Use a transient 
+              detached state field.  This gives the benefits of
+              a detached state field to local objects that are
+              never serialized, but retains
+              serialization compatibility for client tiers without
+              access to the enhanced versions of your classes. 
+              This is the default.
+              </para>
+                </listitem>
+                <listitem>
+                  <para><literal>true</literal>: Use a non-transient 
+              detached state field so that objects crossing
+              serialization barriers can still be attached 
+              efficiently.  This requires, however, that your
+              client tier have the enhanced versions of your
+              classes and the OpenJPA libraries.
+              </para>
+                </listitem>
+                <listitem>
+                  <para><literal>false</literal>: Do not use a detached
+              state field.
+              </para>
+                </listitem>
+              </itemizedlist>
+              <para>
+          You can override the setting of this property or declare
+          your own detached state field on individual classes using 
+          OpenJPA's metadata extensions.  See 
+          <xref linkend="ref_guide_detach_field"/> below.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>DetachedStateManager</literal>: Whether to
use a
+          detached state manager.  A detached state manager makes
+          attachment much more efficient.  Like a detached state 
+          field, however, it breaks serialization compatibility with
+          the unenhanced class if it isn't transient.
+          </para>
+              <para>
+          This setting piggybacks on the <literal>DetachedStateField
+          </literal> setting above.  If your detached state field is 
+          transient, the detached state manager will also be 
+          transient. If the detached state field is disabled, the 
+          detached state manager will also be disabled.  This is 
+          typically what you'll want.  By setting <literal>
+          DetachedStateField</literal> to true (or transient) and 
+          setting this property to false, however, you can use a 
+          detached state field <emphasis role="bold">without
+          </emphasis> using a detached state manager.   This may be 
+          useful for debugging or for legacy OpenJPA users who find 
+          differences between OpenJPA's behavior with a detached state 
+          manager and OpenJPA's older behavior without one.
+          </para>
+            </listitem>
+            <listitem>
+              <para><literal>AccessUnloaded</literal>: Whether to allow
access
+          to unloaded fields of detached objects.  Defaults to true.
+          Set to false to throw an exception whenever an unloaded
+          field is accessed.  This option is only available when you
+          use detached state managers, as determined by the settings
+          above.
+          </para>
+            </listitem>
+          </itemizedlist>
+          <example id="ref_guide_detach_graph_confex">
+            <title>Configuring Detached State</title>
+            <programlisting format="linespecific">
+&lt;property name="openjpa.DetachState" value="fgs(DetachedStateField=true)"/&gt;
+</programlisting>
+          </example>
+          <para>
+      You can also alter the set of fields that will be included in the
+      detached graph at runtime.
+      <ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"><classname>OpenJPAEntityManager</classname></ulink>s
expose the 
+      following APIs for controlling detached state:
+      </para>
+          <programlisting format="linespecific">
+public static final int DETACH_LOADED;
+public static final int DETACH_FGS;
+public static final int DETACH_ALL;
+public int getDetachState ();
+public void setDetachState (int mode);
+</programlisting>
+          <section id="ref_guide_detach_field">
+            <title>Detached State Field</title>
+            <indexterm zone="ref_guide_detach_field">
+              <primary>detachment</primary>
+              <secondary>detached state field</secondary>
+            </indexterm>
+            <para>
+        When the detached state field is enabled, the OpenJPA enhancer 
+        adds an additional field to the enhanced version of your class.
+        This field of type <classname>Object</classname>.  OpenJPA uses
+        this field for bookkeeping information, such as the versioning
+        data needed to detect optimistic concurrency violations when the
+        object is re-attached. 
+        </para>
+            <para>
+        It is possible to define this detached state field yourself.
+        Declaring this field in your class metadata prevents the 
+        enhancer from adding any extra fields to the class, and keeps 
+        the enhanced class serialization-compatible with 
+        the unenhanced version.
+        The detached state field must not be persistent.
+        See <xref linkend="detached-state-field"/> for details on
+        how to declare a detached state field.
+        </para>
+            <programlisting format="linespecific">
+import org.apache.openjpa.persistence.*;
+
+@Entity
+public class Magazine
+    implements Serializable
+{
+    private String name;
+    @DetachedState private Object state;
+    ...
+}
+</programlisting>
+          </section>
+        </section>
+      </section>
+      <section id="ref_guide_event">
+        <title>Remote Event Notification Framework</title>
+        <indexterm zone="ref_guide_event">
+          <primary>remote</primary>
+          <secondary>events</secondary>
+        </indexterm>
+        <indexterm>
+          <primary>events</primary>
+          <secondary>remote</secondary>
+          <see>remote, events</see>
+        </indexterm>
+        <para><indexterm><primary>remote</primary><secondary>events</secondary><tertiary>RemoteCommitProvider</tertiary></indexterm><indexterm><primary>remote</primary><secondary>events</secondary><tertiary>RemoteCommitListener</tertiary></indexterm>
+  The remote event notification framework allows a subset of the 
+  information available through OpenJPA's transaction events (see 
+  <xref linkend="ref_guide_runtime_pm_event"/>) to be broadcast to remote 
+  listeners.  OpenJPA's <link linkend="ref_guide_cache">data cache</link>, for

+  example, uses remote events to remain synchronized when deployed in 
+  multiple JVMs.
+  </para>
+        
+        <para>
+  To enable remote events, you must configure the <classname>
+  EntityManagerFactory</classname> to use a  
+  <literal>RemoteCommitProvider</literal> (see below). 
+  </para>
+        <para>
+  When a <literal>RemoteCommitProvider</literal> is properly configured, you

+  can register <ulink url="../apidocs/org/apache/openjpa/event/RemoteCommitListener.html"><classname>RemoteCommitListener</classname></ulink>s
that will be alerted 
+  with a list of modified object ids whenever a transaction on a remote 
+  machine successfully commits.
+  </para>
+        <section id="ref_guide_event_conf">
+          <title>Remote Commit Provider Configuration</title>
+          <indexterm zone="ref_guide_event_conf">
+            <primary>remote</primary>
+            <secondary>events</secondary>
+            <tertiary>configuration</tertiary>
+          </indexterm>
+          <para>
+    OpenJPA includes built in remote commit providers for JMS and TCP 
+    communication.
+    </para>
+          <section id="ref_guide_event_conf_jms">
+            <title>JMS</title>
+            <indexterm zone="ref_guide_event_conf_jms">
+              <primary>remote</primary>
+              <secondary>events</secondary>
+              <tertiary>JMS</tertiary>
+            </indexterm>
+            <para>
+      OpenJPA includes built in remote commit providers for JMS and TCP
+      communication.  The JMS remote commit provider can be configured by 
+      setting the <link linkend="openjpa.RemoteCommitProvider"><literal>
+      openjpa.RemoteCommitProvider</literal></link> property
+      to contain the appropriate configuration properties. The JMS
+      provider understands the following properties:
+      </para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>Topic</literal>: The topic that the remote
commit
+          provider should publish notifications to and subscribe
+          to for notifications sent from other JVMs.  Defaults to
+          <literal>topic/OpenJPACommitProviderTopic</literal></para>
+              </listitem>
+              <listitem>
+                <para><literal>TopicConnectionFactory</literal>: The JNDI
name of
+          a <classname>javax.jms.TopicConnectionFactory</classname>
+          factory to use for finding topics.  Defaults to <literal>
+          java:/ConnectionFactory</literal>. 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 
+          <classname>javax.jms.TopicConnectionFactory</classname>
+          instance. For example, under Weblogic, the JNDI name
+          for the TopicConnectionFactory is
+          <literal>javax.jms.TopicConnectionFactory</literal>.
+          </para>
+              </listitem>
+              <listitem>
+                <para><literal>ExceptionReconnectAttempts</literal>: 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.
+          </para>
+              </listitem>
+              <listitem>
+                <para><literal>*</literal>: All other configuration properties

+          will be interpreted as settings to pass to the JNDI 
+          <classname>InitialContext</classname> on construction.  For
+          example, you might set the <literal>java.naming.provider.url
+          </literal> property to the URL of the context provider.
+          </para>
+              </listitem>
+            </itemizedlist>
+            <para>
+      To configure a factory to use the JMS provider, your properties 
+      might look like the following:
+      </para>
+            <note>
+              <para>
+        Because of the nature of JMS, it is important that you invoke
+        <methodname>EntityManagerFactory.close</methodname>
+        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.
+        </para>
+            </note>
+          </section>
+          <section id="ref_guide_event_conf_tcp">
+            <title>TCP</title>
+            <indexterm zone="ref_guide_event_conf_tcp">
+              <primary>remote</primary>
+              <secondary>events</secondary>
+              <tertiary>TCP</tertiary>
+            </indexterm>
+            <para>
+      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 <literal>saturn.bea.com:1234</literal>
+      represents an <classname>InetAddress</classname> retrieved by 
+      invoking <methodname>InetAddress.getByName ("saturn.bea.com")
+      </methodname> and a port of 1234.
+      </para>
+            <para><indexterm><primary>TCP provider</primary></indexterm>
+      The TCP provider can be configured by setting the <literal>
+      openjpa.RemoteCommitProvider</literal> plugin property to contain the 
+      appropriate configuration settings. The TCP provider understands the
+      following properties:
+      </para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>Port</literal>: The TCP port that the provider

+          should listen on for commit notifications.  Defaults to 
+          5636.
+          </para>
+              </listitem>
+              <listitem>
+                <para><literal>Addresses</literal>: A semicolon-separated
list of 
+          IP addresses to which notifications should be sent. No 
+          default value.
+          </para>
+              </listitem>
+              <listitem>
+                <para><literal>NumBroadcastThreads</literal>: The number
of 
+          threads to create for the purpose of transmitting events to
+          peers.  You sould 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 the <literal>MaxActive</literal> 
+          property of
+          <literal>openjpa.ConnectionFactoryProperties</literal> in
+          <xref linkend="ref_guide_dbsetup_builtin"/>.
+          Setting a value of 0 will result in behavior where the
+          thread invoking <methodname>commit</methodname> will 
+          perform the broadcast directly.  Defaults to 2.
+          </para>
+              </listitem>
+              <listitem>
+                <para><literal>RecoveryTimeMillis</literal>: 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.
+          </para>
+              </listitem>
+              <listitem>
+                <para><literal>MaxIdle</literal>: The number of TCP sockets

+          (channels) to keep open to each peer in the cluster for 
+          the transmission of events.  Defaults to 2.
+          </para>
+              </listitem>
+              <listitem>
+                <para><literal>MaxActive</literal>: The maximum allowed
number 
+          of TCP sockets (channels) to open simultaneously 
+          between each peer in the cluster.
+          Defaults to 2.
+          </para>
+              </listitem>
+            </itemizedlist>
+            <para>
+      To configure a factory to use the TCP provider, your properties 
+      might look like the following:
+      </para>
+            <example id="ref_guide_event_conf_tcpex">
+              <title>TCP Remote Commit Provider Configuration</title>
+              <programlisting format="linespecific">
+&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;
+</programlisting>
+            </example>
+          </section>
+          <section id="ref_guide_event_conf_common">
+            <title>Common Properties</title>
+            <indexterm zone="ref_guide_event_conf_common">
+              <primary>remote</primary>
+              <secondary>events</secondary>
+              <tertiary>common properties</tertiary>
+            </indexterm>
+            <para>
+      In addition to the provider-specific configuration options above,
+      all providers accept the following plugin properties:
+      </para>
+            <itemizedlist>
+              <listitem>
+                <para><literal>TransmitPersistedObjectIds</literal>: 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.
+          </para>
+              </listitem>
+            </itemizedlist>
+            <para>
+      To transmit persisted object ids in our remote commit events
+      using the JMS provider, we modify the previous example as follows:
+      </para>
+          </section>
+        </section>
+        <section id="ref_guide_event_customization">
+          <title>Customization</title>
+          <indexterm zone="ref_guide_event_customization">
+            <primary>remote</primary>
+            <secondary>events</secondary>
+            <tertiary>customization</tertiary>
+          </indexterm>
+          <para>
+    You can develop additional mechanisms for remote event notification be
+    by creating an implementation of the 
+    <ulink url="../apidocs/org/apache/openjpa/event/RemoteCommitProvider.html"><classname>
+    RemoteCommitProvider</classname></ulink> interface, possibly by 
+    extending the 
+    <ulink url="../apidocs/org/apache/openjpa/event/AbstractRemoteCommitProvider.html"><classname>AbstractRemoteCommitProvider</classname></ulink>
+    abstract class. For details on particular customization needs,
+    contact us at <ulink url="mailto:support@solarmetric.com">
+    support@solarmetric.com</ulink>.
+    </para>
+        </section>
+      </section>
+    </chapter>



Mime
View raw message