5 Working with SOAP Messages

The Transport Layer

Underlying any messaging system is the transport or wire protocol that governs the serialization of the message as it is sent across a wire and the interpretation of the message bits when it gets to the other side. Although SOAP messages can be sent using any number of protocols, the SOAP specification defines only the binding with HTTP. SOAP uses the HTTP request/response message model. It provides SOAP request parameters in an HTTP request and SOAP response parameters in an HTTP response. The HTTP binding has the advantage of allowing SOAP messages to go through firewalls.

The SOAP Layer

Above the transport layer is the SOAP layer. This layer, which is defined in the SOAP Specification, specifies the XML scheme used to identify the message parts: envelope, header, body, and attachments. All SOAP message parts and contents, except for the attachments, are written in XML. The following sample SOAP message shows how XML tags are used to define a SOAP message:

<SOAP-ENV:Envelope
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   SOAP-ENV:encodingStyle=
           "http://schemas.xmlsoap.org/soap/encoding/">
      <SOAP-ENV:Body>
          <m:GetLastTradePrice xmlns:m="Some-URI">
              <symbol>DIS</symbol>
          </m:GetLastTradePrice>
      </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


            

The wire transport and SOAP layers are actually sufficient to do SOAP messaging. You could create an XML document that defines the message you want to send, and you could write HTTP commands to send the message from one side and to receive it on the other. In this case, the client is limited to sending synchronous messages to a specified URL. Unfortunately, the scope and reliability of this kind of messaging is severely restricted. To overcome these limitations, the provider and profile layers are added to SOAP messaging.

The Language Implementation Layer

A language implementation allows you to create XML messages that conform to SOAP, using API calls. For example, the SAAJ implementation of SOAP, allows a Java client to construct a SOAP message and all its parts as Java objects. The client would also use SAAJ to create a connection and use it to send the message. Likewise, a Web service written in Java could use the same implementation (SAAJ), or any other language implementation, to receive the message, to disassemble it, and to acknowledge its receipt.

The Profiles Layer

In addition to a language implementation, a SOAP implementation can offer services that relate to message delivery. These could include reliability, persistence, security, and administrative control, and are typically delivered by a SOAP messaging provider. These services will be provided for SOAP messaging by Message Queue in future releases.

Interoperability

Because SOAP providers must all construct and deconstruct messages as defined by the SOAP specification, clients and services using SOAP are interoperable. That is, as shown in Figure 5-2, the client and the service doing SOAP messaging do not need to be written in the same language nor do they need to use the same SOAP provider. It is only the packaging of the message that must be standard.

Figure 5-2 SOAP Interoperability

Description of "Figure 5-2 SOAP Interoperability"

In order for a SAAJ client or service to interoperate with a service or client using a different implementation, the parties must agree on two things:

• They must use the same transport bindings--that is, the same wire protocol.

• They must use the same profile in constructing the SOAP message being sent.

Inherited Methods

The elements of a SOAP message form a tree. Each node in that tree implements the Node interface and, starting at the envelope level, each node implements the SOAPElement interface as well. The resulting shared methods are described in Table 5-1.

SOAPElement

addAttribute(Name, String)

                           

addChildElement(Name)
addChildElement(String, String)
addChildElement
    (String, String, String)

addNameSpaceDeclaration 
   (String, String)   

addTextnode(String)

getAllAttributes()

getAttributeValue(Name)

getChildElements()

getChildElements(Name)

getElementName()
 

getEncodingStyle() 

getNameSpacePrefixes()

getNamespaceURI(String)

removeAttribute(Name)

removeNamespaceDeclaration
(String)

setEncodingStyle(String)

Node
                           

detachNode()    

getParentElement()

getValue 

recycleNode() 

setParentElement(SOAPElement)

Namespaces

An XML namespace is a means of qualifying element and attribute names to disambiguate them from other names in the same document. This section provides a brief description of XML namespaces and how they are used in SOAP. For complete information, see http://www.w3.org/TR/REC-xml-names/

An explicit XML namespace declaration takes the following form:

<prefix:myElement
xmlns:prefix ="URI">

The declaration defines prefix as an alias for the specified URI. In the element myElement, you can use prefix with any element or attribute to specify that the element or attribute name belongs to the namespace specified by the URI.

The following is an example of a namespace declaration:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"

This declaration defines SOAP_ENV as an alias for the namespace:

http://schemas.xmlsoap.org/soap/envelope/

After defining the alias, you can use it as a prefix to any attribute or element in the Envelope element. In Example 5-1, the elements <Envelope> and <Body> and the attribute encodingStyle all belong to the SOAP namespace specified by the http://schemas.sxmlsoap.org/soap/envelope/URI .

<SOAP-ENV:Envelope
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   SOAP-ENV:encodingStyle=
                     "http://schemas.xmlsoap.org/soap/encoding/">
   <SOAP-ENV:Header>
        <HeaderA
 xmlns="HeaderURI"
 SOAP-ENV:mustUnderstand="0">
     
      The text of the header
     </HeaderA>
 </SOAP-ENV:Header>
   <SOAP-ENV:Body>
.
.
.
   </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

Note that the URI that defines the namespace does not have to point to an actual location; its purpose is to disambiguate attribute and element names.

Name bodyName = MyEnvelope.createName("TradePrice",
                                 "GetLTP","http://foo.eztrade.com");

<GetLTP:TradePrice xmlns:GetLTP= "http://foo.eztrade.com">

SoapBody body = envelope.getBody();//get body from envelope
Name bodyName = envelope.createName("TradePrice", "GetLTP",
                                        "http://foo.eztrade.com");
SOAPBodyElement gltp = body.addBodyElement(bodyName);

Endpoint

An endpoint identifies the final destination of a message. An endpoint is defined either by the Endpoint class (if you use a provider) or by the URLEndpoint class (if you don't use a provider).)

myEndpoint = new URLEndpoint("http://somehost/myServlet");

Message Factory

You use a Message Factory to create a SOAP message.

To instantiate a message factory directly, use a statement like the following:

MessageFactory mf = MessageFactory.newInstance();

Connection

To send a SOAP message using SAAJ, you must obtain a SOAPConnection . You can also transport a SOAP message using Message Queue; for more information, see Integrating SOAP and Message Queue.

SOAP Connection

A SOAPConnection allows you to send messages directly to a remote party. You can obtain a SOAPConnection object simply by calling the static method SOAPConnectionFactory.newInstance(). Neither reliability nor security are guaranteed over this type of connection.

To Create and Add an Attachment

1. Create a URL object and initialize it to contain the location of the file that you want to attach to the SOAP message.

   URL url = new URL("http://wombats.com/img.jpg");
   

2. Create a data handler and initialize it with a default handler, passing the URL as the location of the data source for the handler.

   DataHandler dh = new DataHandler(url);
   

3. Create an attachment part that is initialized with the data handler containing the URL for the image.

   AttachmentPart ap1 = message.createAttachmentPart(dh);
   

4. Add the attachment part to the SOAP message.

   myMessage.addAttachmentPart(ap1);
   

   After creating the attachment and adding it to the message, you can send the message in the usual way.

   If you are using JMS to send the message, you can use the SOAPMessageIntoJMSMessage conversion utility to convert a SOAP message that has an attachment into a JMS message that you can send to a JMS queue or topic using Message Queue.

To Write a SOAP Client for Point-to-Point Messaging

1. Get an instance of a SOAPConnectionFactory:

   SOAPConnectionFactory myFct = SOAPConnectionFactory.newInstance();
   

2. Get a SOAP connection from the SOAPConnectionFactory object:

   SOAPConnection myCon = myFct.createConnection();
   

   The myCon object that is returned will be used to send the message.

3. Get a MessageFactory object to create a message:

   MessageFactory myMsgFct = MessageFactory.newInstance();
   

4. Use the message factory to create a message:

   SOAPMessage message = myMsgFct.createMessage();
   

   The message that is created has all the parts that are shown in Figure 5-7.

   Figure 5-7 SOAP Message Parts

   
   Description of "Figure 5-7 SOAP Message Parts"
   
   

   At this point, the message has no content. To add content to the message, you need to create a SOAP body element, define a name and content for it, and then add it to the SOAP body.

   Remember that to access any part of the message, you need to traverse the tree, calling a get method on the parent element to obtain the child. For example, to reach the SOAP body, you start by getting the SOAP part and SOAP envelope:

   SOAPPart mySPart = message.getSOAPPart();
   SOAPEnvelope myEnvp = mySPart.getEnvelope();
   

5. Now, you can get the body element from the myEnvp object:

   SOAPBody body = myEnvp.getBody();
   

   The children that you will add to the body element define the content of the message. (You can add content to the SOAP header in the same way.)

6. When you add an element to a SOAP body (or header), you must first create a name for it by calling the envelope.createName method. This method returns a Name object, which you must then pass as a parameter to the method that creates the body element (or the header element).

   Name bodyName = envelope.createName("GetLastTradePrice", "m",
                                          "http://eztrade.com")
   SOAPBodyElement gltp = body.addBodyElement(bodyName);
   

7. Now create another body element to add to the gltp element:

   Name myContent = envelope.createName("symbol");
   SOAPElement mySymbol = gltp.addChildElement(myContent);
   

8. And now you can define data for the body element mySymbol:

   mySymbol.addTextNode("SUNW");
   

   The resulting SOAP message object is equivalent to this XML scheme:

   <SOAP-ENV: Envelope
       xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/">
           <SOAP-ENV:Body>
               <m:GetLastTradePrice xmlns:m="http://eztrade.com">
                   <symbol>SUNW</symbol>
               </m:GetLastTradePrice>
       </SOAP-ENV:Body>
   </SOAP-ENV: Envelope>
   

9. Every time you send a message or write to it, the message is automatically saved. However if you change a message you have received or one that you have already sent, this would be the point when you would need to update the message by saving all your changes. For example:

   message.saveChanges();
   

10. Before you send the message, you must create a URLEndpoint object with the URL of the endpoint to which the message is to be sent. (If you use a profile that adds addressing information to the message header, you do not need to do this.)

    URLEndpoint endPt = new URLEndpoint("http://eztrade.com//quotes");
    

11. Now, you can send the message:

    SOAPMessage reply = myCon.call(message, endPt);
    

    The reply message (reply) is received on the same connection.

12. Finally, you need to close the SOAPConnection object when it is no longer needed:

    myCon.close();
    

Disassembling Messages

The onMessage method needs to disassemble the SOAP message that is passed to it by the servlet and process its contents in an appropriate manner. If there are problems in the processing of the message, the service needs to create a SOAP fault object and send it back to the client as described in Handling SOAP Faults.

Processing the SOAP message may involve working with the headers as well as locating the body elements and dealing with their contents. The following code sample shows how you might disassemble a SOAP message in the body of your onMessage method. Basically, you need to use a Document Object Model (DOM) API to parse through the SOAP message.

See http://xml.coverpages.org/dom.html for more information about the DOM API.

{http://xml.coverpages.org/dom.html
    SOAPEnvelope env = reply.getSOAPPart().getEnvelope();
    SOAPBody sb = env.getBody();
    // create Name object for XElement that we are searching for
    Name ElName = env.createName("XElement");

    //Get child elements with the name XElement
    Iterator it = sb.getChildElements(ElName);

    //Get the first matched child element.
    //We know there is only one.
    SOAPBodyElement sbe = (SOAPBodyElement) it.next();

    //Get the value for XElement
    MyValue =   sbe.getValue();
}               

Handling Attachments

A SOAP message may have attachments. For sample code that shows you how to create and add an attachment, see Code Samples. For sample code that shows you how to receive and process an attachment, see Code Samples.

In handling attachments, you will need to use the Java Activation Framework API. See http://java.sun.com/products/javabeans/glasgow/jaf.html for more information.

Replying to Messages

In replying to messages, you are simply taking on the client role, now from the server side.

Handling SOAP Faults

Server-side code must use a SOAP fault object to handle errors that occur on the server side when unmarshalling the request, processing the message, or marshalling the response. The SOAPFault interface extends the SOAPBodyElement interface.

SOAP messages have a specific element and format for error reporting on the server side: a SOAP message body can include a SOAP fault element to report errors that happen during the processing of a request. Created on the server side and sent from the server back to the client, the SOAP message containing the SOAPFault object reports any unexpected behavior to the originator of the message.

Within a SOAP message object, the SOAP fault object is a child of the SOAP body, as shown in the figure below. Detail and detail entry objects are only needed if one needs to report that the body of the received message was malformed or contained inappropriate data. In such a case, the detail entry object is used to describe the malformed data.

Figure 5-8 SOAP Fault Element

Description of "Figure 5-8 SOAP Fault Element"

The SOAP Fault element defines the following four sub-elements:

• faultcode

  A code (qualified name) that identifies the error. The code is intended for use by software to provide an algorithmic mechanism for identifying the fault. Predefined fault codes are listed in Table 5-3. This element is required.

• faultstring

  A string that describes the fault identified by the fault code. This element is intended to provide an explanation of the error that is understandable to a human. This element is required.

• faultactor

  A URI specifying the source of the fault: the actor that caused the fault along the message path. This element is not required if the message is sent to its final destination without going through any intermediaries. If a fault occurs at an intermediary, then that fault must include a faultactor element.

• detail

  This element carries specific information related to the Body element. It must be present if the contents of the Body element could not be successfully processed. Thus, if this element is missing, the client should infer that the body element was processed. While this element is not required for any error except a malformed payload, you can use it in other cases to supply additional information to the client.

VersionMismatch 

MustUnderstand 

Client

Server 

SOAPFault fault;
reply = factory.createMessage();
envp = reply.getSOAPPart().getEnvelope(true);
someBody = envp.getBody();
fault = someBody.addFault():
fault.setFaultCode("Server");
fault.setFaultString("Some Server Error");
fault.setFaultActor(http://xxx.me.com/list/endpoint.esp/)
reply.saveChanges();
               

SOAPFault fault = someBody.addFault();
fault.setFaultCode("Server");
fault.setFaultActor("http://foo.com/uri");
fault.setFaultString ("Unkown error");
Detail myDetail = fault.addDetail();
detail.addDetailEntry(envelope.createName("125detail", "m",
        "Someuri")).addTextNode("the message cannot contain
         the string //");
reply.saveChanges();  

To Transform the SOAP Message into a JMS Message and Send the JMS Message

1. Instantiate a ConnectionFactory object and set its attribute values, for example:

   QueueConnectionFactory myQConnFact =
           new com.sun.messaging.QueueConnectionFactory();
   

2. Use the ConnectionFactory object to create a Connection object.

   QueueConnection myQConn =
            myQConnFact.createQueueConnection();
   

3. Use the Connection object to create a Session object.

   QueueSession myQSess = myQConn.createQueueSession(false,
            Session.AUTO_ACKNOWLEDGE);
   

4. Instantiate a Message Queue Destination administered object corresponding to a physical destination in the Message Queue message service. In this example, the administered object is mySOAPQueue and the physical destination to which it refers is myPSOAPQ.

   Queue mySOAPQueue = new com.sun.messaging.Queue("myPSOAPQ");
   

5. Use the MessageTransformer utility, as shown, to transform the SOAP message into a JMS message. For example, given a SOAP message named MySOAPMsg,

   Message MyJMS = MessageTransformer.SOAPMessageIntoJMSMessage
                                        (MySOAPMsg, MyQSess);
   

6. Create a QueueSender message producer.

   This message producer, associated with mySOAPQueue, is used to send messages to the queue destination named myPSOAPQ.

   QueueSender myQueueSender = myQSess.createSender(mySOAPQueue);
   

7. Send a message to the queue.

   myQueueSender.send(myJMS);
   

To Receive the JMS Message, Transform it into a SOAP Message, and Process It

1. Instantiate a ConnectionFactory object and set its attribute values.

   QueueConnectioFactory myQConnFact = new
            com.sun.messaging.QueueConnectionFactory();
   

2. Use the ConnectionFactory object to create a Connection object.

   QueueConnection myQConn = myQConnFact.createQueueConnection();
   

3. Use the Connection object to create one or more Session objects.

   QueueSession myRQSess = myQConn.createQueueSession(false,
            session.AUTO_ACKNOWLEDGE);
   

4. Instantiate a Destination object and set its name attribute.

   Queue myRQueue = new com.sun.messaging.Queue("mySOAPQ");
   

5. Use a Session object and a Destination object to create any needed MessageConsumer objects.

   QueueReceiver myQueueReceiver =
        myRQSess.createReceiver(myRQueue);
   

6. If needed, instantiate a MessageListener object and register it with a MessageConsumer object.

7. Start the QueueConnection you created in Example 1: Deferring SOAP Processing. Messages for consumption by a client can only be delivered over a connection that has been started.

   myQConn.start();
   

8. Receive a message from the queue.

   The code below is an example of a synchronous consumption of messages:

   Message myJMS = myQueueReceiver.receive();
   

9. Use the Message Transformer to convert the JMS message back to a SOAP message.

   SOAPMessage MySoap =
            MessageTransformer.SOAPMessageFromJMSMessage
                (myJMS, MyMsgFactory);
   

   If you specify null for the MessageFactory argument, the default Message Factory is used to construct the SOAP Message.

10. Disassemble the SOAP message in preparation for further processing. See The SOAP Message Object for information.