9.6 Developing message flows with Web services

< Day Day Up >

When you design a message flow, you must consider some or all of the following factors:

Which nodes provide the function that you require. In many cases, you can choose between several nodes that provide a suitable function. You might have to consider other factors listed here to determine which node is best for your overall needs.
Whether it is appropriate to include more than one input node.
Whether you can make use of subflows, for example, to define a specific output node with common properties.
What response times your applications expect from the message flow. This is influenced by several aspects of how you configure your nodes and the flow.
Whether you want to use WebSphere MQ cluster queues.
Whether you want your messages to go through data conversion.
What steps you can take to ensure that messages are not lost.
How errors are handled within the message flow. You can use the facilities provided by the broker to handle any errors that are encountered during message flow execution (for example, if the input node fails to retrieve an input message, or if writing to a database results in an error). However, you might prefer to design your message flow to handle errors in a specific way.

9.6.1 Development environment

The Message Brokers Toolkit is a component of the WebSphere Business Integration Message Broker product. It is the tool used to develop message flows and to deploy them to a broker.

WebSphere Studio Application Developer is designed for J2EE application programming and in these scenarios would be the tool of choice for creating the source and target applications.

Both of these tools can be used simultaneously on one system. An alternate to this would be to install the WebSphere Studio Application Developer Integration Edition with the Message Brokers Toolkit. This gives you J2EE programming tools, message flow programming tools, the WebSphere Application Server test environment, and broker management tools, all in one WebSphere Studio workbench.

9.6.2 Development steps

Three main steps are used:

Step 1: Create and test a Web client to access the service.
Step 2: Create and test a simple "passthru" message flow that invokes each Web service. This effectively tests the input to the flow, transformation between the input and output formats, the invocation of the Web service, and the reply.
Step 3: Add the broker logic to the message flow and test.

9.6.3 Step 1: Access the Web service directly

The first step is to Web service enable the client and target applications. Using a direct link between the two will allow you to ensure that the application interfaces are working correctly before adding the broker message flows between them (Figure 9-13).

click to expand
Figure 9-13: Step 1- direct access to Web service

Web service-enable the target application

Both WebSphere Studio and WebSphere Application Server provide tools that assist in converting an application to a Web service.

WebSphere Studio wizards

WebSphere Studio provides the Web Services wizard that creates a Web service from an existing application. The wizard allows you to select from the following Web service types:

Skeleton Java bean
Java bean
Skeleton EJB
URL
DADX
EJB
ISD

The wizard will create all the necessary files and deployment descriptors. In addition, you can create and test a client proxy.

WebSphere Application Server command line tools

WebSphere Application Server provides command line tools in the bin directory to help you generate the necessary files to make an application available as a Web service.

The steps to create a Web service from an EJB application would be:

Create a service endpoint interface that extends java.rmi.Remote.
Use the Java2WSDL command line tool to generate a WSDL file using the service endpoint interface as input.
Use the WSDL2Java command line tool to generate the Web services deployment descriptors using the WSDL file as input.
Use the endptEnabler command line tool to create an HTTP router.

Testing with the Web Services Explorer

WebSphere Studio provides a handy tool called the Web Services Explorer. This tool allows you to test a Web service using the WSDL file for the service. Using the tool, you can invoke different methods and alter or add service endpoints to test.

Web service-enable the client application

Both WebSphere Studio and WebSphere Application Server provide tools that assist in creating client code to invoke a Web service. The basis for both is the WSDL file from the target Web service.

WebSphere Studio wizards

WebSphere Studio provides the Web Services Client wizard that creates a Web service from a WSDL file.

Create a Web project.
Copy the WSDL file from the target application to the WebContent/WEB-INF folder.
Invoke the Web Services Client wizard from the context menu of the WSDL file.

The wizard will create the Java proxy code needed to call the Web service. Optionally, you can have the wizard generate a sample application to use for testing or as the basis for the Web application.

WebSphere Application Server command line tools

WebSphere Application Server provides command line tools in the bin directory to help you generate the Web service client code.

The steps to create Web client code would be:

Create a Web project.
Copy the WSDL file from the target application to the WebContent/WEB-INF folder.
Use the WSDL2Java tool to generate the Web service client deployment descriptors and classes.
Use the generated classes within your application to access the Web service. The JNDI name used to access the Web service is specified in the WebContent/WEB-INF/webservicesclient.xml file.

Extended Enterprise:

If you are using the Web Services Gateway to access external Web services, you must download the WSDL files (there will be two, an implementation and an interface) from the Web Services Gateway, and not from the target application. This is true regardless of the method you use to Web service-enable the client.

9.6.4 Step 2: Access the Web service using through message flow

The second step in developing the solution is to create a message flow that takes the input from the client, invokes the Web service, then returns the reply to the client. This step should be done for each Web service the final solution will invoke. This step will verify that:

The client connection to the broker is working
The broker can invoke the back-end Web service
The broker can return the correct reply to the client.

Figure 9-14 shows a message flow that can be used to accomplish this task.

click to expand
Figure 9-14: Passthru message flow

This message flow passes the Web service request from the Web services client through the HttpInput node to the HttpRequest node which then forwards the request to an external Web service. The response from the external Web service is returned to the Web services client through the HttpReply node.

The Web Service URL property of the HttpRequest node enables us to re-route the Web service request from WebSphere Business Integration Message Broker to the Web service without having to modify the SOAP message in a Compute or Mapping node. The response from Web services is returned to the Web service client via the HttpReply node without any modifications.

Build the message flow

Note

The Message Brokers Toolkit is used to create the message flows and deploy them to the broker.

This message flow passes the Web service request from the Web services client through the HttpInput node to the HttpRequest node which then forwards the request to the Wholesale1 Web service. The response from Wholesale1 is returned to the Web services client through the HttpReply node.

The Web Service URL property of the HttpRequest node enables us to re-route the Web service request from WebSphere Business Integration Message Broker to the Wholesale1 Web service without having to modify the SOAP message in a Compute or Mapping node. The response from Wholesale1 is returned to the Web service client via the HttpReply node without any modifications.

Open the Broker Application Development perspective.
Create a new message flow project and name it MBToWholesale1.
Create a new message flow in the project and call it Wholesale1.

Populate the message flow with HttpInput, HttpRequest and HttpReply nodes and connect the terminals as shown in Table 9-1.

Table 9-1: Wiring specifications for Wholesale1 message flow
Node	Terminal	Node
HttpInput	Out	HttpRequest
HttpInput	Failure	HttpReply
HttpRequest	Out	HttpReply
HttpRequest	Failure	HttpReply

To add a node, simple click the node in the Built-in nodes list, then click in the palette. Make sure the Select (versus Connection) option is highlighted at the top.

To wire a node, select the Connection option. Click the starting point, then the end point. If you hold the cursor over a node, a popup will tell you the node type (Out, Failure, etc.).

The Failure terminals are wired to the HttpReply node to return any errors to the Web services client. In a production system an alternative might be to pass the errors back to an administrative queue.

The URL selector property of the HTTPInput node defines how the broker will listen for input destined for this message flow. Define the following properties for the HttpInput node:
1. URL Selector: http://hostname:portid/identifier.
  
  Where hostname is the machine running the broker, and portid is the port number defined on the mqsicreatebroker command. If you didn't specify the -p option when creating the broker, the default port (7080) is used.
  
  In our example, the URL selector is http://kaa5070:7080/Wholesale1.
  
  We selected "Wholesale1" at random. Later, when you create the client you will use this URL to invoke the message flow.
2. Set the message domain to XMLNS (Figure 9-15).
  
  Figure 9-15: HTTPInput node properties
Define the following properties for the HttpRequest node:
1. In the Basic panel of the HttpRequest node properties type the URL of the Web service (Figure 9-16).
  
  Figure 9-16: HttpRequest node properties
2. On the Default panel select XMLNS as the Message Domain and click OK.
The default properties of the HttpReply node are acceptable as they stand.
Save the message flow.

Deploy the message flow

We will be using the test environment to act both as the Web services client and to provide the ConvertTemperature Web service interface.

Note

This process assumes that you have a broker, whether it is the unit test environment or a production broker up and running.

Open the Broker Administration perspective.
Create a broker archive (.bar) file in the Broker Archives/<server_name> folder. To do this, select the server folder, right-click, and select New -> Message Broker Archive. Enter a name for the archive file and click Finish.
The new archive file will open. The next step is to add one or more message flows to be deployed to the broker. The .bar file will be deployed to a specific execution group so keep this in mind when selecting the message flows to add. Using the Add icon, select the message flows to be added, then save the file (Figure 9-17).

Figure 9-17: Add message flows to the broker archive file
Deploy the bar file to the execution group using the Deploy File option from its context menu (Figure 9-18).

Figure 9-18: Deploy the archive
Open the event log for the broker domain by double-clicking the Event Log option in the Domains window. When the archive has been deployed you should get two messages in the event log that will indicate the success or failure of the deploy. If the deploy is successful, the message flow should be available for use.

When you need to make changes to the message flow, just update the message flow file, add it to the bar file again (no need to delete first), and re-deploy the bar file. The changes will automatically be deployed to the broker. You do not need to restart it.

Test the message flow

You can quickly test the message flow from WebSphere Studio by using one of the following methods:

Using the Web Services Explorer. This allows you to test the Web service without generating a client application.
Using the Web Services Client wizard to create a test client application.

In either case, the service endpoint used must be changed to point to the Message Broker message flow instead of directly to the Wholesale1 Web service:

http://kaa5070:7080/Wholesale1Direct/

Using the test client

When you generate Web services client code using the Web Services Client wizard, you have the option to test the client. If you select this option you get a simple application that consists of the following JSP files:

Input.jsp
Method.jsp
Result.jsp
TestClient.jsp

To test using a Web services client:

Start the test client by right-clicking TestClient.jsp and selecting Run on Server.
Select the setEndPoint method.
Enter the URL for the message flow (see Figure 9-15) and click Invoke.

Figure 9-19: Use setEndpoint to point the client to the message flow
To make sure the endpoint has changed, you can select getEndpoint and click Invoke. You should see the URL for the message flow in the Results window (Figure 9-20).

Figure 9-20: Use getEndpoint to ensure the endpoint is correct
Now, click the method you want to test (getDeliveryDate), enter a part number, and click Invoke (Figure 9-21).

Figure 9-21: Test the message flow

Using the Web Services Explorer

Add trace nodes to the message flow and monitor the WebSphere console if necessary:

Start the Web Services Explorer by clicking Run -> Launch Web Services Explorer.
1. Right-click the Wholesale1Direct.wsdl file and select Web Services -> Test with Web Services Explorer. The Web Services Explorer view will open.
2. Click the SOAP binding file in the Navigator panel and scroll down to find the Endpoints table in the right hand Actions pane of the view and click Add.
3. Modify the new endpoint to the URL we defined for the HttpInput node and click Go (Figure 9-22).
  
  Figure 9-22: Adding an endpoint to the Web Services Explorer
Select the getDeliveryDate operation and choose the new endpoint. Enter a part number and click Go. You should get the delivery date in the Results window (Figure 9-23).

Figure 9-23: Invoke the Web service using the new end point

Note

You can click the Source link in the Status window to explore the SOAP request and reply messages. You can verify that the flow went through the broker using the trace function

9.6.5 Step 3: Add the broker function

The final step is to add the logic to the message flows. In this example, the complete message flow process is handled by three message flows. The first flow performs the primary aggregation process. Two subflows are used to invoke the Wholesale1 and Wholesale2 Web services.

Build the primary message flow for aggregation

Figure 9-24 shows the primary aggregation message flow.

click to expand
Figure 9-24: Overview of the complete Aggregation flow

In summary, the main message flow is as follows:

An HTTP request enters the message flow at the HTTPInput node and is passed unchanged to a Compute node. The Compute node saves the HTTP header information in the local environment for later use.
It then passes the request to the AggregateControl node.

The AggregateControl node marks the beginning of a fan-out of requests that are part of an aggregation. It has a "name" property that is used to associate the fan-out message flow with the fan-in message flow (Figure 9-25).

Figure 9-25: Aggregation message flow - part 1
The AggregatorControl node fans out the request simultaneously in three directions:
1. In the first leg of the flow, Compute1 converts the incoming HTTP input into an MQ message. It passes the message to a message queue, where it will be picked up by the WebService1Request message flow. This message flow uses the Wholesale1 Web service to get a delivery date for the part number.
  
  The results are passed to the AggregateRequest node which records the fact that request messages have been sent and collects information that helps the AggregateReply node to construct the compound message.
  
  Each AggregateRequest node specifies a folder name which is used in the AggregateReply node's compound message to store the reply to this request (Figure 9-26).
  
  Figure 9-26: Aggregation message flow - part 2
2. The second leg of the flow (starting with Compute 4) is identical to the first, but the message is placed on a queue where it will be picked up by the WebService2Request message flow which invokes the Wholesale2 Web service (Figure 9-27).
  
  Figure 9-27: Aggregation message flow - part 3
  
  Note that Compute1 and Compute2 are identical and use the same ESQL compute module.
3. The third leg takes the HTTP headers saved to the local environment earlier (step 1) and places them on a message queue. They are picked up later by the Compute2 node and used to build the HTTP reply to the client (Figure 9-28).
  
  Figure 9-28: Aggregation message flow - part 4
The replies are gathered by the AggregateReply node and combined into a single compound message.

Note that the AggregateControl and AggregateReply node are logically tied together through the specification of a common aggregate name.

The AggregateReply node sends the aggregated replies to a Compute node where they are manipulated to get the desired output and then converted to an HTTP response using the HTTP headers saved previously (Figure 9-29).

click to expand
Figure 9-29: Aggregation message flow - part 5

The Compute node can address each portion of the aggregated reply using the folder names assigned in the AggregateRequest nodes. For example, the Compute node can inspect the returned delivery dates and select the earliest date to return to the Retail client. The Compute node uses the HTTP header information saved in step 3c to rebuild the HTTP response. This information is also addressed using the folder name assigned in the AggregateRequest node (Example 9-1).

Example 9-1: Compute module Aggregator2_Compute2

 CREATE COMPUTE MODULE Aggregator2_Compute2    CREATE FUNCTION Main() RETURNS BOOLEAN    BEGIN        DECLARE SOAP_NS NAMESPACE 'http://schemas.xmlsoap.org/soap/envelope/';        DECLARE SOAP_ENC NAMESPACE 'http://schemas.xmlsoap.org/soap/encoding/';        DECLARE MY_NS NAMESPACE 'http://inventory.wholesale.itso.ibm.com';        DECLARE MY_XSD NAMESPACE 'http://www.w3.org/2001/XMLSchema';        DECLARE MY_XSI NAMESPACE 'http://www.w3.org/2001/XMLSchema-instance';       SET OutputRoot.Properties.MessageFormat = 'XMLNS';       SET OutputRoot.Properties.Encoding = 546;       SET OutputRoot.Properties.CodedCharSetId = 437;       SET OutputRoot.Properties.ExpirationTime = -1;       SET OutputRoot.Properties.Priority = 0;       SET OutputRoot.Properties.ReplyProtocol = 'MQ';       SET OutputRoot.Properties.Persistence = FALSE;       DECLARE s1 CHARACTER;       DECLARE s2 CHARACTER;       SET s1 = SUBSTRING(InputRoot.ComIbmAggregateReplyBody.W1.XMLNS.SOAP_NS:Envelope.SOAP_NS:Body.MY_NS:getDe liveryDateResponse.getDeliveryDateReturn FROM 7 FOR 4)           || '-' || SUBSTRING(InputRoot.ComIbmAggregateReplyBody.W1.XMLNS.SOAP_NS:Envelope.SOAP_NS:Body.MY_NS:getDe liveryDateResponse.getDeliveryDateReturn FROM 1 FOR 2)           || '-' || SUBSTRING(InputRoot.ComIbmAggregateReplyBody.W1.XMLNS.SOAP_NS:Envelope.SOAP_NS:Body.MY_NS:getDe liveryDateResponse.getDeliveryDateReturn FROM 4 FOR 2);       SET s2 = SUBSTRING(InputRoot.ComIbmAggregateReplyBody.W2.XMLNS.SOAP_NS:Envelope.SOAP_NS:Body.MY_NS:getDe liveryDateResponse.getDeliveryDateReturn FROM 7 FOR 4)           || '-' || SUBSTRING(InputRoot.ComIbmAggregateReplyBody.W2.XMLNS.SOAP_NS:Envelope.SOAP_NS:Body.MY_NS:getDe liveryDateResponse.getDeliveryDateReturn FROM 1 FOR 2)           || '-' || SUBSTRING(InputRoot.ComIbmAggregateReplyBody.W2.XMLNS.SOAP_NS:Envelope.SOAP_NS:Body.MY_NS:getDe liveryDateResponse.getDeliveryDateReturn FROM 4 FOR 2);       DECLARE d1 DATE;       DECLARE d2 DATE;       SET d1 = CAST(s1 as DATE);       SET d2 = CAST(s2 as DATE);       IF (d1 > d2)       THEN       SET OutputRoot.XMLNS = InputRoot.ComIbmAggregateReplyBody.W1.XMLNS;       ELSE       SET OutputRoot.XMLNS = InputRoot.ComIbmAggregateReplyBody.W2.XMLNS;       END IF;       SET OutputLocalEnvironment.Destination.HTTP.RequestIdentifier = CAST( InputRoot.ComIbmAggregateReplyBody.HTTPRequestIdentifier.XMLNS.SavedHTTPContext.Destination.HTT P.RequestIdentifier AS BLOB);       RETURN TRUE;    END;    CREATE PROCEDURE CopyMessageHeaders() BEGIN       DECLARE I INTEGER 1;       DECLARE J INTEGER CARDINALITY(InputRoot.*[]);       WHILE I < J DO          SET OutputRoot.*[I] = InputRoot.*[I];          SET I = I + 1;       END WHILE;    END;    CREATE PROCEDURE CopyEntireMessage() BEGIN       SET OutputRoot = InputRoot;    END; END MODULE;

A separate message flow is needed for the queue that will hold the saved HTTP header information (Figure 9-30).

Figure 9-30: Aggregation message flow - part 6

Build the message flows to invoke the Web services

There are two additional message flows used (Figure 9-31). These flows invoke the Wholesale1 and Wholesale2 Web services to get delivery dates for the part number supplied by the Retail client. Each is identical with the exception of the message queue they pick up the input from and the Web service URL they invoke.

click to expand
Figure 9-31: Aggregation message flow - part 7

The additional challenge here is that the message is now in MQ format but the Web services require HTTP format, so once again, we must convert the message for processing.

In this flow:

The input has been converted into an MQ message by the primary message flow and placed on a message queue. This flow picks the message off the queue and passes it to a Compute node.
The Compute node builds an HTTP message and passes it to the HTTPRequest node.
The HTTPRequest node invokes the Wholesale Web service.
The response is converted back to an MQ message by the Compute node and passed to the MQReply node where it is placed on the response queue.

Extended Enterprise:

If you are using the Web Services Gateway to access external Web services, the Web service URL in the HTTP Request node must be the location found in the implementation WSDL file:

 <soap:address location="http://wsgw.itso.ral.ibm.com:9080/wsgwsoaphttp1/soaphttpengine/urn %3Aibmwsgw%23Wholesale1"/>.

Deploy and test the message flows

Deploy and test the message flow using the same techniques outlined in , "Deploy the message flow" on page 248 and , "Test the message flow" on page 249.

Update the client application

Update the client application so that the Web service endpoint used is the URL specified in the HTTPInput node.

< Day Day Up >