Asynchronous Exchange << 1 2 3 4 5 6 >>
Introduction
Synch vs. Asynch Operations
Getting Set Up
Use Case & Implementation
Build & Test the Requester
Build & Test the Initiator
Build & Test the Responder
Using the SOAP ReplyTo Header
Adding Message Correlation

Asynchronous Message Exchange, cont.

Build & Test the Requester Process

Defining the Application Data Types

To begin, define the simple data types that will be used in our messages by creating an XML Schema document. The Web Tools Project plug-in included with ActiveVOS is handy for this.

	Expand the AsynchMessageExchange project in the Project Explorer and right-click on the schema folder.
	Select New / XML Schema File from the cascading menu.

New XML Schema file

	Name the file AMETypes.xsd. The file template opens in an editor. Select the Source tab.
	Right-click anywhere in the editor and select Format to reformat the XML for readability.
	Change both the targetNamespace and xmlns:tns prefix declarations to:
	http://docs.activevos.com/schema/AME/AMETypes

The file contents should appear like so:

Edit the schema to create a new <element> definition named Document. See below.

The document / literal binding style will be used for this application, so this element should be defined using complexType and contain one string type element each, named value. Document is the data type we'll be using in our message.

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
   targetNamespace="http://docs.activevos.com/schema/AME/AMETypes"
   xmlns:tns="http://docs.activevos.com/schema/AME/AMETypes"
   elementFormDefault="qualified">

   <element name="Document">
      <complexType>
         <sequence>
            <element name="value" type="string" />
            <element name="InstanceID" type="string" minOccurs="0"/>
         </sequence>
      </complexType>
   </element>

</schema>

Save the AMETypes.xsd file.

This file contains the data type definitions we need to construct our messages and operations. See AMETypes_xsd.fin for the finished version of this file.

Creating the Requester

ActiveVOS Designer has built-in wizards that simplify construction of WSDL and BPEL artifacts we'll need. The first component required is a WSDL definition that specifies the partnerLinkType, portType and operation - that is, the interface - for the service exposed by the Requester. This is the service the Initiator will invoke to get our simple composite application running.

In ActiveVOS Designer, locate the Interfaces view, which is typically below the Project Explorer view on the left.

Note: if you don't see the Interfaces view, ensure that you're using the ActiveVOS Perspective. Select Window / Open Perspective / Other... / ActiveVOS from the main menu if necessary.

Click the button, located in the caption bar of the Interfaces view. The New Interface wizard appears.

Note that the wizard presents options to create a Request-Response Operation or a One-way Operation. Recall from our use case that the Initiator communicates synchronously with the Requester. This corresponds (in BPEL) to a Request-Response, so leave that default radio button selected.

We'll be constructing messages based on our XML Schema (above), so...

	... leave the other two default radio buttons selected and click Next.
	On the next wizard page - Input From Schema - navigate in the top window to AsynchMessageExchange/schema/AMETypes.xsd and select it.
	Under Choose an Element:, leave the Document element selected.
	Click Next, do the same on the Output From Schema wizard page and click Next.
	On the Operation and Partner Link page of the wizard, make the following changes to the values displayed:

Service	Port Type	RequesterPT
	Operation	initiate
	Target Namespace	http://docs.activevos.com/wsdl/AME/Requester
Process	Partner Link Type	RequesterPLT
	Role Name	requester

The resulting wizard page should look like this:

New Interface

	Click Next to continue.
	On the last page of the wizard, enter or navigate to AsynchMessageExchange/wsdl , change the File Name entry to Requester.wsdl and click Finish. The Requester.wsdl file appears in a new editor.
	Right-click anywhere in the editor area and select Format from the pop-up menu to rearrange the XML for better readability.

In the Interfaces view, a new Partner Link Type and Port Type appear, corresponding to the WSDL definition just created. Take a moment to compare the tree hierarchy in the Interfaces view to the values in the WSDL file to ensure that you understand their relationships, then close the Requester.wsdl file in the editor.

With this WSDL definition ready, we can now construct a BPEL process which, once deployed, will expose the web service operation just defined.

	To create a new BPEL process, go back to the Project Explorer, right-click on the AsynchMessageExchange/bpel folder and select New / BPEL Process.
	Set the File name entry to Requester.bpel and click the Advanced button.
	Change the Target Namespace value to http://docs.activevos.com/bpel/AME/Requester, leave the rest of the values at their default settings, and click Finish.

A new, blank BPEL process appears in the editor window. Note that two errors appear in the Problems view. You can safely ignore these for now.

The Requester process is intended to expose the initiate operation, which will be synchronous. For a BPEL process, this implies a Receive / Reply activity pair.

To create these two activities easily, simply go to the Interfaces view and drag the operation and drop it onto the empty process canvas in the editor.

Drag the initiate operation

The Operation wizard appears.

	Leave the default Receive-Reply radio button selected and click Next.
	On the next wizard page, change RequesterPLT to simply RequesterPL (it's a partnerLink, not a partnerLinkType) and click Next.
	On the Input Variable page, change the variable name from Document to requestValue and click Next.
	On the Output Variable page, change the variable name from Document1 to replyValue and click Finish. Two new BPEL activities appear on the editor canvas - a Receive and a Reply.
	Double-click on each activity in turn to examine its attributes in the Properties view.
Before adding the Responder process to the mix, set up the Requester process for standalone test.
	To do this, add an Assign activity to the canvas (drag from the palette or right-click on the canvas and selecte Add / Activity / Assign).
Because it's a complex variable, replyValue will need to be initialized before using it.
	Add a Copy Operation to the Assign activity with the following From and To specs to perform the required initialization (see the ActiveVOS Designer documentation for details on constructing Copy Operations and initialization of complex variables, if needed):

From	Type	Literal
	Literal Contents	<types1:Document xmlns:types1="http://docs.activevos.com/schema/AME/AMETypes"> <types1:value /> <types1:InstanceID /> </types1:Document>
To	Type	Variable
	Variable	replyValue

Add another Copy Operation to the Assign with the following From and To specs. This will append the Requester's Process ID onto the tracking value.

From	Type	Expression
	Expression	concat( $requestValue/types1:value, ' - Requester #', abx:getProcessId())
To	Type	Variable
	Variable	replyValue
	Query	types1:value

Add another Copy Operation to the Assign with the following From and To specs. This will append the Requester's Process ID onto the tracking value.

From	Type	Expression
	Expression	abx:getProcessId()
To	Type	Variable
	Variable	replyValue
	Query	types1:InstanceID

Since the expression we just created is using the ActiveVOS extension function getProcessId() we need to add the ActiveVOS extension namespace to the process. In the Outline View right click on the namespace node and select Add / Delcaration / Namspace. Set the following values in the Properties View:

Property	Value
Prefix:	abx
URI:	http://www.activebpel.org/bpel/extension

	Once the Copy Operation is complete, click on the Receive activity, then shift-click on the Assign and the Reply (in that order).
	Right-click on any of the activities and select Link Activities. Links appear, connecting the activities in the order they're to execute.
	Click anywhere in the empty canvas area, then click the Auto Layout button in the toolbar above the editor to rearrange the activities neatly.
	Save the process, which is now ready for deployment and a simple test. Note that it doesn't yet invoke the Responder - we'll be modifying it to do that in a later step.

A Quick Test of the Requester Process

Now would be a good time to simulate the Requester process. See the ActiveVOS Designer documentation for details on simulation if you choose to do so at this time.

To deploy and test the Requester process using the embedded ActiveVOS Server, first create a Process Deployment Descriptor.

	Right-click on the AsynchMessageExchange/bpel/Requester.bpel and select New / Deployment Descriptor.
	In the New Deployment Descriptor wizard, select the AsynchMessageExchange/deploy folder and click Finish. A new desciptor file appears in the PDD Editor.
	Set Deployment Platform to ActiveVOS Professional and Enterprise.
	Select the Partner Links tab at the bottom of the editor window and click on the RequesterPL Partner Link.
	Below the Partner Links listing, under My Role, change RequesterPLService to simply RequesterService.
	Save the descriptor file and close it.
	To deploy the process using this descriptor, the ActiveVOS Engine needs to be running first. In the Servers view (usually stacked with the Properties and Problems views), right-click on the server instance you want to start and select Start from the pop-up menu. A new Console view appears and after a few moments, the message "...ActiveVOS In-Memory Configuration Started" appears. The engine is now ready to receive deployed processes.
	Right-click on AsynchMessageExchange/deploy/Requester.pdd and select Export... from the pop-up menu. The Export wizard appears.
	Select Orchestration / Business Process Archive File and click Next.
	Under Select the export destination, enter (or navigate to and enter):
[path to extracted archive]\AsynchMessageExchange\deploy\Requester.bpr
	In the Deployment section, select a Type of Web Service and leave the default Deployment URL as-is.
	Under Options, check the Save the archive... button and enter the BPRD file name as:
/AsynchMessageExchange/deploy/Requester.bprd
	Check the Replace existing... checkbox and click Finish. The Requester process is deployed to the engine, as indicated by the Deployment Complete dialog.
If you see messages indicating errors during deployment, retrace the preceding steps to ensure that you've executed them all correctly.
	Click OK and note the additional log messages written to the Console view, indicating that the Requester process has been deployed.
	To verify deployment and locate the URL of the newly deployed service, click on the Open Web Browser icon in the toolbar: . Browse to the following URL:
http://localhost:8080/BpelAdmin
	When the ActiveVOS Engine Admin console appears, select Configuration from the menu on the left. Ensure that the Logging Level is set to Full and that Replace existing resources... is checked. Click Update to save these settings.
	Select Deployed Services from the menu on the left. Scroll down and click on RequesterService. The WSDL for our deployed process is displayed. Record the URL at the browser's location for testing, below. We'll also need this URL later, when constructing the Initiator web service client.

Web Services Explorer

With the Requester process successfully deployed, it's now ready for a quick test using the Eclipse Web Services Explorer - part of the Web Tools Plug-in included with ActiveVOS.

	Locate and select the Launch the Web Services Explorer icon in the toolbar:
	At the far right of the Web Services Explorer editor's caption bar, locate and select the WSDL Page icon: The editor is updated with Navigator, Actions and Status areas.
	In the Navigator area, click WSDL Main. The Actions area is updated for WSDL entry.
	Copy and paste the RequesterService's WSDL URL from the last step in the previous section into the WSDL URL text box . This is typically
http://localhost:8080/active-bpel/services/RequesterService?wsdl
	Click Go to enter the URL. The WSDL Binding Details appear in the Actions area.
	Click the initiate link - recall that this is the name of the operation exposed by the Requester process. Invoke a WSDL Operation appears in the Action area.
	Enter a string in the value textbox, under Document - recall that these are the names of the elements we defined in our XML Schema data type definition earlier - and click Go to invoke the operation.

After a moment, the Status area is updated with a response message:

value (string): [the request message text you entered] - Requester # 1

InstanceID (string): 1

The Requester process has accepted the incoming request and appended its process ID to that to create the response.

In general, use of the Web Services Explorer is a good first test for deployed BPEL processes and/or services. More complex tests require an actual web service client, which we'll build next.

<< Previous

Next >>