About the Address Book sample

The Address Book sample shows you how to use the SOAPInput, SOAPReply, and SOAPRequest nodes to both provide and consume a Web service through an HTTP or JMS transport.

The starting point for the sample is a WSDL file that defines an address book service, see WSDL file. The WSDL file contains bindings for the HTTP and JMS transports and defines two operations: one to store addresses, and one to retrieve them. If you have access to WebSphere Application Server you can interchange the provider and consumer included with this sample with the provider and consumer provided with the Address Book sample in WebSphere Application Server for SOAP over HTTP. The Address Book sample provided with WebSphere Application Server does not support the SOAP over JMS transport. To support the SOAP over JMS transport, you must regenerate the WebSphere Application Server Web Service sample by adding a JMS binding and port to the WSDL. See the WSDL file provided with this sample.

To create the message set and a blank message flow for the provider, use the "Start from WSDL and/or XSD files" wizard with the WSDL file. You can then create a consumer flow manually.

The Address Book sample demonstrates the following tasks:

1. How to provide a Web service by using the SOAPInput and SOAPReply nodes.
2. How to consume a Web service by using a SOAPRequest node.

The message flows

The Address Book sample uses two message flows. The first message flow provides a Web service and the other message flow consumes a Web service.

Provider flow

The following diagram shows the Web service provider message flow:

The following table shows the nodes in the Web service provider message flow.

The flow is constructed by using a SOAPInput and a SOAPReply node. To automatically enter all of the properties for the SOAPInput node, drag the WSDL file onto the SOAPInput node. (The WSDL file is located in the message set project only after you have used the "Start from WSDL and/or XSD files" wizard.)

The SOAPInput node receives incoming SOAP messages and, if the messages are valid, passes them down the message flow to the RouteToLabel node. The RouteToLabel node forwards the message to the Label node, the name of which is located in the local environment (OutputLocalEnvironment.Destination.RouterList.DestinationData[1].labelname). You do not have to set this path explicitly when you are working with incoming SOAP messages because the SOAPInput node automatically sets the path to the name of the operation being called. However, you must connect the SOAPInput node to a RouteToLabel node and create a Label node for each operation.

If the operation being called is saveAddress, the message is sent to the SaveCompute node, where the address is stored in a shared ESQL variable. Shared variables last for the scope of the message flow; if you redeploy the message flow you lose any saved addresses.

If the operation being called is findAddress, the message is sent to the FindCompute node, where the shared variable is queried for the address of the person whose name is supplied in the input message. If the address is found, the address is returned; if the address is not in the shared variable, a SOAP fault is constructed.

Consumer Flow

The following figure shows the Web service consumer message flow:

The following table shows the nodes in the Web service consumer message flow:

The Web service consumer flow is initiated by a WebSphere MQ message arriving on the queue monitored by the MQInput node. The message is an XML message in the XMLNSC domain. To use the RouteToLabel node, you must set the value in the local environment explicitly for this flow by using the RoutingCompute node:

OutputLocalEnvironment.Destination.RouterList.DestinationData[1].labelname = InputRoot.XMLNSC.request.operation 

The message is then routed to the correct Label node. The Label node forwards the message to a Compute node that builds an outbound request message in the SOAP domain by using the input message. The message is forwarded to the correct SOAPRequest node, which calls the provider flow. The return message is sent to an MQOutput node, which writes the XML data to the specified WebSphere MQ queue.

The messages

The Web services consumer message flow is driven by a WebSphere MQ message. A Test Client file is supplied to run the sample by using the following XML message. The first message stores an address, the second message looks up that address. The first element specifies the operation to call; the remainder of the message is used to build the SOAP message that is sent to the provider flow.

<request>
  <operation>saveAddress</operation>
  <Name>Dave</Name>
  <City>Carlisle</City>
  <Street>Welton</Street>
  <Province>Cumbria</Province>
  <PostalCode>NE2 3HP</PostalCode>
  <Area>1</Area>
  <Prefix>2</Prefix>
  <Local>3</Local>
</request> 

The second input message then looks up that address:

<request>
  <operation>findAddress</operation>
  <Name>Dave</Name>
</request>

SOAP messages are also provided to call the provider flow directly. These messages are equivalent to those that the consumer flow builds and sends from the two SOAPRequest nodes. The first SOAP message stores the address:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns3="http://addressbook.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <ns3:Person>
      <ns3:Name>Dave</ns3:Name>
      <ns3:Address>
        <ns3:City>Carlisle</ns3:City>
        <ns3:Street>Welton</ns3:Street>
        <ns3:Province>Cumbria</ns3:Province>
        <ns3:PostalCode>NE2 3HP</ns3:PostalCode>
        <ns3:PhoneNumber>
          <ns3:Area>1</ns3:Area>
          <ns3:Prefix>2</ns3:Prefix>
          <ns3:Local>3</ns3:Local>
        </ns3:PhoneNumber>
      </ns3:Address>
    </ns3:Person>
  </soapenv:Body>
</soapenv:Envelope>

The second input message looks up the address:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:tns="http://addressbook.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <tns:Name>Dave</tns:Name>
  </soapenv:Body>
</soapenv:Envelope>

Back to sample home