What's new in WebSphere Enterprise Service Bus V6.2, Part 2: Service gateway patterns

This article series describes new and enhanced features in WebSphere ESB V6.2 and its associated tooling, WebSphere Integration Developer, including transport protocol bindings, data binding capabilities, mediation primitives, and declarative flow control. Part 2 describes the Service Gateway and Service Policy features.

Brian Hulse (brian_hulse@uk.ibm.com), Senior Software Engineer, WebSphere Service Registry and Repository, IBM

Brian Hulse photoBrian Hulse was a Senior Software Engineer on the WebSphere Enterprise Service Bus team, and is now doing a similar job on the WebSphere Service Registry and Repository team. He has worked in software development at the IBM Hursley Lab in the UK for over 20 years, the last seven of which have been in the SOA arena. You can contact Brian at brian_hulse@uk.ibm.com.



Callum Jackson (callumj@uk.ibm.com), Software Engineer, IBM

Photo of Callum Jackson Callum Jackson is a Software Engineer on the WebSphere ESB team at the IBM Hursley Software Lab in the UK. He has worked on the WebSphere ESB team since 2005, and before that he worked in Software Services on SOA applications for the telecommunications industry. You can contact Callum at callumj@uk.ibm.com.



Fenglian Xu, Software Engineer, IBM

Photo of Fenglian XuDr. Fenglian Xu is a Software Developer on the WebSphere Enterprise Service Bus Development team at the IBM Hursley Software Lab in the UK. Her expertise includes WebSphere MQ JMS bindings, WebSphere Application Server, and WebSphere Enterprise Service Bus. She has worked in various IT companies on both middleware to applications, and with the UK eScience pilot project GEODISE, which involved workflow and SOA. She received a B.Sc. in Applied Math and Software Engineering from Xian Jiaotong University in China in 1989, and a Ph.D. in Computer Science from the University of Southampton in the UK in 1998. You can contact Fenglian at xufengli@uk.ibm.com.


developerWorks Contributing author
        level

10 June 2009

Also available in Chinese Spanish

Introduction

This article series describes the new features in IBM® WebSphere® Enterprise Service Bus V6.2. Part 2 introduces the service gateway patterns and shows you how to create a service gateway for Web services.

What is a service gateway?

A service gateway is an entity that can receive any message, perform some generic processing (such as logging the message or adding a header to it), and then route the message to its destination. This definition raises the question of service gateway classification -- does the "generic processing" involve modifications to the body of the message? WebSphere ESB has two types of service gateways:

Dynamic service gateway (body agnostic)
A gateway pattern that modifies only the message header information.
Static service gateway (body aware)
A gateway pattern that modifies the information in the body and the header of a message.

Later in this article, these patterns will be translated into the SCA patterns required to implement both gateway types.

Enhancements to the WebSphere ESB programming model

Integrating support for the service gateway patterns into WebSphere ESB has involved several extensions to the programming model. This section describes these enhancements.

New mediation primitives

WebSphere ESB mediation primitives are reusable building blocks that application developers can use to build mediation flows. As part of the service gateway support, two new primitives have been implemented:

  • DataHandler
  • TypeFilter

DataHandler primitive

The DataHandler primitive can be used to convert from one message structure to another. This primitive differs from previous transformation primitives such as XSLT, BO Mapper, and Message Element Setter in that the transformation is between a wire format (such as JMSTextBody) and a business object. The other transformation primitives convert one business object structure into another business object.

As the name suggests, the DataHandler primitive lets mediation developers use the custom-written DataHandler within WebSphere ESB to transform the message body from one format to another. Mediation developers can then defer the parsing of the message past the export and complete it only if required within the Mediation Flow component. A simple example of this behaviour is displayed in writing a JMS mediation. The export and import can be configured with the JMS Text DataBinding that places the content of the inbound message into a generic structure. Within the Mediation Flow component, body manipulation may be needed, requiring the message to be transformed from the protocol format into a business object that allows other primitives to access and manipulate the message body.

As it does with other mediation primitives, WebSphere Integration Developer provides tooling to associate properties and terminals with the DataHandler primitive, enabling you to customize DataHandler behaviour. The DataHandler properties view lets you configure the two actions:

Figure 1. DataHandler detail property panel
DataHandler detail property panel

The DataHandler primitive has the following properties:

  • DataHandler configuration -- Identifies the dataHandler class or configuration that will be used by the primitive. Click Browse to open the DataHandler configuration window and select a valid configuration.
  • Output message field refinements -- This table provides the same capability as the SetMessageType primitive but is embedded within the DataHandler primitive. It lets mediation developers assert weakly typed fields of the SMO to concrete types. However, unlike the SetMessageType primitive that does not complete any processing at runtime (unless validation is enabled), these assertions are critical to the processing of the DataHandler primitive. The input and output messages of a DataHandler primitive can be different, and therefore the DataHandler primitive has to generate a completely new output message in this situation. If the XPath location indicated by the value of the Target XPath field navigates through a weakly typed construct within the message, it needs to understand what the weakly typed construct should be in this instance. In Figure 1 above, the output terminal has an anyType element specified at /body/message. An assertion is made for /body/message defining the type to be {http://com.ibm.wbiserver.gateway/schema}TextBody. Therefore, when the Target XPath is selected, you can navigate to /body/message/value.

Action -- Two actions are supported:

  • Convert from native data format to a business object -- This translates to calling the transform method of the specified DataHandler. An example of when this action could be used is if the SMO included a comma-delimited string value and this had to be parsed into a specific BO.
  • Convert from a business object to native data format -- This translates to calling the transformInto method of the specified DataHandler. An example of when this action could be used is if a BO had to be converted into a comma-delimited string.

Source XPath -- Represents the location of the object in the source SMO that should be passed into the DataHandler. For example: /body/operation1/input1/value.

Target XPath -- Represents the location in the target SMO, where the output from the DataHandler should be stored. The target SMO is defined as the type of the output terminal. The DataHandler primitive has one input terminal, one output terminal, and one fail terminal

Figure 2. DataHandler mediation primitive
DataHandler mediation primitive
Table 1. DataHandler terminals
Terminal TypeNameDescription
InputinThis terminal receives the incoming message.
OutputoutThis terminal is fired once when the transformation has been completed by the DataHandler.
FailfailThe terminal fires when the primitive experiences an unexpected failure.

Type Filter primitive

The Type Filter primitive provides the capability to query the instance message to determine if it is one of several configured types. For more information, see Part 1 of this series.

New binding capabilities

The service gateway pattern is implemented across the entire Mediation module and not limited to the Mediation Flow component. Several new binding capabilities have been added:

Service gateway interface

New to V6.2 is the service gateway interface, supplied with WebSphere Integration Developer. It can receive all messages into a service gateway regardless of type. This interface must be used when creating any service gateway as many of the automation steps are dependent on this interface being present.

Figure 3. Service gateway interface
Service gateway interface

While it may appear that the weakly typed fields of the service gateway interface are intended to hold the actual business object that would be generated if the request were handled by a normal concrete typed binding, this is not the case. Any message received by the service gateway will be wrapped into a protocol level business object (such as the TextBody for Web services) and this will be placed within the anyType of the message field. The reason for the weakly typed field is to allow a single interface to handle a number of types of requests, namely JMS, MQ, HTTP, and Web service requests:

Figure 4. Service gateway Interface possible assertions
Service gateway Interface possible assertions

As shown in Figure 3, the service gateway interface has two operations: requestOnly and requestResponse. The requestOnly message handles any one-way message requests, and the requestResponse handles any two-way message requests.

Messaging binding support

The service gateway pattern supports all JMS and MQ messages into the system. To support these message types, a service gateway data binding and function selector for each protocol is provided. The data binding determines the type of the inbound message and generates one of the five built-in JMS business object types:

  • JMSTextBody
  • JMSBytesBody
  • JMSMapBody
  • JMSStreamBody
  • JMSObjectBody

You should use the service gateway data binding whenever an Export or Import is generated using the service gateway Interface. The current predefined JMS data bindings are only capable of converting to one of these business object types, while the service gateway data binding can convert to all five types.

The service gateway function selector provides a built-in mechanism to determine if the inbound message is one-way or two-way. The function selector is only one possible mechanism to determine the operation type; customers are free to create and implement their own function selectors. Out of the box, the JMS function selector looks for a named replyTo queue within the message header property, and if one is found the request is assumed to be a two-way operation. If this field is not found, a "one-way" operation is assumed. In comparison, the MQ function selector queries the MsgType field of the request from the MQ message descriptor (MQMD), and if it is defined as MQMT_REQUEST, the request is assumed to be two-way; otherwise if it is set to MQMT_DATAGRAM, the operation is assumed to be one-way.

HTTP Binding support

Similar to the messaging binding, a data binding and function selector for the HTTP binding has been supplied as part of WebSphere ESB V6.2. The HTTP service gateway data binding determines if the content type is text/* and if so, it places the body of the message into the HTTPText business object. Otherwise the HTTPBytes business object is used.

The HTTP protocol itself does not have any mechanism to determine if the inbound message is a one-way or two-way request, which complicates the processing of a function selector. A solution is to append a parameter argument of operationMode=oneway onto the URL. For instance, if the following URL was received: http://www.anywhere.com/serviceGatewayA, the function selector assumes the request is two-way. But if the URL is: http://www.anywhere.com/serviceGatewayA?operationMode=oneway, the function selector assumes the request is one-way.

Web service binding support

The Web service binding is also supported in the service gateway pattern. In this case, data handler and function selector capabilities were added to the JAX-WS binding and a service gateway data handler and function selector created. The new support within the Web service binding is illustrated below:

Figure 5: Web service binding function selector and data handler support
Web service binding function selector and data handler support

The Web service data handler processes all messages in the same manner, placing the raw XML data from the Web service binding directly into the TextBody business object structure. This means that the data held within the business object is unparsed, providing a performance benefit in some situations since the data has not been through a process of inflation into a concrete business object. However, a disadvantage is that accessing the body of the message is practically impossible without processing the message with a DataHandler primitive.

The Web service function selector works in the same manner as the HTTP function selector to determine if the operation is one-way or two-way.

Tooling Accelerator for the service gateway

In WebSphere Integration Developer V6.2, a new patterns wizard has been created to help in the generation and configuration of the service gateway artifacts. The wizard allows for the creation of both dynamic and static service gateways, and will be used in the next section on creating a service gateway.


Implementing a service gateway

Implementing a service gateway is a three step process:

  1. Determine the service request type for the message
  2. Determine the network addressable end-point to forward the request to
  3. Complete the common processing required by the gateway

First, to determine the service request type, there are many possible solutions:

  • WS addressing information
  • SOAP action
  • SOAP headers
  • URL information -- For instance, if the endpoint of the gateway is http://anywhere.com/serviceGateway the service name can be added on as a parameter: http://anywhere.com/serviceGateway?serviceName=serviceA.

The identifier has to be unique within a particular service gateway for the type of message.

Now that the identifier has been determined, it has to be translated into a network-addressable endpoint to forward the message to. There are many options available:

  • WebSphere Service Registry and Repository using the Endpoint Lookup primitive -- The service identifier can be passed into WebSphere Service Registry and Repository using the User Properties section.
  • WebSphere Service Registry and Repository using policy and the Policy Resolution primitive -- Using the service identifier in a gate condition on a policy attachment document, you can apply different mediation policies, each describing a different endpoint. This topic will be described in Part 3.
  • DB Lookup Primitive -- Using a DB table with the service identifier mapping to the real endpoint location.
  • Custom code -- Writing custom code to map the service identifier to a real endpoint location, which enables integration into third-party systems.

Finally, the common processing for the service gateway needs to be completed, which depends on the functionality required. It can be as trivial as placing a logging primitive on the canvas, or as complex as requiring access to and manipulation of the body of the message using several mediation primitives.

Implementation patterns for the service gateway

There are two mediation module implementation patterns for the service gateway: Dynamic service gateway and static service gateway.

Figure 6: SCA implementation of a dynamic service gateway
SCA implementation of a dynamic service gateway
  1. Numerous clients send in service requests to a single endpoint, which is exposed via an export binding.
  2. The export binding is configured with the service gateway interface and either a Web services, HTTP, JMS, or MQ binding with the service gateway data handler/data binding and function selector defined.
  3. The mediation flow component is defined with the service gateway as an interface and reference. Any common processing is completed during this phase, such as logging the service request.
  4. The target address of the service is determined using information contained within the service message object.
  5. The import binding is configured with the service gateway interface and either a Web services, HTTP, JMS, or MQ binding with the service gateway data handler/data binding and function selector defined
  6. A response is returned by the service, which can also have a common processing phase, such as logging of the message.

The second pattern is Static service gateway and is represented in SCA as:

Figure 7: SCA implementation of a Static service gateway
SCA implementation of a Static service gateway
  1. Numerous clients send in service requests to a single endpoint, which is exposed via an export binding.
  2. The export binding is configured with the service gateway interface and either a Web services, HTTP, JMS, or MQ binding with the service gateway data handler/data binding and function selector defined.
  3. The mediation flow component is defined with the service gateway as an interface and reference. Any common processing is completed during this phase, such as logging the service request. Access to the body of the message is required during this phase since a filter primitive is used to separate the requests into their subsections.
  4. Each message type is then passed into a DataHandler primitive that converts the protocol wrapper business object into a concrete business object, letting downstream primitives to modify the body of the message.
  5. Using transformation primitives, the message is modified as required.
  6. The import binding is configured with the specific service interface selecting any relevant data handler/data binding and function selectors required.
  7. A response is returned, and after any processing on the message, the concrete response business object is converted to the protocol wrapper business object using a DataHandler primitive.

Creating your first service gateway

This section shows you how to create a dynamic service gateway that will log all messages as they pass through the system. The scenario is based on a book ordering company with two basic Web services:

  1. Book Dispatching service -- Sends a message to the warehouse to dispatch the book to the customer.
  2. Billing service -- Charges the customer's credit card for the purchase.
    Figure 8: Architecture of Logging service gateway
    Architecture of Logging service gateway

As this article is focused on the service gateway, the end services have been supplied in the attached project interchange file and the details of their behaviour is not covered. In order to test the services, use the Web Service Explorer. The service gateway developed in this section uses the URL approach described above to determine the service identification, as shown in Figure 8 above.

To remove dependencies from the article, custom Java™ code is used to complete the mapping from the service identifier to the addressable endpoint. In Part 3, the scenario will be extended to extract the endpoint from WebSphere Service Registry and Repository via mediation policies.

You should be familiar with the basic concepts of application construction within WebSphere Integration Developer and more specifically, mediation development.

  1. Start WebSphere Integration Developer with a new workspace.
  2. Import the project interchange file ServiceGatewayEndServices.zip.
    1. Select File => Import.
    2. Select Other => Project Interchange.
    3. Select the Project Interchange file and click Finish:
      Figure 9. Imported sample services
      Imported sample services
  3. Create a new Dynamic service gateway called BookOrderGateway.
    1. Select File => New => Service Gateway.
    2. For the Service Gateway name enter BookOrderGateway and click Next.
    3. Select the Dynamic option and click Next.
    4. As mentioned previously, the routing logic will be written in Java code to simplify the dependencies, and the logging will occur to the standard WebSphere ESB database. In order to make this happen, select Write my own logic and Log messages in a database and click Next:
      Figure 10: Select the routing and logging options for the Gateway
      Select the routing and logging options for the Gateway
    5. The back-end Web services have been generated as SOAP 1.1 services; select Web Service (SOAP 1.1/HTTP) and click Finish. A new mediation module will be generated with the assembly diagram as shown below:
      Figure 11: Initial service gateway created by the wizard
      Initial service gateway created by the wizard
  4. Double-click on the BookOrderGateway Mediation Flow Component and the Mediation Flow Editor will be loaded.
  5. As both back-end services are two-way operations, only the requestResponse operation needs to be implemented. The requestOnly flow needs a small fix so it does not cause any issues at deployment time. Select RouteMessage custom mediation and delete it. Additionally, wire the LogMessage primitive to the CallOut node as shown below:
    Figure 12: One way operation fix up
    One way operation fix up
  6. Now, considering the two-way flow, select the requestResponse operation:
    Figure 13: Mediation flow automatically generated by the wizard
    Mediation flow automatically generated by the wizard
  7. The first task for a service gateway is to retrieve the service identifier, which could be completed directly in the RouteMessage custom mediation, but for future extensibility this logic will be separated into a dedicated primitive.
    1. First, create a new business object to hold the service identifier: Select File => New => Business Object.
    2. Select BookOrderGateay for the Module and enter the name of the business object: ServiceIdentification.
    3. Click Finish.
    4. Add a field called ID and of type String, and Save the file.
      Figure 14: Service Identification business object
      Service Identification business object
    5. Add the ServiceIdentificationbusiness object as the Transient context.
    6. Extend the Transformation section of the Palette.
    7. Select the Message Element Setter primitive and place it onto the canvas.
    8. Rename the primitive ExtractServiceIdentifier.
    9. Delete the wire between the Input node and the LogMessage primitive.
    10. Wire the ExtractServiceIdentifier between the two, as shown below:
      Figure 15: Wire the Message Element Setter primitive into the flow
      Wire the Message Element Setter primitive into the flow
    11. Select the ExtractServiceIdentifier primitive and in the properties panel click Add.
    12. Fill in the details as shown below:
      Figure 16: Add/Edit Properties
      Add/Edit Properties
  8. The final stage is to implement the routing logic with the RouteMessage primitive, which will retrieve the value within the transient context and forward it on to the relevant service. The code has been written for the back-end services running on the default port 9080 and the local machine. If these values are incorrect, the code will need to be customized. Copy the following code into the primitive:
    String port = "9080";
    String hostname = "localhost"; 
    String URI = "http://"+hostname+":"+port+"/";
    String serviceIdentification = 
     ((commonj.sdo.DataObject)smo.getContext().getTransient() ).getString("ID");
    if(serviceIdentification.equals("billing"))
       {
          URI = URI + "BillingServiceWeb/sca/BillingExport";
       }
       else if(serviceIdentification.equals("dispatch"))
       {
          URI = URI + "DispatchingServiceWeb/sca/DispatchExport";
       } 
    com.ibm.websphere.sibx.smobo.TargetAddressType targetAddress = 
       com.ibm.websphere.sibx.smobo.ServiceMessageObjectFactory
       .eINSTANCE.createTargetAddressType(); 
    targetAddress.setAddress(URI);
    smo.getHeaders().getSMOHeader().setTarget(targetAddress);
    out.fire(smo);
  9. Save the modifications to the Mediation Flow Editor: Click Ctrl + S.
  10. Start the built-in WebSphere ESB or WebSphere Process Server Test Environment and deploy all three applications: BillingService, DispatchingService, and BookOrderGateway.
  11. Test the services:
    1. Expand the back-end service project in the Business Integration Navigator: Billing Service => Web Service Ports.
    2. Right-click on BillingExport_BillingHttpPort and select Web Services => Test with Web Service Explorer.
    3. The endpoint currently selected will forward the request to the real service. To redirect it click Add next to the Endpoint section and enter: http://localhost:9080/BookOrderGatewayWeb/sca/BookOrderGatewayExport?serviceName=billing
      or http://localhost:9080/BookOrderGatewayWeb/sca/BookOrderGatewayExport?serviceName=dispatch, customizing the URL for the server's configuration. Click Go:
      Figure 17: Updated Endpoint information
      Updated Endpoint information
    4. Select the operation, fill in the relevant details, and click Submit.

Conclusion

Dynamic service gateway
Accepts multiple client requests and performs common processing on the message headers before forwarding the message to different back-end services via a single import.
Static service gateway
Accepts multiple client requests and performs common processing on both the message header and body.

Downloads

DescriptionNameSize
A completed Service Gateway projectServiceGatewayDynamicComplete.zip32 KB
Back-end services for this articleServiceGatewayEndServices.zip19 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=396644
ArticleTitle=What's new in WebSphere Enterprise Service Bus V6.2, Part 2: Service gateway patterns
publish-date=06102009