ActiveVOS Server User’s Guide

Previous | Next

Invoking a Process from Java

For an overview of this topic, see Standard or Java-based Service Endpoints for Process Consumer (My Role) Partner Links.

ActiveVOS Server provides an API for dispatching a message directly to the engine. This API is available as an Enterprise Java Bean (EJB) on platforms that support EJB or as a plain Java API for deployment platforms without an EJB container.

The following illustration shows an overview of the external and standard implementations of My Role service endpoints.

The ActiveVOS engine’s Enterprise Java Bean (EJB) binding implements the following interface:

public interface org.activebpel.wsio.receive.IAeMessageQueue

{

   /**

    * Delivers the message to the BPEL engine's message queue.

    * 

    * @param aData

    * @param aContext

    * @return IAeWebServiceResponse

    * @throws RemoteException

    * @throws AeRequestException

    */

   public org.activebpel.wsio.IAeWebServiceResponse

        queueReceiveData

        (org.activebpel.wsio.IAeWebServiceMessageData aData,

         org.activebpel.wsio.receive.IAeMessageContext aContext)

        throws RemoteException,

        org.activebpel.wsio.receive.AeRequestException;

}

where:

IAeMessageQueue is name of the interface. The package is org.activebpel.wsio.receive.

IAeWebServiceResponse is the interface for the data or fault that can be returned from the calling service.

queueReceiveData is a method that a service endpoint can invoke passing in context and data.

IAeWebServiceMessageData contains the data for the inbound message.

IAeMessageContext contains the contextual information for the request.

Steps to Invoke a Process via Plain Java or EJB API

1. Include required .jar files on your java project classpath.

The API is contained in the following .jar files. If using the plain Java API, only ae_wsio.jar is required, if using the EJB implementation, both are required on the classpath.

ae_wsio.jar contains the core interfaces used to send messages to the engine

ae_awfwsio.jar contains the required interfaces for interacting with the ActiveVOS engine EJB

2. From Java code, lookup the EJBHome for the AeMessageQueueBean from JNDI context and create an instance of the bean.

For example:

InitialContext ctx = new InitialContext();

Object home = ctx.lookup("ejb/AeMessageQueueBean");

mHome = (AeMessageQueueHome)

PortableRemoteObject.narrow(home,AeMessageQueueHome.class);

AeMessageQueueRemote msgQueueBean = mHome.create();

3. Create an instance of AeMessageContext.

The AeMessageContext object contains the relevant details about the My Role partner link from the BPEL process. These details make up the context for the inbound messages sent to the engine.

The context details are as follows:

AeMessageContext Parameters	Description
setProcessName	Process Qname. The Qname includes the namespace plus the local part of the process name. In a BPEL source file, this is the target namespace. NOTE: You can specify a service name instead of a process/partnerlink name. For a discussion of service name, see Standard or Java-based Service Endpoints for Process Consumer (My Role) Partner Links.
setPartnerLinkName	Partner link name from the BPEL process
setServiceName	Optional. As an alternative to setting the process and partner link name, you may specify the My Role (Process Consumer) service name. This name is in the Process Deployment Descriptor Editor on the Partner Links page and is also on the Service Definitions page in the ActiveVOS Console. This property is mutually exclusive with the process name and only one or the other may be set on the context.
setOperation	Operation from the portType of the partner link type defined for My Role
setProcessVersion	Optional. Messages are sent to the current process, if a process version is not specified.
setPrincipal	Optional. This value is used by the engine for performing lookups on deployed partner definitions when using the "Principal" endpoint type. Identifies the principal name value for inbound messages. Processes that include human tasks also use this value to identify the process initiator.

Example code for creating a new message context:

// Create the message context object for the request

// containing the routing information for the process

AeMessageContext context = new AeMessageContext();

context.setProcessName(new QName(aProcessNamespace,aProcessName));

context.setPartnerLink(aPartnerLink);

context.setOperation(aOperation);

4. Create an instance of AeWebServiceMessageData.

The context details are as follows:

AeWebServiceMessageData Parameters	Description
Constructor QName	The QName specified in the constructor corresponds to the QName of the WSDL message associated with the input message
setData	Each message part is defined in this parameter. Message parts must be primitive types like strings, integers, or XML passed as DOM Document object. Complex types get passed as documents. The XML document must conform to the schema definition of the complex type. If a message has correlated properties in it, the engine extracts these properties using the property aliases and routes the message to the correct process instance.

WSDL Message for the message data object:

<wsdl:message name="creditInformationMessage">

   <wsdl:part name="part1" element="tns:LoanProcessRequest" />

   <wsdl:part name="part2" element="tns:LoanProcessAddress" />

</wsdl:message>

Example code for creating message data object:

AeWebServiceMessageData data = new AeWebServiceMessageData(new 

QName("http://tempuri.org/services/loandefinitions","creditInformationMessage"));

data.setData("part1", domOfLoanProcessRequest);

data.setData("part2", domOfLoanProcessAddress);

5. Invoke the queueReceiveData method on the bean.

IAeWebServiceResponse response = msgQueueBean.queueReceiveData(data,context);

The context details are as follows:

IAeWebServiceResponse Parameter	Description
getMessageData()	Message data returned from the invoke. See Description of AeWebServiceMessageData for details.
isFaultResponse()	Return true if the response wraps a fault
getErrorCode()	Accessor for the error code QName
getErrorString()	Returns an error message associated with the fault or null if there is none
getErrorDetail()	Returns a stacktrace or other detailed information associated with the fault or null if there was none
getRootCause()	Returns a Throwable which is the root cause of the error code
getBusinessProcessProperties()	Return a Map of (string) name/value pairs from the business process

Copyright (c) 2004-2010 Active Endpoints, Inc.