WebSphere Message Brokers
File: ac34570_
Writer: Jane Brockbank

Task topic

This build: July 31, 2007 21:20:22

Detail of how the broker implements a new Web service

This topic provides an overview of a typical end-to-end scenario where the broker implements a Web service.

An existing C or COBOL based system offers some business logic which can usefully be exposed as a Web service.

The broker can start the operation on the existing system, that is, the system exposes an interface to the broker. Typically the existing system would be enabled for WebSphere MQ, meaning that it receives MQ messages containing application data, dispatches these to the underlying implementation and then packages the return values as an MQ response. The data structures supplied to, and returned by, these existing operations are defined in a C header file or COBOL copybook.

The Web service offers an interface based on the operations already exposed by the existing system. This interface might comprise all of the existing operations, or a subset of the existing operations or composite operations, or both.

To define your interface:
  1. Look at the business function offered by the existing system.
  2. Select the subset of this business function to be exposed.
  3. Decide how to represent the subset in the interface, that is, as many discrete operations, or as fewer multipurpose operations.
You must decide whether you want the Web service interface to be RPC-style or document-style. For more information about Web services, WSDL and message flows, and the relationship of WSDL to the Message Model refer to the related links.
  • An RPC-style interface is generally designed to map on to an underlying set of operations provided by some API, and the individual operations (method calls) have relatively small payloads.
  • A document-style interface might have fewer operations each with a larger payload, for instance this might be a document representing a loan request.
The WS-I (see http://www.ws-i.org/) recommend the use only of document-style WSDL, but many older Web services use RPC-style.

To implement the scenario:

  1. Import the existing API data structures, for example using the C importer. If document-style WSDL is to be used, you must use the importer wizard to create the required global elements in the broker model. The WS-I recommends that the Web service payload must be namespace qualified, therefore the user must specify the target namespace on the import.

    You now have a message model for the data to be used to start the existing operations.

  2. Generate the WSDL definition. Unless you have already created the required Message Categories, create a Message Category for each Web services operation to be exposed and associate the existing broker messages with the appropriate SOAP roles (input, output or fault). For more information refer to Working with a message category file.
    • If you choose document-style WSDL, the message set itself is not modified.
    • If you choose RPC-style WSDL, messages corresponding to the request and response for each WSDL operation are created and added to the message set automatically.
  3. The WSDL generation step results in the appropriate SOAP mxsds (message definition files), which includes the SOAP envelope mxsd and (if the WSDL style is RPC-encoded) the SOAP encoding mxsd, being automatically included in the message set.
  4. If you want to create a new Web services client, use the generated WSDL with your chosen Web services client technology. Use a tool other than WebSphere Message Broker, for example, you can use Rational Application Developer or .NET.
  5. Implement a message flow to receive the Web service request, that is, to act as the Web services provider. The endpoint nodes are HTTP or MQ depending on the transport used by the client. The input node properties are:
    • Message Domain: MRM
    • Message Set: the message set containing the SOAP Envelope definition
    • Message Type: Envelope
    • Message Format: XML1
  6. When the parser is started by the flow the parser creates a logical tree comprising the SOAP envelope as defined by the pre-canned SOAP mxsd. Parsing continues automatically at the attachment points within the SOAP envelope (SOAP body and header), attempting to match against other message definitions in the message set. You can apply validation at the input node if you require.

    You now have a logical tree, but you do not know which SOAP payload has been received. Check the HTTP SOAPAction action field to determine the likely content, but this check works only for HTTP. (Use of SOAPAction is not recommended by the WS-I.)

  7. You can provide mapping from the allowed payload messages to the required messages from the existing system. For example, you can have a single mapping definition with messages message1a and message1b both mapped to the same target message2.
    Alternatively you can provide separate mappings for each message type, or for groups of related message types. This approach might result in more manageable and reusable mapping definitions. The disadvantage is that you have to determine which payload has been received before you can apply the mapping. You can determine which payload has been received by using ESQL as follows:
     
     DECLARE SOAPENV NAMESPACE 'http://schemas.xmlsoap.org/soap/envelope/';
     SET contentType = FIELDNAME(InputBody.SOAPENV:Body.*[<]);
     IF (contentType = ‘foo’) ...
     
    or you can use a field reference, for example:
     
     DECLARE R REFERENCE TO InputRoot.MRM.SOAPENV:Body.*[<];
     IF (FIELDNAME(R) = “foo”) ...
     
    When you have determined the payload, you can map the flow to branch appropriately (for example, using a RouteToLabel node) with each branch having either a content-specific Mapping node or Compute node, or both. For simple flows all the logic can be kept in a single Compute node if required.

    Now start the existing system (typically over WebSphere MQ), retrieve any expected response, and propagate the Web service reply. The dataflow designer must account for the possibility that the business application does not send the expected response in a reasonable period of time.

For a similar scenario, see the following sample: You can view samples only when you use the information center that is integrated with the Message Brokers Toolkit.
Related concepts
Web services, WSDL and message flows
Broker calls existing Web service
Broker implements new Web service interface
Broker implements existing Web service interface
Broker implements non-web-service interface to new Web service
Relationship of WSDL to Message Model
Related tasks
Broker implements existing Web service interface - detail
Broker calls existing Web service - detail
Working with a message category file
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:20:22

ac34570_ This topic's URL is: