WebSphere Message Brokers
File: ac34580_
Writer: Jane Brockbank

Task topic

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

Broker implements existing Web service interface - detail

This is an overview of a typical end-to-end scenario where you have a Web service client and you want the broker to make some existing non-web-service functionality available to it.

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

Like the previous example (Detail of how the broker implements a new Web service), there is some mechanism for the broker to invoke operations on the existing system (i.e. 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.

However in this example there is also a constraint on what the Web service must look like, that is, we already have the WSDL definition for the Web services client.

A possible scenario would be that a widely distributed Web services client already gives users access to a particular business capability and the role of the broker will be to offer the same interface to a new implementation based on the existing system. Perhaps the original Web services provider offers a different quality of service or is to be discontinued for some reason.

As before, the broker can invoke the existing system function over WebSphere MQ.

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 have the importer wizard create the required global elements in the broker model. The WS-I (see http://www.ws-i.org/) recommends that the Web service payload be namespace qualified, so the user should specify the target namespace on the import.

    At this stage you have a message model for the data to be used in invoking the existing operations.

  2. Import the existing WSDL file to create the appropriate message model for the expected instance documents (see Importing data structures). The flow will parse the corresponding SOAP request and will need to transform to and from the required existing data format. You can inspect the imported message definitions and use the ESQL and/or Mapping editors to help create the flow. You do not create category files or generate WSDL from the broker model.
  3. The WSDL import step will result in the appropriate SOAP mxsds being automatically included in the message set. Specifically this includes the SOAP envelope mxsd and – if required – the SOAP encoding mxsd.
  4. 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:
    • domain: "MRM"
    • set: the message set containing the SOAP Envelope definition
    • type: "Envelope"
    • format "XML1"
  5. When invoked 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. Apply validation at the input node if required.

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

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

    Now invoke the existing system (typically over WebSphere MQ), retrieve any expected response, and propagate the Web service reply. This is like the previous scenario (Detail of how the broker implements a new Web service), except that the dataflow must also map between the data format used by the Web service client and the format used by the existing system enabled for WebSphere MQ. The dataflow designer must account for the possibility that the business application does not send the expected response in a reasonable period of time.

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
Related tasks
Broker implements existing Web service interface - detail
Broker calls existing Web service - detail
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

ac34580_ This topic's URL is: