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 th...@apache.org on 2005/06/14 11:32:38 UTC
cvs commit: ws-fx/kandula/xdocs/img image001.gif image002.gif image003.gif image004.gif image005.gif image006.gif image007.gif image008.gif image009.gif image010.gif
thilina 2005/06/14 02:32:38
Modified: kandula/xdocs architecture-guide.html navigation.xml
user-guide.html
Added: kandula/xdocs index.html
kandula/xdocs/img image001.gif image002.gif image003.gif
image004.gif image005.gif image006.gif image007.gif
image008.gif image009.gif image010.gif
Log:
Adding the Architecture guide to Kandula xdocs + some more updates.
Revision Changes Path
1.2 +99 -7 ws-fx/kandula/xdocs/architecture-guide.html
Index: architecture-guide.html
===================================================================
RCS file: /home/cvs/ws-fx/kandula/xdocs/architecture-guide.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- architecture-guide.html 7 Jun 2005 11:57:16 -0000 1.1
+++ architecture-guide.html 14 Jun 2005 09:32:37 -0000 1.2
@@ -1,7 +1,99 @@
-<html>
-<head><title>Architecture Guide for Apache Kandula</title>
-</head>
-<body>
-<h1>Architecture Guide for Apache Kandula</h1>
-<h2>Coming Soon</h2>
-</body></html>
+
+<HTML>
+<HEAD><TITLE>Apache Kandula - Architecture Guide</TITLE>
+<style type="text/css">
+<!--
+.style1 {
+ font-size: x-small;
+ font-weight: bold;
+}
+-->
+</style>
+</HEAD>
+<BODY>
+
+<H1>Architectural design</H1>
+<P align="center"><img src="img/image001.gif" width="611" height="361"></P>
+<div align="center" class="style1">Figure 1 : Architectural design of the coordination service </div>
+ <P align="justify">A coordination service coordinates activities. Under the model depicted in figure 1, each activity is coordinated by its own coordinator. Henceforth the term coordinator will be used to refer to the individual runtime components that coordinate activities. The term coordination service will be used to refer to the aggregate of all component services such as the activation, registration etc. </P>
+<p align="justify">When a request is received at one of the endpoints, unless the request is for creating a new activity, in which case a new coordinator is created, it is simply passed on to the coordinator responsible for the activity concerned. The respective coordinator then handles the requested operation. As new activities are created and existing activities are terminated, coordinators also get created and destroyed. Thus at any given time, the number of active coordinators resident in the coordination service is equal to the number of activities coordinated by service. </p>
+<p align="justify">The coordination service maintains a central repository of all active coordinators. When a new request arrives at any of the endpoints, the activity identifier is used to lookup the coordinator coordinating the particular activity to dispatch the request. To facilitate this process, the coordination service uses activity identifier as a reference property [33] at all of its endpoints. Individual endpoints however may use additional reference properties depending on what is been handled and how. </p>
+<p align="justify">The activation and registration endpoints are defined by WS-Coordination specification. All other endpoints are defined by coordination type specific specification such WS- AtomicTransaction , WS- BusinessActivity etc. The activation endpoint allows new activities to be created. The registration endpoint allows participants to register for any activity (regardless of its type) coordinated by the service. The purpose of all other endpoints is to facilitate communication between participants and the coordination service based on specific coordination protocols. Hence are known as protocol services. The set of protocol services offered by the coordination service thus depends on the type of activities coordinated by the service. Presently, the implementation can only coordinate atomic transactions. Hence only protocol services supported by the service (completion and coordinator protocol services) are, those defined by WS- AtomicTransaction specification. </p>
+<p align="justify">When a new activity is created, the coordination service first determines its type: e.g. an atomic transaction, a business activity etc. It then creates a coordinator of appropriate kind to coordinate the activity. All coordinators are required to implement operations defined by WS-Coordination: e.g. create a coordination context for the activity, register participants etc. Additionally, each coordinator is required to support all operations required of it by the type of activity it coordinates. These operations are defined by the specifications that define those specific coordination types: e.g. the operations required of a coordinator coordinating atomic transactions are defined in the WS- AtomicTransaction specification. </p>
+<p align="justify">The design attempts to encapsulate the complexity of coordinating different types of activities (e.g. atomic transactions, business activities etc.) within a specialized set of coordinators while making use of inheritance and polymorphism to support common functions required of all coordinators by WS-Coordination. As a result the design can be extended to support new types of activities by adding new coordinators capable of handling the necessary protocols. </p>
+<p align="justify"> </p>
+<H2>Implementation status</H2>
+<p align="justify">Table 1 lists all operation presently supported by the coordination service. These operations may be implemented by a coordination service as either one-way operations or as request-response type operations. However, the support for one-way operations is mandatory (refer to the WSDL s given in the specifications). Additionally a coordination service may expose the same operations under request-response message pattern. The current implementation only supports request-response message pattern. </p>
+<p align="center" class="style1"> Table 1 : Operations implemented by the coordination service</p>
+<table align="center" cellpadding="0" cellspacing="0">
+ <tr>
+ <td width="86"><p align="center"><strong>Service </strong></p></td>
+ <td width="63"><p align="center"><strong>Defined by </strong></p></td>
+ <td width="182"><p align="center"><strong>WSDL Interface </strong></p></td>
+ <td width="286"><p align="center"><strong>Operation(s) </strong></p></td>
+ </tr>
+ <tr>
+ <td width="86"><p>Activation </p></td>
+ <td width="63"><p>WS-COOR </p></td>
+ <td width="182"><p>ActivationPortTypeRPC </p></td>
+ <td width="286"><p>createCoordinationContextOperation </p></td>
+ </tr>
+ <tr>
+ <td width="86"><p>Registration </p></td>
+ <td width="63"><p>WS-COOR </p></td>
+ <td width="182"><p>RegistrationPortTypeRPC </p></td>
+ <td width="286"><p>registerOperation </p></td>
+ </tr>
+ <tr>
+ <td width="86" rowspan="2"><p>Completion </p></td>
+ <td width="63" rowspan="2"><p>WS-AT </p></td>
+ <td width="182" rowspan="2"><p>CompletionPortTypeRPC </p></td>
+ <td width="286"><p>commitOperation </p></td>
+ </tr>
+ <tr>
+ <td>rollbackOperation </td>
+ </tr>
+ <tr>
+ <td width="86" rowspan="3"><p>Coordinator </p></td>
+ <td width="63" rowspan="3"><p>WS-AT </p></td>
+ <td width="182" rowspan="3"><p>CoordinatorPortTypeRPC </p></td>
+ <td width="286"><p>replayOperation </p></td>
+ </tr>
+ <tr>
+ <td>abortedOperation </td>
+ </tr>
+ <tr>
+ <td>readOnlyOperation </td>
+ </tr>
+</table>
+<p> </p>
+<H3>Server side</H3>
+<p align="center"><img src="img/image002.gif" width="573" height="664"></p>
+<p align="center" class="style1"> Figure 2 : The class diagram- coordination service (1) </p>
+<p align="justify">All coordinator instances must implement the WSCoordinator interface (see figure 2). This interface defines the basic requirements expected of any type of coordinator e.g. creation of coordination contexts, registration of participants, identifying the activity they coordinate etc. Coordination type specific interfaces: e.g. WSAtomicTransactionCoordinator , extend from WSCoordinator and define the requirements of particular coordination types, i.e. Atomic Transactions in this case. </p>
+<p align="justify">WSCoordinatorImpl is an abstract base class that implements the WSCoordinator interface. It also provides functions such as locking, required by all coordinators. All concrete classes, e.g. WSAtomicTransactionCoordinatorImpl , that implement a particular coordination type extend from WSCoordinatorImpl . WSCoordinatorImpl serves as an adaptor for its subclasses. </p>
+<p align="justify">The WSAtomicTransactionCoordinatorImpl implements the atomic transaction coordination type: for instance the method commit carries out the two-phase commit protocol. It also implements operations required by protocol services such as Completion and Coordinator [30]. </p>
+<p align="justify">The class CoordinationService shown in figure 3 is responsible for creating an appropriate coordinator for new or imported activities. It also allows local transactions (JTA) to be imported into the coordination service and to be coordinated as activities. For each activity whose coordination type is Atomic Transaction, the coordination service creates a new instance of the class WSAtomicTransactionCoordinatorImpl . For each local transaction, imported into the coordinator, it creates an instance of SurrogateWSAtomicTransactionCoordinator . </p>
+<p align="justify">The SurrogateWSAtomicTransactionCoordinator registers it self as a participant of the local transaction passed to its constructor and also implements the interface javax.Transaction.xa.XAResource (see appendix C). When the local transaction is committed or rolled back the class simply calls the corresponding methods of the WSAtomicTransactionCoordinatorImpl (the super class) inside its XAResource implementation to extend the scope of the two phase commit protocol carried out on local resources to participants of the atomic transaction. The class overrides the commit and rollback methods of the WSAtomicTransactionCoordinatorImpl . The overridden methods simply call the commit and rollback methods of the local transaction instead. This guarantees that the local transaction is committed (or rolled back) if the atomic transaction is terminated first. As a result even when the atomic transaction is terminated first, two-phase commit protocol is still carried out by the local transaction manager rather than the atomic transaction coordinator: i.e. WSAtomicTransactionCoordinatorImpl . </p>
+<p align="center"><img src="img/image003.gif" width="391" height="175"></p>
+<p align="center" class="style1"> Figure 3 : Class diagram - coordination service (2) </p>
+<p align="justify"> The CoordinationService class a singleton. Apart from creating new coordinators the class is also used in dispatching requests to respective coordinators by different service endpoints. The class maintains a hash map of all active coordinators, keyed by their activity identifiers. When a new request is received, the endpoint uses the reference properties to locate the activity identifier of the activity to which the request belongs. Then the getCoordinator method of CoordinationService is used to obtain a reference to the coordinator coordinating the activity. </p>
+<p align="justify"> </p>
+<h3>Client Side (Standalone)</h3>
+<p align="justify"> The TransactionManager class shown in following figure is used by standalone clients to demarcate transaction boundaries. The TransactionManager maintains the transaction context associated with each thread as part of its internal data structure. A thread's transaction context is either null or refers to a specific atomic transaction. Each transaction is encapsulated by a WSAtomicTransaction object, which can be used to perform operations which are specific to the target transaction, regardless of the calling thread's transaction context. The TransactionManager class is the web service equivalent of JTA javax.transaction.TransactionManager.</p>
+<p align="center"><img src="img/image004.gif" width="340" height="525"></p>
+<p align="center" class="style1"> Figure 4 : The class diagram- coordination service (3) </p>
+<p align="justify"> The WSAtomicTransactionHandler is responsible for flowing the executing thread's transaction context. It does so by checking with the TransactionManager whether the current thread has a transaction context whenever the Client Axis Engine calls it's invoke method on request flow [20]. If the thread has a transaction context it obtains the respective coordination context by calling the getCoordinationContext method of the WSAtomicTransaction object representing the particular transaction. The coordination context is then added to the SOAP header of the request message as stipulated by WS-Coordination. </p>
+<p> </p><!-- Have to redo this code snapshot using source & pre tags -->
+<p align="center"><img src="img/image005.gif" width="577" height="455"></p>
+<p align="center" class="style1"> Figure 5 : Usage scenario - a standalone client calling a transactional web service </p>
+<p> Figure 5, shows a standalone client that uses the implementation. The sequence diagram in figure 6 illustrates the depicted scenario. The client attempts to transfer a sum of money through a Bank service. The client first starts a new transaction by calling the begin method of the TransactionManager . This results in the creation of a new atomic transaction as shown in the sequence diagram. Within the transaction it invokes operations that perform a credit and a debit equal in amount to carry out the monetary transfer. Afterwards, the transaction is rolled back aborting the monetary transfer by calling the rollback method of the TransactionManager . </p>
+<p align="center"><img src="img/image006.gif" width="671" height="639"></p>
+<p align="center" class="style1"> Figure 6 : Sequence Diagram - a standalone client calling a transactional web service </p>
+<p align="center" class="style1"> </p>
+<h3>Client Side (J2EE)</h3>
+<p align="justify"> On the J2EE platform, clients use JTA to manage transactions. Hence there is no web service specific API for transaction management. In fact it is awkward to define such an API. Instead, when a client invokes a web service, the run-time implicitly exports the transaction context associated with the current thread as an atomic transaction. The middleware to augment J2EE runtime to perform this operation. </p>
+<p align="justify"> </p>
+<h2>Possible Future Extensions </h2>
+<p align="justify">In addition to supporting WS- BusinessActivity the present WS- AtomicTransaction implementation needs to be perfected to support numerous interoperability scenarios described in the specification.</p>
+<p align="justify"> </p>
1.3 +1 -1 ws-fx/kandula/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/ws-fx/kandula/xdocs/navigation.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- navigation.xml 8 Jun 2005 05:57:56 -0000 1.2
+++ navigation.xml 14 Jun 2005 09:32:37 -0000 1.3
@@ -3,7 +3,7 @@
<title>Kandula</title>
<body>
<menu name="Kandula">
- <item name="Simple User Guide" href="user-guide.html"/>
+ <item name="User Guide" href="user-guide.html"/>
<item name="Architecture Guide" href="architecture-guide.html"/>
</menu>
</body>
1.5 +84 -201 ws-fx/kandula/xdocs/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /home/cvs/ws-fx/kandula/xdocs/user-guide.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- user-guide.html 8 Jun 2005 07:09:22 -0000 1.4
+++ user-guide.html 14 Jun 2005 09:32:37 -0000 1.5
@@ -6,169 +6,12 @@
<H1>User Guide for Apache Kandula</H1>
<H2>Purpose</H2>
-<P>This tutorial provides a brief overview of the Kandula project
+<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.</P>
-<H2>Objectives</H2>
-<P>The Kandula project has two main objectives:</P>
-<OL type=1>
- <LI>Provide an open source
- implementation for the web services coordination and transaction management
- frameworks defined by WS-Coordination, WS-<SPAN
- >AtomicTransaction and WS-<SPAN
- >BusinessActivity.</li>
- <LI>Integrate existing open
- source JTA implementations (e.g. JOTM, JBoss,
- Geronimo, etc.) with the web services transaction management framework so that
- J2EE web services and clients may take part in atomic transactions while using
- JTA for transaction management. </LI></OL>
-<H2>Overview</H2>
-<P>Think of a hypothetical web service that provides banking
-services. The service provides 2 operations: a <SPAN >credit
-operation and a <SPAN
-style="FONT-SIZE: 9pt; mso-bidi-font-size: 12.0pt">debit
-operation. Now if the two operations are to be used to perform a monetary
-transfer between two accounts, it must be ensured that either both operations
-succeed or neither does. Under these circumstances, the web services
-coordination framework can be used to ensure the atomicity of operations. The
-sample code below shows how a standalone client may use the Kandula implementation
-in this scenario-</P>
-<P ><source>public class ... implements SessionBean {
-private SessionContext ctx;
- public void setSessionContext(SessionContext ctx) {
- this.ctx= ctx;
- }
- public ... foo(....) {
- Bank bank= new BankServiceLocator().getBank();
- UserTransaction ut= ctx.getUserTransaction();
- ut.begin();
- try {
- bank.credit(1001, 10);
- bank.debit(1002, 10);
- }catch (Exception e) {
- ut.rollback();
- }
- ut.commit();
- }
-}
-</source></P>
-<P></P>
-<P >The web services coordination framework describes how web
-services may join in and participate in coordinated activities. It also
-stipulates how participants may reach collective agreement on the ultimate
-outcome of such activities.</P>
-<P >Though the framework is platform independent, participant
-services unavoidably need to use numerous incompatible, platform-specific
-technologies to perform transactional work. For instance, if the banking service
-mentioned above is implemented in J2EE, its implementation would use JTA
-distributed transactions necessarily. Hence in the context of coordinated
-activities, the underlying JTA runtime is required to coordinate with an
-external coordinator to decide if and when to make any work performed as part of
-such activities, persistent. The Kandula provides this capability by integrating
-with existing transaction managers so that JTA distributed transactions started
-locally may be coordinated by an external coordinator through the web services
-coordination framework.</P>
-<P >Furthermore, the Kandula runtime is also capable of implicitly
-propagating the local transaction context of a calling thread on web service
-invocations. This allows distributed transactions to be propagated across
-heterogeneous application domains. To illustrate this point consider how the
-same use case illustrated above would be implemented by a J2EE client.</P>
-<P><source>
-public class ... implements SessionBean {
- private SessionContext ctx;
- public void setSessionContext(SessionContext ctx) {
- this.ctx= ctx;
- }
- public ... foo(....) {
- Bank bank= new BankServiceLocator().getBank();
- UserTransaction ut= ctx.getUserTransaction();
- ut.begin();
- try {
- bank.credit(1001, 10);
- bank.debit(1002, 10);
- }catch (Exception e) {
- ut.rollback();
- }
- ut.commit();
- }
-}</source></P>
-<P >Notice that the component uses JTA to ensure atomicity of
-operations. At runtime however, the transaction context of the calling thread is
-propagated to the remote service using the web services coordination
-framework.</P>
-<H2>Deliverables</H2>
-<P >Mainly, the Kandula project delivers a coordination service and
-a server runtime for using the web services coordination framework for
-distributed transaction management.</P>
-<P >The coordination service comprise of following web
-services:</P>
-<UL>
- <LI>Activation service
- (WS-Coordination)
- <LI>Registration service
- (WS-Coordination)
- <LI>Completion service
- (WS-AtomicTransaction)
- <LI>Coordinator service
- (WS-AtomicTransaction)
- <LI>Completion service
- (WS-AtomicTransaction) </LI></UL>
-<P >The server runtime is capable of importing and exporting
-transactions to and from J2EE, in accordance with the coordination framework
-described by WS-Coordination and WS-AtomicTransaction.
-It also provides a participant service in accordance with WS-AtomicTransaction. As stated before, this allows J2EE web
-services and clients to take part in atomic transactions while using JTA for
-transaction management.</P>
-<P >Additionally, Kandula also includes a Transaction Manager
-modeled on javax.transaction.TransactionManager,
-for use by standalone clients that need to coordinate activities using a
-coordination service. Note that this transaction manager cannot be used to
-perform any transactional work at the client end like JTA implementations sited
-elsewhere in this document. It merely provides a convenient API for standalone
-clients to use the coordination framework.</P>
-<H2>Status</H2>
-<P >Presently, the implementation only supports atomic
-transaction coordination type. Business activities will be supported in
-future.</P>
-<P>The framework supports importing atomic transactions for J2EE
-web services, i.e. JSR109 (see src/samples/interop).
-It also supports exporting transactions along web service calls made from J2EE
-by J2EE components like servlets and EJB s (see src/samples/servlet).</P>
-<P >So far the Kandula runtime has been integrated with 2 JTA
-implementations, Java Open Transaction Manager (JOTM) from ObjectWeb and JBoss transaction
-manager from JBoss.</P>
-<H2>Dependencies</H2>
-<P >Even though in practice the Kandula server runtime would be
-most likely used in conjunction with a J2EE server, in order to make the test
-cases as simple as possible, they have been designed to use Apache Tomcat servlet container instead.</P>
-<P >To try out the test cases it is required to integrate at
-least one of the above mentioned JTA implementations with Tomcat. To be specific
-you may use either one of the following transaction managers:</P>
-<UL type=disc>
- <LI>JOTM version 1.4.3 or
- later
- <LI>JBoss transaction manager from JBoss-4.0.0RC1 or later
- application server distribution. </LI></UL>
-<H2>Using Kandula with different JTA implementations</H2>
-<P >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 >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 >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>
+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 >All examples and Kandula default endpoint configuration
+<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>
@@ -179,45 +22,66 @@
Axis-1.2beta3 or later is required. </LI></OL>
<H3>Build and deploy Kandula</H3>
<OL type=1>
- <LI >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.
- <LI >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.
- <LI style="mso-list: l1 level1 lfo9; tab-stops: list .5in">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%.
- <LI>Copy the j2ee.jar, addressing.jar &
- jotm-*.jar files from %KANDULA_HOME%/target/lib to %CATALINA_HOME%/shared/lib.
- <LI >*Move* all Axis jars in
-%CATALINA_HOME%/webapps/axis/WEB-INF/lib to %CATALINA_HOME%/shared/lib
-
- <LI >Copy %KANDULA_HOME%/target/kandula-0.1-SNAPSHOT.jar
- to %CATALINA_HOME%/shared/lib.
-
- <LI >Use
- the server-config.wsdd file provided in %KANDULA_HOME%/conf
- to deploy the services sited above.
- <LI>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.
- <LI>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. </LI></OL>
+ <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>
@@ -256,5 +120,24 @@
<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></DIV></BODY></HTML>
+ 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>
+</BODY></HTML>
1.1 ws-fx/kandula/xdocs/index.html
Index: index.html
===================================================================
<HTML>
<HEAD><TITLE>Kandula - Apache Kandula</TITLE>
</HEAD>
<BODY>
<H1>Apache Kandula</H1>
<H2>Purpose</H2>
<P align="justify"> Kandula will provide an open-source implementation of WS-Coordination, WS-AtomicTransaction and WS-BusinessActivity based on Axis. The initial implementation will be in Java using Axis/Java. In addition to providing an implementation, a major focus of this project would be to ensure interoperability with other implementations of above specifications, particularly those by Microsoft (.NET) and IBM.</P>
<P align="justify"> </P>
<H2>Objectives</H2>
<P align="justify">The Kandula project has two main objectives:</P>
<div align="justify">
<OL type=1>
<LI>Provide an open source
implementation for the web services coordination and transaction management
frameworks defined by WS-Coordination, WS-<SPAN
>AtomicTransaction and WS-<SPAN
>BusinessActivity.</li>
<LI>Integrate existing open
source JTA implementations (e.g. JOTM, JBoss,
Geronimo, etc.) with the web services transaction management framework so that
J2EE web services and clients may take part in atomic transactions while using
JTA for transaction management</LI>
</OL>
<p> </p>
</div>
<H2>Overview</H2>
<P align="justify">Think of a hypothetical web service that provides banking
services. The service provides 2 operations: a credit
operation and a debit
operation. Now if the two operations are to be used to perform a monetary
transfer between two accounts, it must be ensured that either both operations
succeed or neither does. Under these circumstances, the web services
coordination framework can be used to ensure the atomicity of operations. The
sample code below shows how a standalone client may use the Kandula implementation
in this scenario-</P>
<P ><source>public class ... implements SessionBean {
private SessionContext ctx;
public void setSessionContext(SessionContext ctx) {
this.ctx= ctx;
}
public ... foo(....) {
Bank bank= new BankServiceLocator().getBank();
UserTransaction ut= ctx.getUserTransaction();
ut.begin();
try {
bank.credit(1001, 10);
bank.debit(1002, 10);
}catch (Exception e) {
ut.rollback();
}
ut.commit();
}
}
</source></P>
<P align="justify"></P>
<P align="justify" >The web services coordination framework describes how web
services may join in and participate in coordinated activities. It also
stipulates how participants may reach collective agreement on the ultimate
outcome of such activities.</P>
<P align="justify" >Though the framework is platform independent, participant
services unavoidably need to use numerous incompatible, platform-specific
technologies to perform transactional work. For instance, if the banking service
mentioned above is implemented in J2EE, its implementation would use JTA
distributed transactions necessarily. Hence in the context of coordinated
activities, the underlying JTA runtime is required to coordinate with an
external coordinator to decide if and when to make any work performed as part of
such activities, persistent. The Kandula provides this capability by integrating
with existing transaction managers so that JTA distributed transactions started
locally may be coordinated by an external coordinator through the web services
coordination framework.</P>
<P align="justify" >Furthermore, the Kandula runtime is also capable of implicitly
propagating the local transaction context of a calling thread on web service
invocations. This allows distributed transactions to be propagated across
heterogeneous application domains. To illustrate this point consider how the
same use case illustrated above would be implemented by a J2EE client.</P>
<P><source>
public class ... implements SessionBean {
private SessionContext ctx;
public void setSessionContext(SessionContext ctx) {
this.ctx= ctx;
}
public ... foo(....) {
Bank bank= new BankServiceLocator().getBank();
UserTransaction ut= ctx.getUserTransaction();
ut.begin();
try {
bank.credit(1001, 10);
bank.debit(1002, 10);
}catch (Exception e) {
ut.rollback();
}
ut.commit();
}
}</source></P>
<P align="justify" >Notice that the component uses JTA to ensure atomicity of
operations. At runtime however, the transaction context of the calling thread is
propagated to the remote service using the web services coordination
framework.</P>
<P align="justify" > </P>
<H2>Deliverables</H2>
<P align="justify" >Mainly, the Kandula project delivers a coordination service and
a server runtime for using the web services coordination framework for
distributed transaction management.</P>
<P align="justify" >The coordination service comprise of following web
services:</P>
<div align="justify">
<UL>
<LI>Activation service
(WS-Coordination)
<LI>Registration service
(WS-Coordination)
<LI>Completion service
(WS-AtomicTransaction)
<LI>Coordinator service
(WS-AtomicTransaction)
<LI>Completion service
(WS-AtomicTransaction) </LI>
</UL>
</div>
<P align="justify" >The server runtime is capable of importing and exporting
transactions to and from J2EE, in accordance with the coordination framework
described by WS-Coordination and WS-AtomicTransaction.
It also provides a participant service in accordance with WS-AtomicTransaction. As stated before, this allows J2EE web
services and clients to take part in atomic transactions while using JTA for
transaction management.</P>
<P align="justify" >Additionally, Kandula also includes a Transaction Manager
modeled on javax.transaction.TransactionManager,
for use by standalone clients that need to coordinate activities using a
coordination service. Note that this transaction manager cannot be used to
perform any transactional work at the client end like JTA implementations sited
elsewhere in this document. It merely provides a convenient API for standalone
clients to use the coordination framework.</P>
<P align="justify" > </P>
<H2>Status</H2>
<P align="justify" >Presently, the implementation only supports atomic
transaction coordination type. Business activities will be supported in
future.</P>
<P align="justify">The framework supports importing atomic transactions for J2EE
web services, i.e. JSR109 (see src/samples/interop).
It also supports exporting transactions along web service calls made from J2EE
by J2EE components like servlets and EJB s (see src/samples/servlet).</P>
<P align="justify" >So far the Kandula runtime has been integrated with 2 JTA
implementations, Java Open Transaction Manager (JOTM) from ObjectWeb and JBoss transaction
manager from JBoss.</P>
<P align="justify" > </P>
<H2>Dependencies</H2>
<P align="justify" >Even though in practice the Kandula server runtime would be
most likely used in conjunction with a J2EE server, in order to make the test
cases as simple as possible, they have been designed to use Apache Tomcat servlet container instead.</P>
<P align="justify" >To try out the test cases it is required to integrate at
least one of the above mentioned JTA implementations with Tomcat. To be specific
you may use either one of the following transaction managers:</P>
<div align="justify">
<UL type=disc>
<LI>JOTM version 1.4.3 or
later
<LI>JBoss transaction manager from JBoss-4.0.0RC1 or later
application server distribution. </LI>
</UL>
</div>
<UL type=disc>
</UL>
</BODY></HTML>
1.1 ws-fx/kandula/xdocs/img/image001.gif
<<Binary file>>
1.1 ws-fx/kandula/xdocs/img/image002.gif
<<Binary file>>
1.1 ws-fx/kandula/xdocs/img/image003.gif
<<Binary file>>
1.1 ws-fx/kandula/xdocs/img/image004.gif
<<Binary file>>
1.1 ws-fx/kandula/xdocs/img/image005.gif
<<Binary file>>
1.1 ws-fx/kandula/xdocs/img/image006.gif
<<Binary file>>
1.1 ws-fx/kandula/xdocs/img/image007.gif
<<Binary file>>
1.1 ws-fx/kandula/xdocs/img/image008.gif
<<Binary file>>
1.1 ws-fx/kandula/xdocs/img/image009.gif
<<Binary file>>
1.1 ws-fx/kandula/xdocs/img/image010.gif
<<Binary file>>