[jboss-svn-commits] JBL Code SVN: r36225 - in labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US: extras and 1 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Dec 7 00:57:58 EST 2010
Author: misty at redhat.com
Date: 2010-12-07 00:57:58 -0500 (Tue, 07 Dec 2010)
New Revision: 36225
Added:
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/DemoClient.java
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/DemoServer.java
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/example-DemoResource.java
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/example-idl-interface.java
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/transactional-implementation.java
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/sequence-diagram.png
Modified:
labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/Example.xml
Log:
Converted Examples.xml
Modified: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/Example.xml
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/Example.xml 2010-12-07 04:04:28 UTC (rev 36224)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/Example.xml 2010-12-07 05:57:58 UTC (rev 36225)
@@ -3,7 +3,294 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "ArjunaJTS_Development_Guide.ent">
%BOOK_ENTITIES;
]>
-<chapter id="chap-ArjunaJTS_Development_Guide-Test_Chapter">
- <title></title>
+<chapter>
+ <title>Example</title>
+ <para>
+ This example illustrates the concepts and the implementation details for a simple client/server example using
+ implicit context propagation and indirect context management.
+ </para>
+
+ <section>
+ <title>The basic example</title>
+ <para>
+ This example only includes a single unit of work within the scope of the transaction. consequently, only a
+ one-phase commit is needed.
+ </para>
+ <para>
+ The client and server processes are both invoked using the <option>implicit propagation</option> and
+ <option>interposition</option> command-line options.
+ </para>
+ <para>
+ For the purposes of this worked example, a single method implements the
+ <interfacename>DemoInterface</interfacename> interface. This method is used in the DemoClient program.
+ </para>
+
+ <example>
+ <title>idl interface</title>
+ <programlisting role="JAVA" language="Java"><xi:include href="extras/example-idl-interface.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+
+ <section>
+ <title>Example implementation of the interface</title>
+ <para>
+ This section deals with the pieces needed to implement the example interface.
+ </para>
+
+ <section>
+ <title>Resource</title>
+ <para>
+ The example overrides the methods of the <classname>Resource</classname> implementation class. The
+ <classname>DemoResource</classname> implementation includes the placement of
+ <methodname>System.out.println</methodname> statements at judicious points, to highlight when a particular
+ method is invoked.
+ </para>
+ <para>
+ Only a single unit of work is included within the scope of the transaction. Therefore, the
+ <methodname>prepare</methodname> or <methodname>commit</methodname> methods should never be invoked, but the
+ <methodname>commit_one_phase</methodname> method should be invoked.
+ </para>
+
+ <example>
+ <title>DemoResource</title>
+ <programlisting role="JAVA" language="Java"><xi:include href="extras/example-DemoResource.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>Transactional implementation</title>
+ <para>
+ At this stage, the <filename>Demo.idl</filename> has been processed by the ORB’s idl compiler to generate the
+ necessary client and server package.
+ </para>
+ <para>
+ Line 14 returns the transactional context for the <classname>Current</classname> pseudo object. After
+ obtaining a <classname>Control</classname> object, you can derive the Coordinator object (line 16).
+ </para>
+ <para>
+ Lines 17 and 19 create a resource for the transaction, and then inform the ORB that the resource is ready to
+ receive incoming method invocations.
+ </para>
+ <para>
+ Line 20 uses the <classname>Coordinator</classname> to register a <classname>DemoResource</classname> object
+ as a participant in the transaction. When the transaction terminates, the resource receives requests to commit
+ or rollback the updates performed as part of the transaction.
+ </para>
+
+ <example>
+ <title>Transactional implementation</title>
+ <programlisting role="JAVA" language="Java"><xi:include href="extras/transactional-implementation.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>Server implementation</title>
+ <para>
+ First, you need to to initialize the ORB and the POA. Lines 10 through 14 accomplish these tasks.
+ </para>
+ <para>
+ The servant class <classname>DemoImplementation</classname> contains the implementation code for the
+ <interfacename>DemoInterface</interfacename> interface. The servant services a particular client request. Line
+ 16 instantiates a servant object for the subsequent servicing of client requests.
+ </para>
+ <para>
+ Once a servant is instantiated, connect the servant to the POA, so that it can recognize the invocations on
+ it, and pass the invocations to the correct servant. Line 18 performs this task.
+ </para>
+ <para>
+ Lines 20 through to 21 registers the service through the default naming mechanism. More information about the
+ options available can be found in the ORB Portability Guide.
+ </para>
+ <para>
+ If this registration is successful, line 23 outputs a <literal>sanity check</literal> message.
+ </para>
+ <para>
+ Finally, line 25 places the server process into a state where it can begin to accept requests from client
+ processes.
+ </para>
+
+ <example>
+ <title>DemoServer</title>
+ <programlisting role="JAVA" language="Java"><xi:include href="extras/DemoServer.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ <para>
+ After the server compiles, you can use the command line options defined below to start a server process. By
+ specifying the usage of a filter on the command line, you can override settings in the
+ <filename>TransactionService.properties</filename> file.
+ </para>
+ <note>
+ <para>
+ if you specify the interposition filter, you also imply usage of implicit context propagation.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>Client implementation</title>
+ <para>
+ The client, like the server, requires you to first initialize the ORB and the POA. Lines 14 through 18
+ accomplish these tasks.
+ </para>
+ <para>
+ After a server process is started, you can obtain the object reference through the default publication
+ mechanism used to publish it in the server. This is done in lines 20 and 21. Initially the reference is an
+ instance of <classname>Object</classname>. However, to invoke a method on the servant object, you need to
+ narrow this instance to an instance of the <interfacename>DemoInterface</interfacename> interface. This is
+ shown in line 21.
+ </para>
+ <para>
+ Once we have a reference to this servant object, we can start a transaction (line 23), perform a unit of work
+ (line 25) and commit the transaction (line 27).
+ </para>
+ <example>
+ <title>DemoClient</title>
+ <programlisting role="JAVA" language="Java"><xi:include href="extras/DemoClient.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>Sequence diagram</title>
+ <para>
+ The sequence diagram illustrates the method invocations that occur between the client and server. The
+ following aspects are important:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ You do not need to pass the transactional context as a parameter in method <methodname>work</methodname>,
+ since you are using implicit context propagation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Specifying the use of interposition when the client and server processes are started, by using appropriate
+ filters and interceptors, creates an interposed coordinator that the servant process can use, negating any
+ requirement for cross-process invocations. The interposed coordinator is automatically registered with the
+ root coordinator at the client.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The resource that commits or rolls back modifications made to the transactional object is associated, or
+ registered, with the interposed coordinator.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <methodname>commit</methodname> invocation in the client process calls the root coordinator. The root
+ coordinator calls the interposed coordinator, which in turn calls the
+ <methodname>commit_one_phase</methodname> method for the resource.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <figure>
+ <title>Sequence Diagram</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/sequence-diagram.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>Sequence diagram</para>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section>
+ <title>Interpretation of output</title>
+ <para>
+ The server process first stringifies the servant instance, and writes the servant IOR to a temporary file. The
+ first line of output is the sanity check that the operation was successful.
+ </para>
+ <para>
+ In this simplified example, the coordinator object has only a single registered resource. Consequently, it
+ performs a <methodname>commit_one_phase</methodname> operation on the resource object, instead of performing a
+ <methodname>prepare</methodname> operation, followed by a <methodname>commit</methodname> or
+ <methodname>rollback</methodname>.
+ </para>
+ <para>
+ The output is identical, regardless of whether implicit context propagation or interposition is used, since
+ interposition is essentially performance aid. Ordinarily, you may need to do a lot of marshalling between a
+ client and server process.
+ </para>
+ <example>
+ <title>Server output</title>
+ <screen>
+Object reference written to file
+commit_one_phase called
+ </screen>
+ </example>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title>Default settings</title>
+ <para>
+ These settings are defaults, and you can override them at run-time by using property variables, or in the
+ properties file in the <filename>etc/</filename> directory of the installation.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Unless a CORBA object is derived from
+ <interfacename>CosTransactions::TransactionalObject</interfacename>,you do not need to propagate any
+ context. In order to preserve distribution transparency, JBossTS defaults to always propagating a
+ transaction context when calling remote objects, regardless of whether they are marked as transactional
+ objects. You can override this by setting the
+ <varname>com.arjuna.ats.jts.alwaysPropagateContext</varname> property variable to <literal>NO</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If an object is derived from <interfacename>CosTransactions::TransactionalObject</interfacename>, and no
+ client context is present when an invocation is made, JBossTS transmits a null context. Subsequent
+ transactions begun by the object are top-level. If a context is required, then set the
+ <varname>com.arjuna.ats.jts.needTranContext</varname> property variable to <literal>YES</literal>, in which
+ case JBossTS raises the <systemitem>TransactionRequired</systemitem> exception.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ JBossTS needs a persistent object store, so that it can record information about transactions in the event of
+ failures. If all transactions complete successfully, this object store has no entries. The default location
+ for this must be set using the <varname>ObjectStoreEnvironmentBean.objectStoreDir</varname> variable in the
+ properties file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you use a separate transaction manager for <interfacename>Current</interfacename>, its location is obtained
+ from the <filename>CosServices.cfg</filename> file. <filename>CosServices.cfg</filename> is located at runtime
+ by the <varname>OrbPortabilityEnvironmentBean</varname> properties <varname>initialReferencesRoot</varname>
+ and <varname>initialReferencesFile</varname>. The former is a directory, defaulting to the current working
+ directory. The latter is a file name, relative to the directory. The default value is
+ <literal>CosServices.cfg</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Checked transactions are not enabled by default. This means that threads other than the transaction creator may
+ terminate the transaction, and no check is made to ensure all outstanding requests have finished prior to
+ transaction termination. To override this, set the <varname>JTSEnvironmentBean.checkedTransactions</varname>
+ property variable to <literal>YES</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <note>
+ <para>
+ As of JBossTS 4.5, transaction timeouts are unified across all transaction components and are controlled by
+ ArjunaCore. The old JTS configuration property com.arjuna.ats.jts.defaultTimeout still remains but is
+ deprecated.
+ </para>
+ </note>
+ <para>
+ if a value of <literal>0</literal> is specified for the timeout of a top-level transaction, or no timeout is
+ specified, JBossTS does not impose any timeout on the transaction. To override this default timeout, set the
+ <varname>CoordinatorEnvironmentBean.defaultTimeout</varname> property variable to the required timeout value
+ in seconds.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
</chapter>
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/DemoClient.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/DemoClient.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/DemoClient.java 2010-12-07 05:57:58 UTC (rev 36225)
@@ -0,0 +1,34 @@
+1 import Demo.*;
+2 import java.io.*;
+3 import com.arjuna.orbportability.*;
+4 import com.arjuna.ats.jts.*;
+5 import org.omg.CosTransactions.*;
+6 import org.omg.*;
+7
+8 public class DemoClient
+9 {
+10 public static void main(String[] args)
+11 {
+12 try
+13 {
+14 ORB myORB = ORB.getInstance("test").initORB(args, null);
+15 RootOA myOA = OA.getRootOA(myORB).myORB.initOA();
+16
+17 ORBManager.setORB(myORB);
+18 ORBManager.setPOA(myOA);
+19
+20 Services serv = new Services(myORB);
+21 DemoInterface d = (DemoInterface) DemoInterfaceHelper.narrow(serv.getService("DemoObjReference"));
+22
+23 OTS.get_current().begin();
+24
+25 d.work();
+26
+27 OTS.get_current().commit(true);
+28 }
+29 catch (Exception e)
+30 {
+31 System.err.println(e);
+32 }
+33 }
+34 }
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/DemoServer.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/DemoServer.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/DemoServer.java 2010-12-07 05:57:58 UTC (rev 36225)
@@ -0,0 +1,32 @@
+1 import java.io.*;
+2 import com.arjuna.orbportability.*;
+3
+4 public class DemoServer
+5 {
+6 public static void main (String[] args)
+7 {
+8 try
+9 {
+10 ORB myORB = ORB.getInstance("test").initORB(args, null);
+11 RootOA myOA = OA.getRootOA(myORB).myORB.initOA();
+12
+13 ORBManager.setORB(myORB);
+14 ORBManager.setPOA(myOA);
+15
+16 DemoImplementation obj = new DemoImplementation();
+17
+18 myOA.objectIsReady(obj);
+19
+20 Services serv = new Services(myORB);
+21 serv.registerService(myOA.corbaReference(obj), "DemoObjReference", null);
+22
+23 System.out.println("Object published.");
+24
+25 myOA.run();
+26 }
+27 catch (Exception e)
+28 {
+29 System.err.println(e);
+30 }
+31 }
+32 }
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/example-DemoResource.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/example-DemoResource.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/example-DemoResource.java 2010-12-07 05:57:58 UTC (rev 36225)
@@ -0,0 +1,35 @@
+1 import org.omg.CosTransactions.*;
+2 import org.omg.CORBA .SystemException;
+3
+4 public class DemoResource extends org.omg.CosTransactions .ResourcePOA
+5 {
+6 public Vote prepare() throws HeuristicMixed, HeuristicHazard,
+7 SystemException
+8 {
+9 System.out.println("prepare called");
+10
+11 return Vote.VoteCommit;
+12 }
+13
+14 public void rollback() throws HeuristicCommit, HeuristicMixed,
+15 HeuristicHazard, SystemException
+16 {
+17 System.out.println("rollback called");
+18 }
+19
+20 public void commit() throws NotPrepared, HeuristicRollback,
+21 HeuristicMixed, HeuristicHazard, SystemException
+22 {
+23 System.out.println("commit called");
+24 }
+25
+26 public void commit_one_phase() throws HeuristicHazard, SystemException
+27 {
+28 System.out.println("commit_one_phase called");
+29 }
+30
+31 public void forget() throws SystemException
+32 {
+33 System.out.println("forget called");
+34 }
+35 }
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/example-idl-interface.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/example-idl-interface.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/example-idl-interface.java 2010-12-07 05:57:58 UTC (rev 36225)
@@ -0,0 +1,13 @@
+#include <idl/CosTransactions.idl>
+#pragma javaPackage ""
+
+
+module Demo
+{
+ exception DemoException {};
+
+ interface DemoInterface : CosTransactions::TransactionalObject
+ {
+ void work() raises (DemoException);
+ };
+};
\ No newline at end of file
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/transactional-implementation.java
===================================================================
--- labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/transactional-implementation.java (rev 0)
+++ labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/extras/transactional-implementation.java 2010-12-07 05:57:58 UTC (rev 36225)
@@ -0,0 +1,28 @@
+1 import Demo.*;
+2 import org.omg.CosTransactions.*;
+3 import com.arjuna.ats.jts.*;
+4 import com.arjuna.orbportability.*;
+5
+6 public class DemoImplementation extends Demo.DemoInterfacePOA
+7 {
+8 public void work() throws DemoException
+9 {
+10 try
+11 {
+12
+13 Control control = OTSManager.get_current().get_control();
+14
+15 Coordinator coordinator = control.get_coordinator();
+16 DemoResource resource = new DemoResource();
+17
+18 ORBManager.getPOA().objectIsReady(resource);
+19 coordinator.register_resource(resource);
+20
+21 }
+22 catch (Exception e)
+23 {
+24 throw new DemoException();
+25 }
+26 }
+27
+28 }
Added: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/sequence-diagram.png
===================================================================
(Binary files differ)
Property changes on: labs/jbosstm/trunk/ArjunaJTS/docs/ArjunaJTS_Development_Guide/en-US/images/sequence-diagram.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
More information about the jboss-svn-commits
mailing list