incubator-agila-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Agila Wiki] Update of "AgilaBpelDeveloperGuide" by MatthieuRiou
Date Mon, 29 Aug 2005 19:30:41 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Agila Wiki" for change notification.

The following page has been changed by MatthieuRiou:
http://wiki.apache.org/agila/AgilaBpelDeveloperGuide

The comment on the change is:
Importing former Twister developer's guide.

New page:
= Agila BPEL Developer Guide =

== Introduction ==

Agila BPEL is composed of several components interacting altogether. Those components are
distributed in several war and jar artifacts:

    * agila-engine-x.x.jar: Agila BPEL engine jar groups all server components making the
Agila BPEL solution. The engine core, the process deployer, the worklist manager, a user/role
manager and few other utilities are packaged in this library. For detailed information on
this module (javadoc, test results, ...), see the engine documentation.
    * agila-ws-x.x.war: this web application is the web service adapter for the engine. It
provides the entry point to the engine using SOAP/HTTP (thanks to Axis) ans simply presents
engine's interfaces. See detailed documentation on the web services module documentations.
    * agila-client-x.x.jar: this jar file replicates the public engine interfaces on the client
side encapsulating the SOAP/HTTP remote call. So engine's interface can be simply called in
Java, just as if it was local.

When Agila is just downloaded and installed it is already fully functional but is not setup
to invoke your web services. We chose to have a default 'demonstration' setup that just logs
the calls to services for testing. You just need to change a line in a configuration file
to let Agila BPEL call your web services from their WSDL descriptions. It can then be used
to organize the work of people and interact with those services, which is probably the most
valuable role of a business process management system.

==  Making Agila BPEL call your services ==

===  Setting up Web Services invocation ===

Edit agila-configuration.xml that should be located in the common/classes directory of your
Tomcat installation. In the engine/implementation node you should find something like:
{{{
<message-broker impl="org.apache.agila.bpel.engine.priv.messaging.impl.DefaultMessageBrokerImpl"/>
}}}
To enable web services invocation using the deployed WSDL description, just replace this with:
{{{
<message-broker impl="org.apache.agila.bpel.engine.priv.messaging.impl.WSMessageBroker"/>
}}}

=== Custom Invocation ===

If you don't want to use Web Services invocation and invoke your services in your own proprietary
way (for performance or convenience reasons), you will have to implement your own class that
Agila BPEL will use for delegating the services calls: a MessageBroker.

==== Implementing the MessageBroker ====

MessageBroker is an abstract class that receives all messages from the engine and will resend
them to the methods or your subclass. To write your own Message Broker you will have to extend
it and therefore implement the two following methods:
{{{
protected void asyncSend(String partner, String portType, String operation, Document message);
protected Document syncSend(String partner, String portType, String operation, Document message);
}}}
The first method should be implemented as an asynchronous invocation so the call should return
almost immediately and no result are required. The second method requires a result relevant
to the service processing so its execution have to be synchronous.

The parameters provided refer to the service that should be called. The partner (actually
partner link) is the name of the business partner who is invokved in this business interaction.
The portType and the operation have the same semantic as defined by WSDL . Those parameters
are the ones that have been defined in the process BPEL description.

If you are familiar with BPEL, the first method is called when Agila BPEL meets a reply element
or an invoke with no output variable. The second is called in case of an invoke with an output
variable.

====  Configuring Agila BPEL to use your MessageBroker ====

To let Agila BPEL use your Message Broker you just have to modify Agila BPEL's configuration
file and put your class in Agila BPEL's classpath. Edit agila-configuration.xml located in
Tomcat's conf directory. Change the impl attribute of the element in path agila/engine/implementations/message-broker
by replacing the class currently specified with the fully qualified name of your Message Broker.

Then, to add your Message Broker in Agila BPEL classpath, if it's packaged inside a jar file,
copy it to:
{{{
[TOMCAT_HOME ] /webapps/agila-ws/WEB-INF/lib
}}}
If it's just a class file, copy it to:
{{{
[TOMCAT_HOME ] /webapps/agila-ws/WEB-INF/classes
}}}

Don't forget to copy those files again if you need to reinstall Agila BPEL. Redeploying Agila
BPEL webapp would mean deleting all the agila-ws directory.

==  Calling Agila BPEL ==

To make calling Agila BPEL easy, we implemented client stubs that wrap the SOAP/HTTP network
calls, so you just need to use client classes to invoke Agila BPEL. There is one client stub
for each server component, so if you check the package org.apache.agila.bpel.client you will
find 5 client stubs (AgilaDeployer, AgilaEngine, AgilaEngineAdmin, AgilaUser and AgilaWorkList)
and few java beans that can hold the returned data. Actually the only stub you're probably
going to need is AgilaEngine. Others are mostly used by Agila BPEL WorkList UI and Agila BPEL
administration console.

===  Setting your classpath ===

To use our client module, you'll have to setup your classpath correctly. So additionally to
agila-client.jar, include the following libraries :

    * axis-1.1.jar : main axis library, needed for web services invocation
    * axis-jaxrpc-1.2-alpha-1.jar : needed by Axis
    * axis-saaj-1.2-alpha-1.jar : needed by Axis
    * commons-discovery-SNAPSHOT.jar : needed by Axis
    * commons-logging-1.0.3.jar : our logging library.

=== Sending a message ===

There are two ways to send a message to your process using Agila BPEL:

   1. Send your message to the process endpoint, providing the target partner, portType and
operation in the header of the SOAP message.
   2. Send the message directly to Agila BPEL engine using Agila BPEL specific message format.

Both methods have advantages and disadvantages. The first method is prefered as it is compliant
with the WS-BPEL specification, each process have to be available as separate web service.
However there are some cases where you just want to send a message without knowing exactly
wich process is the target. The second method makes this possible, the engine will know for
you which process is the target of your message using the partner, portType and operation
provided.

Here is an example of java code that prepares the appropriate SOAP envelope to send to your
process using the first method:
{{{
   String SOAP_ATTRIBUTE_NS = "http://www.apache.org/agila";
   String SOAP_ATTRIBUTE_PARTNER = "partner";
   String SOAP_ATTRIBUTE_PORTTYPE = "port";
   String SOAP_ATTRIBUTE_OPERATION = "operation";

   SOAPHeaderElement partnerElmt = 
         new SOAPHeaderElement(envelope.createName(
                           SOAP_ATTRIBUTE_PARTNER, "tws", SOAP_ATTRIBUTE_NS));
   partnerElmt.addTextNode(partner);
   SOAPHeaderElement portElmt = 
         new SOAPHeaderElement(envelope.createName(
                           SOAP_ATTRIBUTE_PORTTYPE, "tws", SOAP_ATTRIBUTE_NS));
   portElmt.addTextNode(port);
   SOAPHeaderElement operationElmt = new SOAPHeaderElement(
                           envelope.createName(SOAP_ATTRIBUTE_OPERATION, "tws", SOAP_ATTRIBUTE_NS));
   operationElmt.addTextNode(operation);
   envelope.addHeader(partnerElmt);
   envelope.addHeader(portElmt);
   envelope.addHeader(operationElmt);

   envelope.addBodyElmt(wsdlMessageBodyElmt);
}}}

When you deploy a process in Agila BPEL engine, it is automatically available at the address
http://server:port/agila-ws/processname.

===  Using the java client ===

The Agila BPEL Engine client class implements two methods to contact the engine, each using
one of the message sending mechanism illustrated before. The method you're going to call is:
{{{
public Document acknowledge(String partner, String port, String operation, Document message)
                throws ServiceException, RemoteException;

public Document acknowledge(String targetProcess, String namespace, String partner, String
port, 
    		String operation, Document message) throws ServiceException, RemoteException;
}}}

Main parameters are the partnerlink, port type and operation the message is targeted at (actually
Agila BPEL engine is 'playing' the role of several web services). From those parameters, the
AgilaEngine class is building a SOAP message following a pre-defined XML Schema (message.xsd
in the conf directory of your Agila BPEL distribution) and sending it using Axis to the Agila
BPEL engine web service.

The last parameter is the body of the message, it's also included in the SOAP message sent
to the engine's web service as is. This message should correspond to a pending receive held
by the engine. If the engine cannot find any receive waiting for such a message in an instance
relevant to the message content (see message correlation in WS-BPEL) it will just be ignored.

===  Calling other Agila BPEL services ===

If you want to use the AgilaDeployer client (for exampe to deploy using your own UI) or any
other client class, just call them just like you called the engine. The javadoc of the client
module should give you a good idea of which methods are available, what they are doing and
how to call them.

== Agila BPEL listener ==

Agila BPEL is running inside a web container as a server, it's logging all actions properly
but it can be sometimes hard to react to server errors automatically only with logging. We
therefore implemented a simple listener interface that is notified when Agila BPEL meets a
problem.

To add a listener of your own that can be notified of such events, you just need to complete
the following steps:

   1. Create your listener class that must implement the AgilaListener interface.
   2. Make sure your class is in Agila BPEL classpath (see Configuring Agila BPEL to use your
MessageBroker )
   3. Add your listener's fully qualified name in agila-configuration.xml under the /agila/event-listeners
node.

Mime
View raw message