[jboss-svn-commits] JBL Code SVN: r36898 - labs/jbosstm/trunk/docs/failure_recovery_guide/en-US.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Apr 13 07:19:41 EDT 2011
Author: tomjenkinson
Date: 2011-04-13 07:19:41 -0400 (Wed, 13 Apr 2011)
New Revision: 36898
Modified:
labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/How_JBossTS_manages_the_OTS_recovery_protocol.xml
Log:
JBTM-700 formatted the page
Modified: labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/How_JBossTS_manages_the_OTS_recovery_protocol.xml
===================================================================
--- labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/How_JBossTS_manages_the_OTS_recovery_protocol.xml 2011-04-13 11:19:06 UTC (rev 36897)
+++ labs/jbosstm/trunk/docs/failure_recovery_guide/en-US/How_JBossTS_manages_the_OTS_recovery_protocol.xml 2011-04-13 11:19:41 UTC (rev 36898)
@@ -3,193 +3,271 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "Failure_Recovery_Guide.ent">
]>
<chapter>
- <title>How JBossTS manages the OTS Recovery Protocol</title>
+ <title>How JBossTS manages the OTS Recovery Protocol</title>
+ <section>
+ <title>Recovery Protocol in OTS - Overview</title>
+ <para>To manage recovery in case of failure, the OTS specification has defined a recovery protocol. Transaction’s participants in a doubt status
+ could use the RecoveryCoordinator to determine the status of the transaction. According to that transaction status, those participants can take
+ appropriate decision either by roll backing or committing.</para>
+ <figure>
+ <title>Resource and RecoveryCoordinator relationship</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/fig3-resource-recoverycoordinator.gif" format="GIF" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>A reference to a RecoveryCoordinator is returned as a result of successfully calling register_resource on the transaction Coordinator. This
+ object, which is implicitly associated with a single Resource, can be used to drive the Resource through recovery procedures in the event of a
+ failure occurring during the transaction.</para>
+ </section>
+ <section>
+ <title>RecoveryCoordinator in JBossTS</title>
+ <para>On each resource registration a RecoveryCoordinator Object is expected to be created and returned to the application that invoked the
+ register_resource operation. Behind each CORBA object there should be an object implementation or Servant object, in POA terms, which performs
+ operations made on a RecoveryCoordinator object. Rather than to create a RecoveryCoordinator object with its associated servant on each
+ register_resource, JBossTS enhances performance by avoiding the creation of servants but it relies on a default RecoveryCoordinator object with
+ it’s associated default servant to manage all replay_completion invocations.</para>
+ <para>In the next sections we first give an overview of the Portable Object Adapter architecture, then we describe how this architecture is used
+ to provide RecoveryCoordinator creation with optimization as explained above.</para>
<section>
- <title>Recovery Protocol in OTS - Overview</title>
- <para>To manage recovery in case of failure, the OTS specification has defined a recovery protocol. Transaction’s participants in a doubt status could use the RecoveryCoordinator to determine the status of the transaction. According to that transaction status, those participants can take appropriate decision either by roll backing or committing.</para>
- <figure>
- <title>Resource and RecoveryCoordinator relationship</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig3-resource-recoverycoordinator.gif" format="GIF"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>A reference to a RecoveryCoordinator is returned as a result of successfully calling register_resource on the transaction Coordinator. This object, which is implicitly associated with a single Resource, can be used to drive the Resource through recovery procedures in the event of a failure occurring during the transaction.</para>
- </section>
- <section>
- <title>RecoveryCoordinator in JBossTS</title>
- <para>On each resource registration a RecoveryCoordinator Object is expected to be created and returned to the application that invoked the register_resource operation. Behind each CORBA object there should be an object implementation or Servant object, in POA terms, which performs operations made on a RecoveryCoordinator object. Rather than to create a RecoveryCoordinator object with its associated servant on each register_resource, JBossTS enhances performance by avoiding the creation of servants but it relies on a default RecoveryCoordinator object with it’s associated default servant to manage all replay_completion invocations.</para>
- <para>In the next sections we first give an overview of the Portable Object Adapter architecture, then we describe how this architecture is used to provide RecoveryCoordinator creation with optimization as explained above.</para>
- <section>
- <title>Understanding POA</title>
- <para>Basically, the Portable Object Adapter, or POA is an object that intercepts a client request and identifies the object that satisfies the client request. The Object is then invoked and the response is returned to the client.</para>
- <figure>
- <title>Overview of the POA</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig4-overview-of-poa.gif" format="GIF"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>The object that performs the client request is referred as a servant, which provides the implementation of the CORBA object requested by the client. A servant provides the implementation for one or more CORBA object references. To retreive a servant, each POA maintains an Active Object Map that maps all objects that have been activated in the POA to a servant. For each incoming request, the POA looks up the object reference in the Active Object Map and tries to find the responsible servant. If none is found, the request is either delegated to a default servant, or a servant manager is invoked to activate or locate an appropriate servant. In addition to the name space for the objects, which are identified by Object Ids, a POA also provides a name space for POAs. A POA is created as a child of an existing POA, which forms a hierarchy starting with the root POA.</para>
- <para>Each POA has a set of policies that define its characteristics. When creating a new POA, the default set of policies can be used or different values can be assigned that suit the application requirements. The POA specification defines:</para>
- <itemizedlist>
- <listitem>
- <para>Thread policy – Specifies the threading model to be used by the POA. Possible values are:</para>
- <itemizedlist>
- <listitem>
- <para>ORB_CTRL_MODEL – (default) The POA is responsible for assigning requests to threads.</para>
- </listitem>
- <listitem>
- <para>SINGLE_THREAD_MODEL – the POA processes requests sequentially</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>Lifespan policy - specifies the lifespan of the objects implemented in the POA. The lifespan policy can have the following values:</para>
- <itemizedlist>
- <listitem>
- <para>
-TRANSIENT (Default) Objects implemented in the POA cannot outlive the process in which they are first created. Once the POA is deactivated, an OBJECT_NOT_EXIST exception occurs when attempting to use any object references generated by the POA.
+ <title>Understanding POA</title>
+ <para>Basically, the Portable Object Adapter, or POA is an object that intercepts a client request and identifies the object that satisfies the
+ client request. The Object is then invoked and the response is returned to the client.</para>
+ <figure>
+ <title>Overview of the POA</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/fig4-overview-of-poa.gif" format="GIF" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The object that performs the client request is referred as a servant, which provides the implementation of the CORBA object requested by
+ the client. A servant provides the implementation for one or more CORBA object references. To retreive a servant, each POA maintains an Active
+ Object Map that maps all objects that have been activated in the POA to a servant. For each incoming request, the POA looks up the object
+ reference in the Active Object Map and tries to find the responsible servant. If none is found, the request is either delegated to a default
+ servant, or a servant manager is invoked to activate or locate an appropriate servant. In addition to the name space for the objects, which
+ are identified by Object Ids, a POA also provides a name space for POAs. A POA is created as a child of an existing POA, which forms a
+ hierarchy starting with the root POA.</para>
+ <para>Each POA has a set of policies that define its characteristics. When creating a new POA, the default set of policies can be used or
+ different values can be assigned that suit the application requirements. The POA specification defines:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Thread policy – Specifies the threading model to be used by the POA. Possible values are:</para>
+ <itemizedlist>
+ <listitem>
+ <para>ORB_CTRL_MODEL – (default) The POA is responsible for assigning requests to threads.</para>
+ </listitem>
+ <listitem>
+ <para>SINGLE_THREAD_MODEL – the POA processes requests sequentially</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>Lifespan policy - specifies the lifespan of the objects implemented in the POA. The lifespan policy can have the following values:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ TRANSIENT (Default) Objects implemented in the POA cannot outlive the process in which they are first created. Once the POA is
+ deactivated, an
+ OBJECT_NOT_EXIST exception occurs when attempting to use any object references generated by the POA.
</para>
- </listitem>
- <listitem>
- <para>
-PERSISTENT Objects implemented in the POA can outlive the process in which they are first created.
+ </listitem>
+ <listitem>
+ <para>
+ PERSISTENT Objects implemented in the POA can outlive the process in which they are first created.
</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
-Object ID Uniqueness policy - allows a single servant to be shared by many abstract objects. The Object ID Uniqueness policy can have the following values:</para>
- <itemizedlist>
- <listitem>
- <para>
-UNIQUE_ID (Default) Activated servants support only one Object ID.
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ Object ID Uniqueness policy - allows a single servant to be shared by many abstract objects. The Object ID Uniqueness policy can have
+ the following
+ values:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ UNIQUE_ID (Default) Activated servants support only one Object ID.
</para>
- </listitem>
- <listitem>
- <para>
-MULTIPLE_ID Activated servants can have one or more Object IDs. The Object ID must be determined within the method being invoked at run time.
+ </listitem>
+ <listitem>
+ <para>
+ MULTIPLE_ID Activated servants can have one or more Object IDs. The Object ID must be determined within the method being invoked
+ at run time.
</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
-ID Assignment policy - specifies whether object IDs are generated by server applications or by the POA. The ID Assignment policy can have the following values:</para>
- <itemizedlist>
- <listitem>
- <para>
-USER_ID is for persistent objects, and
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ ID Assignment policy - specifies whether object IDs are generated by server applications or by the POA. The ID Assignment policy can
+ have the
+ following values:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ USER_ID is for persistent objects, and
</para>
- </listitem>
- <listitem>
- <para>
-SYSTEM_ID is for transient objects
+ </listitem>
+ <listitem>
+ <para>
+ SYSTEM_ID is for transient objects
</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
-Servant Retention policy - specifies whether the POA retains active servants in the Active Object Map. The Servant Retention policy can have the following values:
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ Servant Retention policy - specifies whether the POA retains active servants in the Active Object Map. The Servant Retention policy
+ can have the
+ following values:
</para>
- <itemizedlist>
- <listitem>
- <para>
-RETAIN (Default) The POA tracks object activations in the Active Object Map. RETAIN is usually used with ServantActivators or explicit activation methods on POA.
+ <itemizedlist>
+ <listitem>
+ <para>
+ RETAIN (Default) The POA tracks object activations in the Active Object Map. RETAIN is usually used with ServantActivators or
+ explicit activation
+ methods on POA.
</para>
- </listitem>
- <listitem>
- <para>
-NON_RETAIN The POA does not retain active servants in the Active Object Map. NON_RETAIN is typically used with ServantLocators.
+ </listitem>
+ <listitem>
+ <para>
+ NON_RETAIN The POA does not retain active servants in the Active Object Map. NON_RETAIN is typically used with ServantLocators.
</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
-Request Processing policy - specifies how requests are processed by the POA.
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ Request Processing policy - specifies how requests are processed by the POA.
</para>
- <itemizedlist>
- <listitem>
- <para>
-USE_ACTIVE_OBJECT_MAP (Default) If the Object ID is not listed in the Active Object Map, an OBJECT_NOT _EXIST exception is returned. The POA must also use the RETAIN policy with this value.
+ <itemizedlist>
+ <listitem>
+ <para>
+ USE_ACTIVE_OBJECT_MAP (Default) If the Object ID is not listed in the Active Object Map, an OBJECT_NOT _EXIST exception is
+ returned. The POA must also use the
+ RETAIN policy with this value.
</para>
- </listitem>
- <listitem>
- <para>
-USE_DEFAULT_SERVANT If the Object ID is not listed in the Active Object Map or the NON_RETAIN policy is set, the request is dispatched to the default servant. If no default servant has been registered, an OBJ_ADAPTER exception is returned. The POA must also use the MULTIPLE_ID policy with this value.
+ </listitem>
+ <listitem>
+ <para>
+ USE_DEFAULT_SERVANT If the Object ID is not listed in the Active Object Map or the NON_RETAIN policy is set, the request is
+ dispatched to the default servant. If
+ no default servant has been registered, an OBJ_ADAPTER exception is returned. The POA must also
+ use the MULTIPLE_ID policy with this
+ value.
</para>
- </listitem>
- <listitem>
- <para>
-USE_SERVANT_MANAGER If the Object ID is not listed in the Active Object Map or the NON_RETAIN policy is set, the servant manager is used to obtain a servant.
+ </listitem>
+ <listitem>
+ <para>
+ USE_SERVANT_MANAGER If the Object ID is not listed in the Active Object Map or the NON_RETAIN policy is set, the servant manager
+ is used to obtain a servant.
</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
-Implicit Activation policy - specifies whether the POA supports implicit activation of servants. The Implicit Activation policy can have the following values:
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ Implicit Activation policy - specifies whether the POA supports implicit activation of servants. The Implicit Activation policy can
+ have the following
+ values:
</para>
- <itemizedlist>
- <listitem>
- <para>
-IMPLICIT_ACTIVATION The POA supports implicit activation of servants. Servants can be activated by converting them to an object reference with org.omg.PortableServer.POA.servant_to_reference() or by invoking _this()on the servant. The POA must also use the SYSTEM_ID and RETAIN policies with this value.
+ <itemizedlist>
+ <listitem>
+ <para>
+ IMPLICIT_ACTIVATION The POA supports implicit activation of servants. Servants can be activated by converting them to an object
+ reference with
+ org.omg.PortableServer.POA.servant_to_reference() or by invoking _this()on the servant. The POA must also use the
+ SYSTEM_ID and RETAIN
+ policies with this value.
</para>
- </listitem>
- <listitem>
- <para>
-NO_IMPLICIT_ACTIVATION (Default) The POA does not support implicit activation of servants.
+ </listitem>
+ <listitem>
+ <para>
+ NO_IMPLICIT_ACTIVATION (Default) The POA does not support implicit activation of servants.
</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- <para>
-It appears that to redirect replay_completion invocations to a default servant we need to create a POA with the Request Processing policy assigned with the value set to USE_DEFAULT_SERVANT. However to reach that default Servant we should first reach the POA that forward the request to the default servant. Indeed, the ORB uses a set of information to retrieve a POA; these information are contained in the object reference used by the client. Among these information there are the IP address and the port number where resides the server and also the POA name. To perform replay_completion invocations, the solution adopted by JBossTS is to provide one Servant, per machine, and located in the RecoveryManager process, a separate process from client or server applications. The next section explains how the indirection to a default Servant located on a separate process is provided for JacORB.
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>
+ It appears that to redirect replay_completion invocations to a default servant we need to create a POA with the Request Processing policy
+ assigned
+ with the value set to USE_DEFAULT_SERVANT. However to reach that default Servant we should first reach the POA that forward the
+ request to the
+ default servant. Indeed, the ORB uses a set of information to retrieve a POA; these information are contained in the object
+ reference used by
+ the client. Among these information there are the IP address and the port number where resides the server and also the POA
+ name. To perform
+ replay_completion invocations, the solution adopted by JBossTS is to provide one Servant, per machine, and located in the
+ RecoveryManager
+ process, a separate process from client or server applications. The next section explains how the indirection to a default
+ Servant located on
+ a separate process is provided for JacORB.
</para>
- </section>
</section>
+ </section>
+ <section>
+ <title>The default RecoveryCoordinator in JacOrb</title>
+ <para>
+ JacORB does not define additional policies to redirect any request on a RecoveryCoordinator object to a default servant located in the
+ Recovery Manager process. However it provides a set of APIs that allows building object references with specific IP address, port number and POA
+ name in order to reach the appropriate default servant.
+ </para>
<section>
- <title>The default RecoveryCoordinator in JacOrb</title>
- <para>
- JacORB does not define additional policies to redirect any request on a RecoveryCoordinator object to a default servant located in the Recovery Manager process. However it provides a set of APIs that allows building object references with specific IP address, port number and POA name in order to reach the appropriate default servant.
+ <title>How Does it work</title>
+ <para>
+ When the Recovery Manager is launched it seeks in the configuration the RecoveryActivator that need be loaded. Once done it invokes the
+ startRCservice
+ method of each loaded instances. As seen in in the previous chapter (Recovery Manager ) the class to load that implements the
+ RecoveryActivator interface is the class RecoveryEnablement. This generic class, located in the package
+ com.arjuna.ats.internal.jts.orbspecific.recovery, hides the nature of the ORB being used by the application (JacORB). The following figure
+ illustrates the behavior of the RecoveryActivator that leads to the creation of the default servant that performs replay_completion
+ invocations requests.
</para>
- <section>
- <title>How Does it work</title>
- <para>
- When the Recovery Manager is launched it seeks in the configuration the RecoveryActivator that need be loaded. Once done it invokes the startRCservice method of each loaded instances. As seen in in the previous chapter (Recovery Manager ) the class to load that implements the RecoveryActivator interface is the class RecoveryEnablement. This generic class, located in the package com.arjuna.ats.internal.jts.orbspecific.recovery, hides the nature of the ORB being used by the application (JacORB). The following figure illustrates the behavior of the RecoveryActivator that leads to the creation of the default servant that performs replay_completion invocations requests.
+ <para>
+ In addition to the creation of the default servant, an object reference to a RecoveryCoordinator object is created and stored in the
+ ObjectStore. As
+ we will see this object reference will be used to obtain its IP address, port number and POA name and assign them to any
+ RecoveryCoordinator
+ object reference created on register_resource.
</para>
- <para>
- In addition to the creation of the default servant, an object reference to a RecoveryCoordinator object is created and stored in the ObjectStore. As we will see this object reference will be used to obtain its IP address, port number and POA name and assign them to any RecoveryCoordinator object reference created on register_resource.
- </para>
- <figure>
- <title>Recovery Manager</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig5-recoverymanager.gif" format="GIF"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>
-When an application registers a resource with a transaction, a RecoveryCoordinator object reference is expected to be returned. To build that object reference, the Transaction Service uses the RecoveryCoordinator object reference created within the Recovery Manager as a template. The new object reference contains practically the same information to retrieve the default servant (IP address, port number, POA name, etc.), but the Object ID is changed; now, it contains the Transaction ID of the transaction in progress and also the Process ID of the process that is creating the new RecoveryCoordinator object reference, as illustrated in Figure 11.
+ <figure>
+ <title>Recovery Manager</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/fig5-recoverymanager.gif" format="GIF" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ When an application registers a resource with a transaction, a RecoveryCoordinator object reference is expected to be returned. To build
+ that object
+ reference, the Transaction Service uses the RecoveryCoordinator object reference created within the Recovery Manager as a template.
+ The new
+ object reference contains practically the same information to retrieve the default servant (IP address, port number, POA name, etc.),
+ but the
+ Object ID is changed; now, it contains the Transaction ID of the transaction in progress and also the Process ID of the process that is
+ creating the new RecoveryCoordinator object reference, as illustrated in Figure 11.
</para>
- <figure>
- <title>Resource registration and returned RecoveryCoordinator Object reference build from a reference stored in the ObjectStore. </title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/fig6-resourceregistration.gif" format="GIF"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>
-Since a RecoveryCoordintaor object reference returned to an application contains all information to retrieve the POA then the default servant located in the Recovery Manager, all replay_completion invocation, per machine, are forwarded to the same default RecoveryCoordinator that is able to retreive the Object ID from the incoming request to extract the transaction identifier and the process identifier needed to determine the status of the requested transaction.
+ <figure>
+ <title>Resource registration and returned RecoveryCoordinator Object reference build from a reference stored in the ObjectStore. </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/fig6-resourceregistration.gif" format="GIF" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Since a RecoveryCoordintaor object reference returned to an application contains all information to retrieve the POA then the default
+ servant located
+ in the Recovery Manager, all replay_completion invocation, per machine, are forwarded to the same default RecoveryCoordinator
+ that is able to
+ retreive the Object ID from the incoming request to extract the transaction identifier and the process identifier needed to
+ determine the
+ status of the requested transaction.
</para>
- </section>
</section>
+ </section>
</chapter>
More information about the jboss-svn-commits
mailing list