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>>
