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/07 13:57:16 UTC
cvs commit: ws-fx/kandula/xdocs navigation.xml user-guide.html architecture-guide.html
thilina 2005/06/07 04:57:16
Added: kandula/xdocs navigation.xml user-guide.html
architecture-guide.html
Log:
Adding xdocs to Kandula
Revision Changes Path
1.1 ws-fx/kandula/xdocs/navigation.xml
Index: navigation.xml
===================================================================
<project name="Sandesha">
<title>Sandesha</title>
<body>
<menu name="Sandesha">
<item name="Simple User Guide" href="user-guide.html"/>
<item name="Architecture Guide" href="architecture-guide.html"/>
</menu>
</body>
</project>
1.1 ws-fx/kandula/xdocs/user-guide.html
Index: user-guide.html
===================================================================
<HTML>
<HEAD><TITLE>User Guide for Apache Kandula</TITLE>
</HEAD>
<BODY>
<H1>User Guide for Apache Kandula</H1>
<H2>Purpose</H2>
<P>This tutorial provides a brief overview of the WS-TX 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 WS-TX 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 WS-TX 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 WS-TX 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 WS-TX 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 WS-TX 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, WS-TX 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 WS-TX 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 WS-TX 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 WS-TX with different JTA implementations</H2>
<P >WS-TX 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 %WS-TX_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 %WS-TX_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>
<H2>Running the provided samples</H2>
<H3>Setup the TCP Monitor</H3>
<P >All examples and WS-TX default endpoint configuration
parameters given in %WS-TX_HOME%/conf/endpoints.conf assume that you are using the
TCP monitor to monitor and redirect soap messages sent to port 8081 on localhost, to port 8080.</P>
<H3>Configure Jakarta-Tomcat and deploy Axis</H3>
<OL type=1>
<LI >Install Jakarta-Tomcat.
The samples have been tested on Jakarta-Tomcat-5.0.25.
<LI >Deploy Apache Axis.
Axis-1.2beta3 or later is required. </LI></OL>
<H3>Build and deploy WS-TX</H3>
<OL type=1>
<LI >Modify %WS-TX_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 %WS-TX_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 %WS-TX_HOME%.
<LI>Copy the j2ee.jar, addressing.jar &
jotm-*.jar files from %WS-TX_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 %WS-TX_HOME%/target/kandula-0.1-SNAPSHOT.jar
to %CATALINA_HOME%/shared/lib.
<LI >Use
the server-config.wsdd file provided in %WS-TX_HOME%/conf
to deploy the services sited above.
<LI>Use
the server-config.wsdd file provided in %WS-TX_HOME%/conf
to deploy WS-TX and WS-Addressing handlers. <BR>Note: WS-TX
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 %WS-TX_HOME%/conf/server-config.wsdd are used by the WS-Addressing
implementation and *must be* copied to the server-config.wsdd.
<LI>Copy %WS-TX_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>
<P><source>
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></source></P>
<H3>Build the samples</H3>
<OL style="MARGIN-TOP: 0in" type=1>
<LI >To
build the sample(s) enter,<BR clear=all><BR clear=all>ant dist<BR clear=all><BR
clear=all>in %WS-TX_HOME%/src/samples </LI></OL>
<H3>Run the Interop sample</H3>
<P >This sample shows how a standalone client may access a
transactional web service. To try it out,</P>
<OL style="MARGIN-TOP: 0in" type=1>
<LI >Copy the %WS-TX_HOME%/src/samples/interop/build/interop.jar to
%CATALINA_HOME%/webapps/axis/WEB-INF/lib
<LI >Use
the deploy.wsdd
in %WS-TX_HOME%/src/samples/interop to deploy the service in
Axis.
<LI>Run
the provided JUnit test cases by entering,<BR
clear=all><BR clear=all>ant test<BR clear=all><BR
clear=all>in %WS-TX_HOME%/
</LI></OL></DIV></BODY></HTML>
1.1 ws-fx/kandula/xdocs/architecture-guide.html
Index: architecture-guide.html
===================================================================
<html>
<head><title>Architecture Guide for Apache Kandula</title>
</head>
<body>
<h1>Architecture Guide for Apache Kandula</h1>
<h2>Coming Soon</h2>
</body></html>