ws-kandula-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r376498 - /webservices/kandula/branches/Kandula_1/xdocs/user-guide.html
Date Fri, 10 Feb 2006 00:03:27 GMT
Author: dasarath
Date: Thu Feb  9 16:03:26 2006
New Revision: 376498

updated to reflect the changes made to the code in Dec 05


Modified: webservices/kandula/branches/Kandula_1/xdocs/user-guide.html
--- 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>
-<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
-<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 
-      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 &amp; 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

-    on request flow. Also remove the

-    used by standalone clients. The modified client-config.wsdd is shown below. </div>
-  </LI>
-&lt;deployment ...&gt;
-    &lt;globalConfiguration&gt;
-        &lt;requestFlow&gt;
-            &lt;handler type=&quot;java:org.apache.axis.message.
-                addressing.handler.AddressingHandler&quot; /&gt;
-        	    &lt;handler type=&quot;
-        	        j2ee.handler.TransactionHandler&quot;/&gt;
-        				...        
-        &lt;/requestFlow&gt;
-        &lt;responseFlow&gt;
-               	&lt;handler type=&quot;java:org.apache.axis.message.addressing.
-               	    handler.AddressingHandler&quot; /&gt;
-               			...        
-        &lt;/responseFlow&gt;
-        	...  
-     &lt;/globalConfiguration&gt;
-<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>
-<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

-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

-interface for the transaction manager used by the application server 
+<P>Describe how to deploy Apache Kandula and run the provided sample applications.</P>
+<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>
+<LI>Checkout Kandula_1 from the svn repository using an svn client at the following
+<a href=""></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/</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>
+<h3>How to deploy</h3>
+<li>Move all Apache Axis jars from <tt>%AXIS_DEPLOY%/WEB-INF/lib</tt> to
+<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>
+<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>
+<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,
+<p>The most important aspect of this sample application is that it demostrates how
+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>
+<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=""></a>
+. We suggest that you read through this specification before moving on since some of the
terminology is explained in the
+<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
+<p>To run this sample, you need to use <tt></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></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></tt></p>
+<p>To test Kandula in PA role follow the steps below.</p>
+<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=""></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
+<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>
+<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></tt>. You also need a test orchetrator
+for some of the scenarios. The test orchestrator can be found in <tt></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>

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message