Sun Java System Application Server Enterprise Edition 8.2 Developer's Guide

Delivering SOAP Messages Using the JMS API

Web service clients use the Simple Object Access Protocol (SOAP) to communicate with web services. SOAP uses a combination of XML-based data structuring and Hyper Text Transfer Protocol (HTTP) to define a standardized way of invoking methods in objects distributed in diverse operating environments across the Internet.

For more information about SOAP, see the Apache SOAP web site at http://xml.apache.org/soap/index.html.

You can take advantage of the JMS provider’s reliable messaging when delivering SOAP messages. You can convert a SOAP message into a JMS message, send the JMS message, then convert the JMS message back into a SOAP message. The following sections explain how to do these conversions:

ProcedureTo send SOAP messages using the JMS API

  1. Import the MessageTransformer library.

    import com.sun.messaging.xml.MessageTransformer;

    This is the utility whose methods you use to convert SOAP messages to JMS messages and the reverse. You can then send a JMS message containing a SOAP payload as if it were a normal JMS message.

  2. Initialize the TopicConnectionFactory, TopicConnection, TopicSession, and publisher.

    tcf = new TopicConnectionFactory();
    tc = tcf.createTopicConnection();
    session = tc.createTopicSession(false,Session.AUTO_ACKNOWLEDGE);
    topic = session.createTopic(topicName);
    publisher = session.createPublisher(topic);
  3. Construct a SOAP message using the SOAP with Attachments API for Java (SAAJ).

    *construct a default soap MessageFactory */
    MessageFactory mf = MessageFactory.newInstance();
    /* Create a SOAP message object.*/
    SOAPMessage soapMessage = mf.createMessage();
    /** Get SOAP part.*/
    SOAPPart soapPart = soapMessage.getSOAPPart();
    /* Get SOAP envelope. */
    SOAPEnvelope soapEnvelope = soapPart.getEnvelope();
    /* Get SOAP body.*/
    SOAPBody soapBody = soapEnvelope.getBody();
    /* Create a name object. with name space */
    /* http://www.sun.com/imq. */
    Name name = soapEnvelope.createName("HelloWorld", "hw",
     "http://www.sun.com/imq");
    * Add child element with the above name. */
    SOAPElement element = soapBody.addChildElement(name)
    /* Add another child element.*/
    element.addTextNode( "Welcome to Sun Java System Web Services." );
    /* Create an atachment with activation API.*/
    URL url = new URL ("http://java.sun.com/webservices/");
    DataHandler dh = new DataHandler (url);
    AttachmentPart ap = soapMessage.createAttachmentPart(dh);
    /*set content type/ID. */
    ap.setContentType("text/html");
    ap.setContentId("cid-001");
    /**  add the attachment to the SOAP message.*/
    soapMessage.addAttachmentPart(ap);
    soapMessage.saveChanges();
  4. Convert the SOAP message to a JMS message by calling the MessageTransformer.SOAPMessageintoJMSMessage() method.

    Message m = MessageTransformer.SOAPMessageIntoJMSMessage (soapMessage, 
    session );
  5. Publish the JMS message.

    publisher.publish(m);
  6. Close the JMS connection.

    tc.close();

ProcedureTo receive SOAP messages using the JMS API

  1. Import the MessageTransformer library.

    import com.sun.messaging.xml.MessageTransformer;

    This is the utility whose methods you use to convert SOAP messages to JMS messages and the reverse. The JMS message containing the SOAP payload is received as if it were a normal JMS message.

  2. Initialize the TopicConnectionFactory, TopicConnection, TopicSession, TopicSubscriber, and Topic.

    messageFactory = MessageFactory.newInstance();
    tcf = new com.sun.messaging.TopicConnectionFactory();
    tc = tcf.createTopicConnection();
    session = tc.createTopicSession(false, Session.AUTO_ACKNOWLEDGE);
    topic = session.createTopic(topicName);
    subscriber = session.createSubscriber(topic);
    subscriber.setMessageListener(this);
    tc.start();
  3. Use the OnMessage method to receive the message. Use the SOAPMessageFromJMSMessage method to convert the JMS message to a SOAP message.

    public void onMessage (Message message) {
    SOAPMessage soapMessage =
     MessageTransformer.SOAPMessageFromJMSMessage( message,
     messageFactory ); }
  4. Retrieve the content of the SOAP message.