Kandula-1

Business Activity basics

A WS-BA Business Activity is a coordination context with relaxed constraints compared to WS-AT Atomic Transaction. The most important differences are:

Atomicity: the work done in the context need not appear to be atomic to the outside, e.g. intermediate results may be seen by an observer.
Consistency: while the state after the transaction finished should be consistent with business rules, it is not required that all participants share a common outcome.

In WS-AT transactions, all participants agree to either commit or roll back. The decision is made for all participants.

By contrast, WS-BA allows for the separate management of every participant, so while one participant is told to cancel, other participants may complete and close their work.

Step 1: Adopting the Web Service Interface Definition (WSDL)

When a web service client invites a business partner into a WS-Coordination transaction, they send them a WS-Coordination coordination context object that includes the address of the coordination service, the transaction's identifier and other data the coordination service requires.

The web service provider needs to allow a WS-Coordination Coordination Context object to be included with the business request:

			<wsdl:definitions
				xmlns:wscoor="http://schemas.xmlsoap.org/ws/2004/10/wscoor"
				...
			>
				<wsdl:types>
					<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
						<xsd:element name="applicationRequest">
								<!-- This element needs to be added -->
								<xsd:element ref="wscoor:CoordinationContext" />
		
								<!-- All other application elements need not be modified -->
								<xsd:element name="flightNo" type="..." .../>
								...
						</xsd:element>
					</xsd:schema>
				</wsdl:definitions>
		
				<!-- The rest of the definitions also need not be modified -->
		
			</wsdl:types>

Step 2: Implementing the Service

A WS-BA enabled web service needs to do only two things:

After receiving a CoordinationContext from the client, register yourself in the transaction.
When receiving commands from the Coordinator, do your business and report back.

Apache Kandula provides two classes for registering participants with a coordination context:

org.apache.kandula.coordinator.ba.participant.BAwPCParticipant, for registering for the Participant Completion Protocol.

Participants need to start performing their work immediately and report Completed by invoking this.tellCompleted() when done.
org.apache.kandula.coordinator.ba.participant.BAwCCParticipant, for registering for the Coordinator Completion Protocol.

Participants need to implement the onComplete method and perform their work there. Completed is reported by returning a corresponding value.

Your participant implementation needs to extend one of those classes and implement the abstract methods. Thats it!

Implementing the abstract methods of the participant classes

The following sections document what your implementation of kandula's abstract methods is required to do.

onComplete

This method is only applicable for the Coordination Completion participant. When it is invoked, the coordinator tells you to actually perform the requested work.

Return ParticipantCompleteResult.COMPLETED when you were able to complete your work as requested, or ParticipantCompleteResult.HANDLED_BY_APPLICATION if you like not to report something back at the moment. You need to call one of the tell...() methods to send your response to the coordinator at any time you wish.

onCancel

When the coordinator sends Cancel, it asks you to cancel all outstanding work. If you were able to successfully abort and cancel everything, return ParticipantCancelResult.CANCELED. After the coordinator acknowledges the receipt of Canceled, the participant is no longer needed.

If the service is unable to cancel, it should have reported Completed before.

onClose

After having reported Completed, either from onComplete or by having invoked tellCompleted(), the business partner decided to go for it. Perform whatever it takes to finalize your work and return ParticipantCloseResult.CLOSED when done.

Please note that the service may not report any fault at this stage! You must successfully complete!

onCompensate

After having reported Completed, either from onComplete or by having invoked tellCompleted(), the business partner decided to throw away your work. Perform whatever it takes to compensate previous actions and return ParticipantCompensateResult.COMPENSATED when done.

If compensation is not possible, you need to return ParticipantCompensateResult.FAULTED and humans must investigate the issue. This should almost never happen.

onFinish

The coordinator informs you that the result of your work, whatever it is, was acknowledged and that you may forget about the transaction. This means the participant object may now be destroyed.

Step 3: Implementing the Client

Step 4: Adding business logic to the client

Step 5: Deploying and Testing

Running the samples

To try out the samples provided with Kandula-1, you need the following prerequisites:

Apache Tomcat with Apache Axis installed
Kandula Sources from SVN checked out

The WS-BA examples require you to have two Tomcat Servers running, one acting as the coordination service and one as the participants. The initiator will run independently as JUnit test cases or a Swing application.

Building

Build Kandula as usual with "maven". Build the BusinessActivity-Testsuite and the Holiday example by running "ant" in the "samples/holiday" or "samples/ba-testsuite" directories.

Copy the jar-files from the respective "build" directories into the axis/lib folders of your Axis installation.

Preparing the Tomcats

If you run Kandula from an IDE such as eclipse, you can typically manage multiple configurations there. The Eclipse Web Tools Projects, for example, offers to set different "base" directories with different axis installations.

The easiest way to have two Tomcat instances running is to copy the whole "Tomcat"-directory. This tutorial will refer to the "Coordination Server" and to the "Participant Server".

First, we configure the Coordination Server. It does not require the two JAR files from holiday and ba-testsuite. Copy the "src/conf/server-only-config_with_WSBA.wsdd" to the axis/WEB-INF folder and rename it to "server-config.wsdd". If the file already exists, replace it with that one. Next, copy the kandula.properties and the client-config.wsdd files from src/conf/ to the axis/WEB-INF/classes directory.

Now we have to make sure the correct ports are configured. Open the Tomcat/conf/server.xml file with your favorite text editor, scan for the

<Connector ...>

line and make sure the port is set to 8280. If you don't want to use the TCP Monitor (which you only do if you know what this is), set it to 8281.

Next, open the copy of the kandula.properties and make sure the following entries are set:

kandula.localService=http://localhost:8281/axis/services/ 

kandula.preferredCoordinationService=http://localhost:8281/axis/services/

The kandula.localService property shall point to the endpoint the coordination services are running, and be fully qualified. It is used to generate the endpoint addresses that is sent to the peers. The kandula.preferredCoordinationService property tells Kandula at which coordination service it shall create new coordination contexts; at the coordinator, this should point to itself.

The Coordination Server is now ready!

Start it up by invoking the Tomcat/bin/startup script and verify that the Axis List Services page shows the "coordinator", "kandula_BA_PC_coordinator" and some more services named like that.

Second, we configure the Participant Service. This server requires the Kandula, ba-testsuite and holiday jar files in its axis/web-inf/lib directory. Copy the "server-participant-only-with-test-config_with_WSBA.wsdd" from the src/conf directory to the axis/WEB-INF folder and rename it to "server-config.wsdd". If the file already exists, replace it with that one. Next, copy the kandula.properties and the client-config.wsdd files from src/conf/ to the axis/WEB-INF/classes directory.

Now we have to make sure the correct ports are configured. Open the Tomcat/conf/server.xml file with your favorite text editor, scan for the

<Connector ...>

line and make sure the port is set to 8180. If you don't want to use the TCP Monitor (which you only do if you know what this is), set it to 8181.

Next, open the copy of the kandula.properties and make sure the following entries are set:

kandula.localService=http://localhost:8181/axis/services/ 

kandula.preferredCoordinationService=http://localhost:8281/axis/services/

The kandula.localService property shall point to the endpoint the participant services are running, and be fully qualified. It is used to generate the endpoint addresses that is sent to the peers. The kandula.preferredCoordinationService property tells Kandula at which coordination service it shall create new coordination contexts.

The Participant Server is now ready!

Start it up by invoking the Tomcat/bin/startup script and verify that the Axis List Services page shows the "participant", "kandula_BA_PC_participant" and some more services named like that.

Start up now the TCP Port Monitor, if you chose to use it.

Run!

After having started both servers, the port monitor if configured and verifying everything is OK, start the holiday demo by issuing "ant run" in the holiday folder.

The holiday example consists of two rental providers that offer cars and rooms for rent. When starting up the client, you must first chose whether you'd like atomic or mixed outcome.

Select "car" or "room" from the dropdown and hit the "Search for offers" button. The client now fetches offers from the remote web service on the participant web server. You may search for multiple different offers, also cars and rooms mixed. Choose some of the offers from the list, and hit the "add selected offer to basket" button to put the offer into the basket. The client now contacts the remote web service again, but this time provides the CoordinationContext to enrol a participant. The Rental Web Service immediatly enroles for the transaction.

To check the state of the business activity, switch to the "basket" tab and hit the "refresh basket" button. Depending on mixed or atomic outcome, the available buttons at the bottom change. With mixed outcome, select one or more participants from the basket and hit the "complete", "close", etc. buttons to send the corresponding messages to the participants. Refresh will always refresh the participant list. If you press buttons to send messages that are not applicable in the current state of the context or participant, there is no error message but the command is silently ignored.

Project Documentation