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 02:08:27 UTC
svn commit: r376523 - /webservices/kandula/site/user-guide.html
Author: dasarath
Date: Thu Feb 9 17:08:26 2006
New Revision: 376523
URL: http://svn.apache.org/viewcvs?rev=376523&view=rev
Log:
updated to reflect the changes made to code in Dec. 05
Modified:
webservices/kandula/site/user-guide.html
Modified: webservices/kandula/site/user-guide.html
URL: http://svn.apache.org/viewcvs/webservices/kandula/site/user-guide.html?rev=376523&r1=376522&r2=376523&view=diff
==============================================================================
--- webservices/kandula/site/user-guide.html (original)
+++ webservices/kandula/site/user-guide.html Thu Feb 9 17:08:26 2006
@@ -3,118 +3,144 @@
@import url("./style/maven-theme.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://ws.apache.org/" id="organizationLogo"><img alt="Apache Web Services" src="http://ws.apache.org/images/project-logo.jpg"></img></a><a href="http://ws.apache.org/ws-fx/kandula/" id="projectLogo"><span>Apache Kandula</span></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
Last published: 18 August 2005
- | Doc for 0.1-SNAPSHOT</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuKandula"><h5>Kandula</h5><ul><li class="none"><a href="user-guide.html">User Guide</a></li><li class="none"><a href="architecture-guide.html">Architecture Guide</a></li></ul></div><div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li class="none"><a href="index.html">About Apache Kandula</a></li><li class="collapsed"><a href="project-info.html">Project Info</a></li><li class="collapsed"><a href="maven-reports.html">Project Reports</a></li><li class="none"><a href="http://maven.apache.org/development-process.html" class="externalLink" title="External Link">Development Process</a></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentB
ox"><div class="section"><a name="User_Guide_for_Apache_Kandula"></a><h2>User Guide for Apache Kandula</h2><div class="subsection"><a name="Purpose"></a><h3>Purpose</h3><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></div><div class="subsection"><a name="Running_the_provided_samples"></a><h3>Running the provided samples</h3></div><div class="subsection"><a name="Setup_the_TCP_Monitor"></a><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></div><div class="subsection"><a name="Configure_Jakarta-Tomcat_and_deploy_Axis"></a><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><li>Deploy Apache Axis.
- Axis-1.2beta3 or later is required. </li></ol></div><div class="subsection"><a name="Build_and_deploy_Kandula"></a><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><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><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>
- <br clear="all"></br>
- maven<br clear="all"></br>
- <br clear="all"></br>
- in %KANDULA_HOME%.</div>
- </li><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><li>
- <div align="left">*Move* all Axis jars in
- %CATALINA_HOME%/webapps/axis/WEB-INF/lib to %CATALINA_HOME%/shared/lib
-
- </div>
- </li><li>
- <div align="left">Copy %KANDULA_HOME%/target/kandula-0.1-SNAPSHOT.jar
- to %CATALINA_HOME%/shared/lib.
-
- </div>
- </li><li>
- <div align="left">Use
- the server-config.wsdd file provided in %KANDULA_HOME%/conf
- to deploy the services sited above.
- </div>
- </li><li>
- <div align="left">Use
- the server-config.wsdd file provided in %KANDULA_HOME%/conf
- to deploy Kandula and WS-Addressing handlers. <br></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><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>
- <div class="source"><pre><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></pre></div>
- </p></div><div class="subsection"><a name="Build_the_samples"></a><h3>Build the samples</h3><ol style="MARGIN-TOP: 0in" type="1">
- <li>To
- build the sample(s) enter,<br clear="all"></br><br clear="all"></br>ant dist<br clear="all"></br><br clear="all"></br>in %KANDULA_HOME%/src/samples </li></ol></div><div class="subsection"><a name="Run_the_Interop_sample"></a><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><li>Use
- the deploy.wsdd
- in %KANDULA_HOME%/src/samples/interop to deploy the service in
- Axis.
- </li><li>Copy the client-config.wsdd to %KANDULA_HOME%/src/samples/interop/ . ( To deploy addressing and Transaction handlers at the client side.)
- </li><li>Run
- the provided JUnit test cases by entering,<br clear="all"></br><br clear="all"></br>ant test<br clear="all"></br><br clear="all"></br>in %KANDULA_HOME%/src/samples/interop</li>
-</ol><p> </p></div><div class="subsection"><a name="Using_Kandula_with_different_JTA_implementations"></a><h3>Using Kandula with different JTA implementations</h3><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></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2005, Apache Web Services</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
+ | Doc for 0.1-SNAPSHOT</div><div class="xright"></div><div class="clear"><hr></hr></div
+ div><div id="leftColumn"><div id="navcolumn"><div id="menuKandula"><h5>Kandula</h5><ul>
+ <li class="none"><a href="user-guide.html">User Guide</a></li>
+ <li class="none"><a href="architecture-guide.html">Architecture Guide</a></li></ul></div>
+ <div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li class="none">
+ <a href="index.html">About Apache Kandula</a></li><li class="collapsed">
+ <a href="project-info.html">Project Info</a></li><li class="collapsed">
+ <a href="maven-reports.html">Project Reports</a></li><li class="none">
+ <a href="http://maven.apache.org/development-process.html" class="externalLink" title="External Link">
+ Development Process</a></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy">
+ <img alt="Built by Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn">
+ <div class="contentBox"><div class="section"><a name="User_Guide_for_Apache_Kandula"></a>
+
+ <H1>User Guide for Apache Kandula</H1>
+<H2>Purpose</H2>
+<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 their 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 which 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). It is better to use the
+ same version of Axis on both ends (client/server) </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 of the sample 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. Further, different samples use different handlers. You
+ need to change your handler configuration as appropriate when you try out a particular
+ sample application.</p>
+
+<h4>How to setup the TCP sniffer</h4>
+<p>The default configuration of 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, do the following.</p>
+<ol><li>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>.
+</li>
+<li>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>.
+<li>To run the test cases use the standard JUnit test harness of your IDE.</li>
+</ol>
+<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 used in the following section 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 implementation 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 role interoperates with IBM successfully in all scenarios upto Section 5.0 of the 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 that we used 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. If you run into trouble, please shoot your questions to kandula-dev@ws.apache.org!</p>
+
+
+
+
+
+
+
+
+ </div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2005, Apache Web Services</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: kandula-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: kandula-dev-help@ws.apache.org