<?xml version="1.0"?>
<!--
  JBoss, Home of Professional Open Source
  Copyright 2006, JBoss Inc., and others contributors as indicated 
  by the @authors tag. All rights reserved. 
  See the copyright.txt in the distribution for a
  full listing of individual contributors. 
  This copyrighted material is made available to anyone wishing to use,
  modify, copy, or redistribute it subject to the terms and conditions
  of the GNU Lesser General Public License, v. 2.1.
  This program is distributed in the hope that it will be useful, but WITHOUT A 
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 
  PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
  You should have received a copy of the GNU Lesser General Public License,
  v.2.1 along with this distribution; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 
  MA  02110-1301, USA.
  
  (C) 2005-2006,
  @author JBoss Inc.
-->
<page title="Arjuna Technologies Limited: Arjuna+JBoss Transaction Service Examples: RMI-IIOP" rootpath="../..">
    <header>
        Arjuna+JBoss Transaction Service Examples: RMI-IIOP
    </header>
    <content>
        <navigation>
            <links include="includes/www_arjuna_com_navigation.xml"/>
            <links include="includes/jbossatx_navigation.xml"/>
        </navigation>
        <area title="RMI-IIOP Example">
            <html>
                <P STYLE="margin-bottom: 0cm">The purpose of this example is to show
                    that it is possible to propagate transactional context to RMI
                    services (via RMI over IIOP) using the Arjuna+JBoss product. Please
                    note that there is a change required to the JBoss installation for
                    this example to work, it is outlined below.</P>
                <P STYLE="margin-bottom: 0cm">
                    <BR/>
                </P>
                                <P STYLE="margin-bottom: 0cm">The JDK ORB delegation code uses a
                                    ShutdownUtil class which assumes that the ORB being used is the
                                    Java ORB. As this is not the case the JDK ORB delegation code
                                    needs to be instructed to use a different ShutdownUtil class,
                                    this can be done by including the
                                    <FONT SIZE="2" STYLE="font-size: 9pt">
                                        <FONT FACE="Courier, monospace">orb-fix.jar</FONT>
                                    </FONT>
                                    JAR (located in lib/ext) in the
                                    <FONT SIZE="2" STYLE="font-size: 9pt">
                                        <FONT FACE="Courier, monospace">jboss-3.2.2/server/all/lib/</FONT>
                                    </FONT>
                                    directory and setting the JAVA_OPTS environment variable to
                                    include:
                                    <BR/>
                                    <BR/>
                                </P>
                                <P STYLE="margin-bottom: 0cm">
                                    <FONT SIZE="2" STYLE="font-size: 9pt">
                                        <FONT FACE="Courier, monospace">-Djavax.rmi.CORBA.UtilClass=com.arjuna.ats.orbfix.JacORBUtilDelegate
                                        </FONT>
                                    </FONT>
                                </P>
                                <P>
                                        <BR/>NB The source code for the ORB
                                        fix is included in the example in the
                                        <FONT SIZE="2" STYLE="font-size: 9pt">
                                            <FONT FACE="Courier, monospace">orbfix</FONT>
                                        </FONT>
                                        directory.
                                </P>
                <P STYLE="margin-bottom: 0cm">
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">
                    This example
                        isn't intended to show users how RMI over IIOP works (see
                        http:
                        <A HREF="../../../../">//www.javasoft.com/</A> for information),
                        neither does it cover in detail how to use RMI-IIOP with JBoss (see
                        <A HREF="http://www.jboss.org/">http://www.jboss.org</A> for more
                        information). This is a very simple example which shows that
                        transactional context can be propagated over RMI-IIOP invocations. It
                        is built up of three parts: i) an RMI-IIOP server, ii) a JBoss
                        Enterprise Java Bean (EJB) and iii) a simple JBoss client. These
                        parts are discussed in detail in the following section.  The
                        following diagram shows how the parts interact with one another:
                </P>
                <P STYLE="margin-bottom: 0cm">
                    <IMG SRC="images/overview.gif" NAME="Graphic2" ALIGN="LEFT" WIDTH="334" HEIGHT="334" BORDER="0"/>
                        <BR CLEAR="LEFT"/>
                        <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">
                        As the diagram shows the JBoss client invokes the 'invoke' method on the
                        TestBean EJB.  Within this method a transaction is started and
                        terminated, within the scope of this transaction the 'simpleTest'
                        method of the RMI object is invoked.  The example shows that the
                        transaction's context is propagated from the EJB to the RMI object.
                        <BR/>
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">
                        <B>RMI-IIOP
                            Server (RemoteServer)</B>
                </P>
                <P STYLE="margin-bottom: 0cm">
                            The RMI-IIOP server is a simple RMI server which creates an instance of
                            the Java RMI object implementation
                            (
                            <FONT SIZE="2" STYLE="font-size: 9pt">
                                <FONT FACE="Courier, monospace">com.arjuna.ats.tests.rmiiiop.server.impls.ServerRemoteImpl</FONT>
                            </FONT>)
                            and binds it to the CORBA naming service within the JBoss server.
                            The Java RMI object is very simple and only has one method 'invoke'.
                            This method simply outputs the UID of the transaction associated with
                            the current thread (i.e. the current transactional context).
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">
                        <B>JBoss EJB
                            (com.arjuna.ats.tests.rmiiiop.ejb.TestBean)</B>
                </P>
                <P STYLE="margin-bottom: 0cm">This is a very basic Enterprise Java
                    Bean (EJB) which has one operation: simpleTest.  This method simply
                    starts a transaction, outputs the transaction UID, calls the 'invoke'
                    method on the RMI object and then commits the transaction.
                    <BR/>
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">
                        <B>Simple
                            JBoss Client</B>
                </P>
                <P STYLE="margin-bottom: 0cm">This is a simple JBoss client which
                    looks up the EJB and invokes the 'simpleTest' operation.
                    <BR/>
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">
                        <B>Steps to
                            take before running the example</B>
                </P>
                <P STYLE="margin-bottom: 0cm">
                        Before running the example the following actions must be performed:
                            <BR/>
                    <BR/>
                </P>
                <OL>
                    <LI>
                        <P STYLE="margin-bottom: 0cm">
                                Append the Apache ANT 1.5.x bin directory to your path, e.g.
                                    <BR/>
                            <BR/>
                        </P>
		    </LI>
                </OL>
                <P STYLE="margin-bottom: 0cm">
                    Windows:
                        <FONT SIZE="2" STYLE="font-size: 9pt">
                            <FONT FACE="Courier, monospace">set
                                PATH=%PATH$;$ANT_HOME\bin\</FONT>
                        </FONT>
                </P>
                <P STYLE="margin-bottom: 0cm">
                        Unix:
                            <FONT SIZE="2" STYLE="font-size: 9pt">
                                <FONT FACE="Courier, monospace">export
                                    PATH=$PATH:$ANT_HOME/bin/</FONT>
                            </FONT>
                            <BR/>
                    <BR/>
                </P>
                <OL START="2">
                    <LI>
                        <P STYLE="margin-bottom: 0cm">
                            Ensure the JAVA_HOME property is pointing to a valid JDK 1.4.x home
                                directory.
                        </P>
		    </LI>
                        <LI>
                            <P STYLE="margin-bottom: 0cm">
                                Ensure
                                    the RMICTool JAR (in the lib/ext directory) is either in the Java
                                    classpath or exists in the ANT lib directory.
                            </P>
			</LI>
                            <LI>
                                <P STYLE="margin-bottom: 0cm;">
                                   The
                                        Arjuna+JBoss product must be installed correctly and have a active
                                        licence.
                                </P>
			    </LI>

                </OL>
                <OL START="4">
                    <LI>
                        <P STYLE="margin-bottom: 0cm">
                            <SPAN STYLE="font-weight: medium">
                                Edit
                                    the file example/rmi-iiop-example.properties to suit your
                                    environment. A description of each of the properties is listed
                                    below.
                                    <BR/>
                            </SPAN>
                            <BR/>
                        </P>
		    </LI>
                </OL>
                                <P>
                                                <FONT FACE="Courier, monospace" SIZE="2">
                                                    jboss.jnp.url
                                                </FONT>
                                This is the provider URL for the JBoss server (e.g.
                                    jnp://127.0.0.1:1099).</P>
                                <P STYLE="text-decoration: none">
                                    <FONT FACE="Courier, monospace" SIZE="2">
					jboss.home
				    </FONT>
                                The home directory of the JBoss server with Arjuna+JBoss
                                    installed (e.g. /opt/jboss-3.2.2/)</P>
                                <P>
                                        <FONT FACE="Courier, monospace">
                                            <FONT SIZE="2">arjunats.home</FONT>
                                        </FONT>
                                The home directory of the Arjuna Transaction Service
                                    installation (e.g. /opt/arjuna/arjunajboss-1.0/ats-3.1/)</P>
                                <P>
                                        <FONT SIZE="2">
                                            <FONT FACE="Courier, monospace">
                                                jboss.poa.addr
                                            </FONT>
                                        </FONT>
                                This is the address of the JBoss POA including port (e.g.
                                    127.0.0.1:3528)</P>
                <P STYLE="margin-bottom: 0cm">
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">
                        <B>Running
                            the example</B>
                </P>
                <P STYLE="margin-bottom: 0cm">
                    <SPAN STYLE="font-weight: medium">
                        To run the example simply perform the following steps:
                            <BR/>
                    </SPAN>
                    <BR/>
                </P>
                <OL>
                    <LI>
                        <P STYLE="margin-bottom: 0cm">
                            Start the Arjuna+JBoss server by going into the jboss-3.2.2/bin directory
                                and running
                                <BR/>
                            <BR/>
                        </P>
		    </LI>
                </OL>
                <P STYLE="margin-left: 2cm; margin-bottom: 0cm">Windows:
                    <FONT SIZE="2" STYLE="font-size: 9pt">
                        <FONT FACE="Courier, monospace">run.bat
                            -c all</FONT>
                    </FONT>
                </P>
                <P STYLE="margin-left: 2cm; margin-bottom: 0cm">Unix:
                    <FONT SIZE="2" STYLE="font-size: 9pt">
                        <FONT FACE="Courier, monospace">./run.sh
                            -c all</FONT>
                        <BR/>
                    </FONT>
                    <BR/>
                </P>
                <OL START="2">
                    <LI>
                        <P STYLE="margin-bottom: 0cm">Deploy the EJB into JBoss simply
                            by going into the example/ directory and running
                            <BR/>
                            <BR/>
                        </P>
		    </LI>
                </OL>
                <P STYLE="margin-left: 2cm; margin-bottom: 0cm">
                    <FONT SIZE="2" STYLE="font-size: 9pt">
                        <FONT FACE="Courier, monospace">ant
                            jboss.deploy
                            <BR/>
                        </FONT>
                    </FONT>
                    <BR/>
                </P>
                <OL START="3">
                    <LI>
                        <P STYLE="margin-bottom: 0cm">Once the JBoss server has started
                            successfully and the EJB has been deployed, start the RMI-IIOP
                            server by going into the example/ directory and running
                            <BR/>
                            <BR/>
                        </P>
		    </LI>
                </OL>
                <P STYLE="margin-left: 2cm; margin-bottom: 0cm">
                    <FONT SIZE="2" STYLE="font-size: 9pt">
                        <FONT FACE="Courier, monospace">ant
                            run.rmiserver
                            <BR/>
                        </FONT>
                    </FONT>
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">When the RMI-IIOP server has started
                    you will see the following output:
                    <BR/>
                    <BR/>
                </P>
                <P STYLE="margin-left: 2cm; margin-bottom: 0cm">
                    <FONT FACE="Courier, monospace">
                        <FONT SIZE="2" STYLE="font-size: 9pt">[java]
                            Remote Server: Ready....
                        </FONT>
                    </FONT>
                    <BR/>
                </P>
                <OL START="4">
                    <LI>
                        <P STYLE="margin-bottom: 0cm">
                            <SPAN STYLE="font-weight: medium">
                                Now simply run the JBoss client by going into the example/ directory and
                                    running
                                    <BR/>
                            </SPAN>
                            <BR/>
                        </P>
		    </LI>
                </OL>
                <P STYLE="margin-left: 2cm; margin-bottom: 0cm">
                    <SPAN STYLE="font-weight: medium">
                        <FONT SIZE="2" STYLE="font-size: 9pt">
                            <FONT FACE="Courier, monospace">ant
                                run.jbossclient
                                <BR/>
                            </FONT>
                        </FONT>
                    </SPAN>
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">
                    <SPAN STYLE="font-weight: medium">
                            You should see that the JBoss server outputs the following:
                            <BR/>
                    </SPAN>
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">
                    <FONT FACE="Courier, monospace">
                        <FONT SIZE="2" STYLE="font-size: 9pt">&lt;DATE&gt;
                            &lt;TIME&gt; INFO  [STDOUT] Client: Obtained a ref. to remote server.</FONT>
                    </FONT>
                </P>
                <P STYLE="margin-bottom: 0cm">
                    <FONT FACE="Courier, monospace">
                        <FONT SIZE="2" STYLE="font-size: 8pt">&lt;DATE&gt;
                            &lt;TIME&gt; INFO  [STDOUT] EJB-TX:TransactionImple : &lt;TRANSACTION
                            UID e.g. 7f000001:83c1:401fad92:7c&gt;
                            <BR/>
                        </FONT>
                    </FONT>
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">You should also see the following
                    output from the RMI-IIOP server:
                    <BR/>
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">
                    <FONT FACE="Courier, monospace">
                        <FONT SIZE="2" STYLE="font-size: 9pt">[java]
                            Worker: RMI/IIOP Server remote method invoke</FONT>
                    </FONT>
                </P>
                <P STYLE="margin-bottom: 0cm">
                    <FONT FACE="Courier, monospace">
                        <FONT SIZE="2" STYLE="font-size: 9pt">[java]
                            TX[&lt;THREAD NAME&gt;] : TransactionImple : &lt;TRANSACTION UID e.g.
                            7f000001:83c1:401fad92:7c&gt;
                            <BR/>
                        </FONT>
                    </FONT>
                    <BR/>
                </P>
                <P STYLE="margin-bottom: 0cm">The transaction UID outputted from the
                    JBoss server should match that of the RMI-IIOP server.  This shows
                    that the transactional context has been propagated from the JBoss
                    server to the RMI-IIOP server successfully.</P>
            </html>
        </area>
    </content>
    <footer/>
</page>

