You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fx-dev@ws.apache.org by da...@apache.org on 2006/02/10 01:03:27 UTC
svn commit: r376498 -
/webservices/kandula/branches/Kandula_1/xdocs/user-guide.html
Author: dasarath
Date: Thu Feb 9 16:03:26 2006
New Revision: 376498
URL: http://svn.apache.org/viewcvs?rev=376498&view=rev
Log:
updated to reflect the changes made to the code in Dec 05
Modified:
webservices/kandula/branches/Kandula_1/xdocs/user-guide.html
Modified: webservices/kandula/branches/Kandula_1/xdocs/user-guide.html
URL: http://svn.apache.org/viewcvs/webservices/kandula/branches/Kandula_1/xdocs/user-guide.html?rev=376498&r1=376497&r2=376498&view=diff
==============================================================================
--- webservices/kandula/branches/Kandula_1/xdocs/user-guide.html (original)
+++ webservices/kandula/branches/Kandula_1/xdocs/user-guide.html Thu Feb 9 16:03:26 2006
@@ -6,139 +6,119 @@
<H1>User Guide for Apache Kandula</H1>
<H2>Purpose</H2>
-<P align="justify">This tutorial provides a brief overview of the Kandula project
-and how to try out the provided examples. For a detail illustration on the
-design, please refer to the provided architecture documentation. For an overview , please refer to the "About Apache Kandula"</P>
-<H2>Running the provided samples</H2>
-<H3>Setup the TCP Monitor</H3>
-<P align="justify" >All examples and Kandula default endpoint configuration
-parameters given in %KANDULA_HOME%/conf/endpoints.conf assume that you are using the
-TCP monitor to monitor and redirect soap messages sent to port 8081 on localhost, to port 8080.</P>
-<H3>Configure Jakarta-Tomcat and deploy Axis</H3>
-<OL type=1>
- <LI >Install Jakarta-Tomcat.
- The samples have been tested on Jakarta-Tomcat-5.0.25.
- <LI >Deploy Apache Axis.
- Axis-1.2beta3 or later is required. </LI></OL>
-<H3>Build and deploy Kandula</H3>
-<OL type=1>
- <LI >
- <div align="left">Modify %KANDULA_HOME%/conf/jta.conf. The TransactionManagerGlueImpl
- property must be set to the fully qualified class name of the class
- implementing org.apache.ws.transaction.participant.j2ee.TransactionManagerGlue
- interface for the transaction manager that you plan to use. By default the
- property is set to use the sample implementation for JOTM.
- </div>
- <LI >
- <div align="left">If
- necessary, modify %KANDULA_HOME%/conf/endpoints.conf. The properties declared here
- configure the numerous endpoints of the coordination service and server
- runtime. The default values provided assume that services are available at
- http://localhost:8081/axis/services/...
- If you use normal settings for Catalina and Axis, you do not need to modify
- these properties.
- </div>
- <LI style="mso-list: l1 level1 lfo9; tab-stops: list .5in">
- <div align="left">To
- build the kandula-0.1-SNAPSHOT.jar,
- enter<BR clear=all>
- <BR clear=all>
- maven<BR clear=all>
- <BR
- clear=all>
- in %KANDULA_HOME%.</div>
- <LI>
- <div align="left">Copy the j2ee.jar, addressing.jar & jotm-*.jar files from %KANDULA_HOME%/target/lib to %CATALINA_HOME%/shared/lib. </div>
- <LI >
- <div align="left">*Move* all Axis jars in
- %CATALINA_HOME%/webapps/axis/WEB-INF/lib to %CATALINA_HOME%/shared/lib
-
- </div>
- <LI >
- <div align="left">Copy %KANDULA_HOME%/target/kandula-0.1-SNAPSHOT.jar
- to %CATALINA_HOME%/shared/lib.
-
- </div>
- <LI >
- <div align="left">Use
- the server-config.wsdd file provided in %KANDULA_HOME%/conf
- to deploy the services sited above.
- </div>
- <LI>
- <div align="left">Use
- the server-config.wsdd file provided in %KANDULA_HOME%/conf
- to deploy Kandula and WS-Addressing handlers. <BR>
- Note: Kandula
- implementation uses reference properties that must be configured with the
- WS-Addressing handler as illustrated in the provided server-config.wsdd file. The global type mappings
- provided in %KANDULA_HOME%/conf/server-config.wsdd are used by the WS-Addressing
- implementation and *must be* copied to the server-config.wsdd.
- </div>
- <LI>
- <div align="left">Copy %KANDULA_HOME%/conf/client-config.wsdd to %CATALINA_HOME%/webapps/axis/WEB-INF/classes. Modify the
- client-config.wsdd copied to %CATALINA_HOME%/webapps/axis/WEB-INF/classes to deploy the
- org.apache.ws.transaction.participant.j2ee.handler.TransactionHandler
- on request flow. Also remove the org.apache.ws.transaction.participant.standalone.handler.TransactionHandler
- used by standalone clients. The modified client-config.wsdd is shown below. </div>
- </LI>
-</OL>
-<P><source><pre>
-<deployment ...>
- <globalConfiguration>
- <requestFlow>
- <handler type="java:org.apache.axis.message.
- addressing.handler.AddressingHandler" />
- <handler type="java:org.apache.ws.transaction.participant.
- j2ee.handler.TransactionHandler"/>
- ...
- </requestFlow>
- <responseFlow>
- <handler type="java:org.apache.axis.message.addressing.
- handler.AddressingHandler" />
- ...
- </responseFlow>
- ...
- </globalConfiguration>
-...
-</deployment>
-</pre></source></P>
-<H3>Build the samples</H3>
-<OL style="MARGIN-TOP: 0in" type=1>
- <LI >To
- build the sample(s) enter,<BR clear=all><BR clear=all>ant dist<BR clear=all><BR
- clear=all>in %KANDULA_HOME%/src/samples </LI></OL>
-<H3>Run the Interop sample</H3>
-<P >This sample shows how a standalone client may access a
-transactional web service. To try it out,</P>
-<OL style="MARGIN-TOP: 0in" type=1>
- <LI >Copy the %KANDULA_HOME%/src/samples/interop/build/interop.jar to
- %CATALINA_HOME%/webapps/axis/WEB-INF/lib
- <LI >Use
- the deploy.wsdd
- in %KANDULA_HOME%/src/samples/interop to deploy the service in
- Axis.
- <LI >Copy the client-config.wsdd to %KANDULA_HOME%/src/samples/interop/ . ( To deploy addressing and Transaction handlers at the client side.)
- <LI>Run
- the provided JUnit test cases by entering,<BR
- clear=all><BR clear=all>ant test<BR clear=all><BR
- clear=all>in %KANDULA_HOME%/src/samples/interop</LI>
-</OL>
-<p> </p>
-<H2>Using Kandula with different JTA implementations</H2>
-<P align="left">Kandula architecture has been designed so that it may be used
-with any JTA implementation provided that it implements the org.apache.ws.transaction.participant.j2ee.TransactionManagerGlue
-interface. Two sample implementations of this interface for JOTM (version 1.4.3
-or later; version 1.5.3 is preferred but this implementation does not take
-advantage of XATerminator
-provided in this later version of JOTM) and JBoss
-transaction manager (JBoss-4.0.0RC1 or later) have been provided under %KANDULA_HOME%/src/java/org/apache/ws/transaction/participant/j2ee.</P>
-<P align="left" >In general given a transaction manager, the user should first
-determine whether it supports JCA 1.5 transaction inflow mechanism. If so, it is
-generally possible to come up with an implementation for the above interface. It
-may not be possible to do so otherwise.</P>
-<P align="left" >Lastly, before the Maven build is done (see below), the TransactionManagerGlueImpl
-property in %KANDULA_HOME%/conf/jta.conf must be set to the fully qualified
-class name of the class implementing org.apache.ws.transaction.participant.j2ee.TransactionManagerGlue
-interface for the transaction manager used by the application server
-runtime.</P>
+<P>Describe how to deploy Apache Kandula and run the provided sample applications.</P>
+<H2>Introduction</H2>
+<p>Presently Apache Kandula has 2 branches. The svn trunk named "Kandula2" runs on Apache Axis2. Kandula_1 branch
+runs on "Axis 1.x" (henceforth referred to as Apache Axis). Both branches now support the nightly builds of respective Axis flavours.</p>
+<H2>Kandula2 branch</H2>
+
+<H2>Kandula_1 branch</H2>
+<H3>How to download and build</H3>
+<ol>
+<LI>Checkout Kandula_1 from the svn repository using an svn client at the following URL:
+<a href="https://svn.apache.org/repos/asf/webservices/kandula/branches/Kandula_1/">https://svn.apache.org/repos/asf/webservices/kandula/branches/Kandula_1/</a>.
+Let us call the directory to where you checked out Kandula_1, <tt>KANDULA_HOME</tt>.</LI>
+<li>Download and install Apache Tomcat. (5.0 or later required).</li>
+<li>Download and install Apache Axis (1.3 or later required).</li>
+<li>Download and install Apache Maven 1.x (2.0 not supported).</li>
+<li>Download and install Apache Ant (1.6.5 or later).</li>
+<li>Set the kandula.context property in <tt>%KANDULA_HOME%/src/conf/kandula.properties</tt>, to the context under which
+services are deployed in axis. Normally this is: <tt>http://localhost:8080/axis/services/</tt></li>
+<li>Build Kandula using Maven. Use the command <tt>maven</tt> in <tt>%KANDULA_HOME</tt>. This will create the directory
+<tt>%KANDULA_HOME%/target</tt>. You will find the <tt>kandula-0.2-SNAPSHOT.jar</tt> along with all other required <tt>*.jar</tt>
+files in the directory <tt>%KANDULA_HOME%/target/lib</tt>.</li>
+<li>To build the sample applications, move to each one of the directories in <tt>%KANDULA_HOME%/src/samples/</tt>
+and use the command <tt>ant dist</tt>.</li>
+</ol>
+
+<h3>How to deploy</h3>
+<ol>
+<li>Move all Apache Axis jars from <tt>%AXIS_DEPLOY%/WEB-INF/lib</tt> to <tt>%TOMCAT_HOME%/shared/lib</tt>.</li>
+<li>Move all <tt>geronimo-*.jar</tt> files, <tt>addressing-SNAPSHOT.jar</tt> and <tt>kandula-0.2-SNAPSHOT.jar</tt> to <tt>%TOMCAT_HOME%/shared/lib</tt>.</li>
+<li>Copy the <tt>*.jar</tt> file in the <tt>build</tt> directory of each sample application to <tt>%AXIS_DEPLOY%/WEB-INF/lib</tt>.</li>
+<li>Copy the <tt>server-config.wsdd</tt> file in <tt>%KANDULA_HOME%/src/conf/</tt> to <tt>%AXIS_DEPLOY%/WEB-INF/</tt>.</li>
+<li>Copy the <tt>client-config.wsdd</tt> file in <tt>%KANDULA_HOME%/src/conf/</tt> to <tt>%AXIS_DEPLOY%/WEB-INF/classes</tt>.</li>
+<li>Start Tomcat. To assure that Kandula has been properly deployed, first list all deployed services
+in Axis from the "Happy Axis" page and then verify that you can view the WSDL of each service.</li>
+</ol>
+
+<h3>How to run the sample applications</h3>
+
+<p>Sample applications reside in the directory <tt>%KANDULA_HOME%/src/samples</tt>. The Axis artifacts necessary to deploy
+all the samples are also included in <tt>%KANDULA_HOME%/src/conf/server-config.wsdd</tt>. Hence unless you deploy the samples
+along with Kandula, you need to remove those elements from the <tt>server-config.wsdd</tt> file copied to <tt>%AXIS_DEPLOY%/WEB-INF/</tt> before you
+start Tomcat.</p>
+
+<h4>How to setup the TCP sniffer</h4>
+<p>The default configuration in Kandula assumes that you will use a TCP sniffer such as the "tcpmon" tool
+that comes with Apache Axis to monitor TCP traffic while running the sample applications. We also
+assume that Tomcat would be run on port <tt>8080</tt> and services in Axis are deployed under the URL:
+<tt>http://localhost:8080/axis/services/</tt>. Hence, to facilitate monitoring of traffic, all Stubs
+in Kandula forward messages that would otherwise be forwarded to port 8080 to port 8081.</p>
+<p>Therefore, inorder to run
+the samples (or any other application that uses Kandula in the default setting) you MUST forward port 8081
+of your local machine to port 8080.</p>
+<p>You can change this behaviour by editing the WSDL files in <tt>%KANDULA_HOME%/src/schema/</tt>
+and rebuilding Kandula thereafter.</p>
+
+<h4>Test-suite1</h4>
+<p>This sample application demostrates how to use Kandula to initiate and terminate transactions using the
+WS-AtomicTransaction protocol. It also demostrates the behaviour of Kandula under a number of failure scenarios.
+Note that we use pseudo XAResouces instead of actual applications such as Databases, Messaging etc. to simplify
+the testing process. Hence the application explicitly enlists all XAResources used in operations. This would
+not be the case with real applications however. The container would normally takecare of this for you,
+transparently.</p>
+
+<p>The most important aspect of this sample application is that it demostrates how Kandula
+can be used to expose transactional resources in a J2EE environment via the web services transaction management
+framework. After the revision of code in December 2005, Kandula_1 now supports ONLY the "Geronimo" Transaction Manager.
+The required jars are automatically downloaded by Maven during the build process.</p>
+
+<p>To run the sample, first ensure that the transaction handler used in your <tt>%AXIS_DEPLOY%/WEB-INF/classes/client-config.wsdd</tt>
+is <tt>org.apache.kandula.geronimo.TxHandler</tt>. Next open up the JUnit test case provided in the <tt>src</tt> directory
+in your favourite IDE. This file contains a number of test cases. Each test case should be run on its own. If you run
+a number of test cases this would result in a whole lot of messages which would be rather difficult to interpret.
+Also note that some of the test scenarios are positive tests while some others are negative. A short description of
+the success criteria of most of the test cases can be found in the <tt>success-criteria.txt</tt> file in <tt>%KANDULA_HOME%/src/samples/test-suite1/</tt>.
+To run the test cases use the standard JUnit test harness of your IDE.</p>
+
+<h4>InteropIBM</h4>
+
+<p>The objective of this sample application is to test Kandula against IBM WS-AtomicTransaction implementation for
+interoperability. For details on interoperability test please refer to the documentation available from: <a href="http://wsi.alphaworks.ibm.com:8080/interop/index.html">http://wsi.alphaworks.ibm.com:8080/interop/index.html</a>
+. We suggest that you read through this specification before moving on since some of the terminology is explained in the
+specification.</p>
+
+<p>The sample allows you to exercies Kandula in both IA (Initiator Application) and PA (Participant Application) configurations.
+We have successfully tested Kandula in IA role against the IBM in PA role for all scenarios except those that involve
+WS-Security. Testing under the opposite configuration is still under way. From the tests carried out thus far, Kandula in PA
+roles interoperates with IBM successfully in all scenarios upto Section 5.0 of test scenario specification.</p>
+
+<p>To run this sample, you need to use <tt>org.apache.kandula.coordinator.at.TxHandler</tt> in your <tt>%AXIS_DEPLOY%/WEB-INF/classes/client-config.wsdd</tt>.
+Most importantly you MUST have an externally visible URL for your web container. If not, you may setup and HTTP tunnel. However,
+in this case you must set the <tt>kandula.context</tt> property to the externally visible URL. If neither option is
+available you may still run the sample using Kandula in both IA and PA configurations simultaniously. The resulting
+message exchanges SHOULD still comply with the documented success criteria.</p>
+
+<p>Further, in this particular scenario, the Kandula Stubs are pre-configured to forward any messages addressed to
+<tt>http://wsi.alphaworks.ibm.com:8080/</tt> to <tt>http://localhost:8082/</tt>. This allows you to monitor all outgoing
+traffic. So before you run the sample forward the port 8082 of your local machine to <tt>http://wsi.alphaworks.ibm.com:8080/</tt></p>
+
+<p>To test Kandula in PA role follow the steps below.</p>
+<ol>
+<li>Deploy the sample and start Tomcat. Ensure that InteropService is listed (along with its operations) under deployed
+services in Axis and that you are able to view the WSDL.</li>
+<li>Open the page <a href="http://wsi.alphaworks.ibm.com:8080/wstx/interop.jsp">http://wsi.alphaworks.ibm.com:8080/wstx/interop.jsp</a> in your web browser.</li>
+<li>Enter the URL of your "InteropService" as the participant destination. Here, if you want to monitor incoming traffic,
+change the port from 8080 to 8081 when entering the URL and forward port 8081 to 8080 as before.</li>
+<li>Select the test scenario you want to run. Do not select scenarios from Sections 5.0 or later since these have not
+been tested yet under this setting.</li>
+<li>Select run test.</li>
+</ol>
+
+<p>To test Kandula in IA role, deploy the sample application and setup the TCP sniffer as before.
+Thne open up the sample application in your favourite IDE. The code for exercising test scenarios is in <tt>InitiatorApp.java</tt>. You also need a test orchetrator
+for some of the scenarios. The test orchestrator can be found in <tt>ManInTheMiddle.java</tt>. Note that when using the test orchestrator you need to setup the TCP monitor differently.
+Due to the relative complexity of the process involved we do not document these steps any further. However, things can be
+figured out rather quickly by examining the source code.</p>
</BODY></HTML>
---------------------------------------------------------------------
To unsubscribe, e-mail: kandula-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: kandula-dev-help@ws.apache.org