使用SAAJ处理SOAP

The foundation of Web services lies in the sending and receiving of messages in a standard format so that all systems can understand them. Typically, that format is SOAP. A SOAP message can be generated and sent manually, but the SOAP with Attachments API for Java (SAAJ) -- an offshoot of the Java API for XML Messaging (JAXM) -- automates many of the required steps, such as creating connections or creating and sending the actual messages. This tip chronicles the creation and sending of a synchronous SOAP message.

The process involves five steps:

  1. Creating a SOAP connection
  2. Creating a SOAP message
  3. Populating the message
  4. Sending the message
  5. Retrieving the reply

SAAJ is available as part of the Java Web Services Developer Pack 1.2 (see Resources). This package also includes a copy of the Tomcat Web server (so you can host your own service) and sample applications.


The structure of a SOAP message

I'll start by showing you the structure of the message itself. A basic SOAP message consists of an envelope with two main parts: the header and the body. The application determines how these parts are used, but the overall message must follow a specific XML structure, such as:


Listing 1. A sample SOAP message
				<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
            xmlns:xsd="http://www.w3.org/1999/XMLSchema">
            <SOAP-ENV:Header />
            <SOAP-ENV:Body> 
            <ns1:getPrice xmlns:ns1="urn:xmethods-BNPriceCheck"
            SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
            <isbn xsi:type="xsd:string">0672324229</isbn>
            </ns1:getPrice>
                </SOAP-ENV:Body>
            </SOAP-ENV:Envelope> 
            

Here, the header is empty and the body contains the payload, or the message to be delivered. In this case, it's a message requesting the price of a book.

Notice the structure of the message. The Envelope contains the Header and Body elements, and all three are part of the http://schemas.xmlsoap.org/soap/envelope/ namespace. The application sends the message using a SOAPConnection.




Creating the connection and the message

The first step is to create the overall class and the connection:


Listing 2. Create the connection
import javax.xml.soap.SOAPConnectionFactory;
            import javax.xml.soap.SOAPConnection;
            public class SOAPTip {
            public static void main(String args[]) {
            try {
                     //First create the connection
            SOAPConnectionFactory soapConnFactory =
            SOAPConnectionFactory.newInstance();
            SOAPConnection connection =
            soapConnFactory.createConnection();
            //Close the connection
            connection.close();
            } catch(Exception e) {
            System.out.println(e.getMessage());
            }
            }
            }

The application can send SOAP messages directly using a SOAPConnection, which is now part of the SAAJ package, or indirectly using a messaging provider, which remains in the JAXM package. In this case, the application creates the SOAPConnection object using a factory.

A factory also creates the message itself:


Listing 3. Creating the message object
import javax.xml.soap.SOAPConnectionFactory;
            import javax.xml.soap.SOAPConnection;
            import javax.xml.soap.MessageFactory;
            import javax.xml.soap.SOAPMessage;
            import javax.xml.soap.SOAPPart;
            import javax.xml.soap.SOAPEnvelope;
            import javax.xml.soap.SOAPBody;
            public class SOAPTip {
            public static void main(String args[]) {
            try {
            //First create the connection
            SOAPConnectionFactory soapConnFactory =
            SOAPConnectionFactory.newInstance();
            SOAPConnection connection =
            soapConnFactory.createConnection();
                    //Next, create the actual message
            MessageFactory messageFactory = MessageFactory.newInstance();
            SOAPMessage message = messageFactory.createMessage();
            //Create objects for the message parts
            SOAPPart soapPart =     message.getSOAPPart();
            SOAPEnvelope envelope = soapPart.getEnvelope();
            SOAPBody body =         envelope.getBody();
            //Close the connection
            connection.close();
            } catch(Exception e) {
            System.out.println(e.getMessage());
            }
            }
            }

Version differences
If you've using another version of SAAJ, such as the Axis 1.2 beta SAAJ library, you may need to use addBodyElement instead of addChildElement.

First, you create the message itself by using the MessageFactory. This message already contains empty versions of the basic parts, such as the envelope and header. The SOAPPart contains the envelope, and the envelope contains the body. Create references to the needed objects, such as the SOAPBody.

Next, populate the SOAPBody:


Listing 4. Populating the body
...
            import javax.xml.soap.SOAPBody;
            import javax.xml.soap.SOAPElement;
            public class SOAPTip {
            public static void main(String args[]) {
            try {
            ...
            //Create objects for the message parts
            SOAPPart soapPart =     message.getSOAPPart();
            SOAPEnvelope envelope = soapPart.getEnvelope();
            SOAPBody body =         envelope.getBody();
                    //Populate the body
            //Create the main element and namespace
            SOAPElement bodyElement =
            body.addChildElement(envelope.createName("getPrice" ,
            "ns1",
            "urn:xmethods-BNPriceCheck"));
            //Add content
            bodyElement.addChildElement("isbn").addTextNode("0672324229");
            //Save the message
            message.saveChanges();
            //Check the input
            System.out.println("\nREQUEST:\n");
            message.writeTo(System.out);
            System.out.println();
            //Close the connection
            connection.close();
            } catch(Exception e) {
            System.out.println(e.getMessage());
            }
            }
            }

The body of the SOAP message is just like any other XML element in that you can add a child element, such as getPrice. You can then add the isbn element and its text node just as you might with a typical DOM element.

With SAAJ you also have the opportunity to directly create the SOAPPart of the message using an external file. For example, the file prepped.msg contains the XML structure in the first listing, and can be called in lieu of building the document manually:


Listing 5. Creating the message from an external file
...
            import javax.xml.soap.SOAPElement;
            import java.io.FileInputStream;
            import javax.xml.transform.stream.StreamSource;
            public class SOAPTip {
            public static void main(String args[]) {
            ...
            //Create objects for the message parts
            SOAPPart soapPart =     message.getSOAPPart();
            SOAPEnvelope envelope = soapPart.getEnvelope();
            SOAPBody body =         envelope.getBody();
            //Populate the Message
            StreamSource preppedMsgSrc = new StreamSource(
            new FileInputStream("prepped.msg"));
            soapPart.setContent(preppedMsgSrc);
            //Save the message
            message.saveChanges();
            ...
            }
            }

The StreamSource class is typically used as part of an XSL Transformation, but here you can use it simply to obtain the FileInputStream. The result is a SOAP message that's ready to send.




Sending the message

With a synchronous message, sending the SOAP message and receiving a reply take place in a single step:


Listing 6. Sending the message
...
            public class SOAPTip {
            public static void main(String args[]) {
            ...
            //Check the input
            System.out.println("\nREQUEST:\n");
            message.writeTo(System.out);
            System.out.println();
                    //Send the message and get a reply
            //Set the destination
            String destination =
            "http://services.xmethods.net:80/soap/servlet/rpcrouter";
            //Send the message
            SOAPMessage reply = connection.call(message, destination);
            //Close the connection
            connection.close();
            ...
            }
            }

The actual message is sent using the call() method, which takes the message itself and a destination as arguments and returns a second SOAPMessage as a reply. In earlier versions of JAXM, the destination had to be an Endpoint object or a URLEndpoint, but now it simply has to be an object. This example uses the "Book price checker" Web service hosted by XMethods, which returns the price of the book whose ISBN is listed in the request.

The call() method blocks until it receives the returned SOAPMessage.




The response

The returned SOAPMessage, reply, is a SOAP message in the same form as the message sent, and as such can be manipulated just like any other XML message. SOAP allows you to transform the reply directly using XSLT:


Listing 7. Reading the response
...
            import javax.xml.transform.TransformerFactory;
            import javax.xml.transform.Transformer;
            import javax.xml.transform.Source;
            import javax.xml.transform.stream.StreamResult;
            public class SOAPTip {
            public static void main(String args[]) {
            try {
            ...
            //Send the message
            SOAPMessage reply = connection.call(message, destination);
                    //Check the output
            System.out.println("\nRESPONSE:\n");
            //Create the transformer
            TransformerFactory transformerFactory =
            TransformerFactory.newInstance();
            Transformer transformer =
            transformerFactory.newTransformer();
            //Extract the content of the reply
            Source sourceContent = reply.getSOAPPart().getContent();
            //Set the output for the transformation
            StreamResult result = new StreamResult(System.out);
            transformer.transform(sourceContent, result);
            System.out.println();
            //Close the connection
            connection.close();
            ...
            }
            }

Create the Transformer object as you would in any XSLT application. In this case, you just want to output the content, so there's no stylesheet. Here, the content itself is the entire SOAP part of the message (as opposed to the SOAP message itself, which might include attachments). You could also extract the envelope and body before processing. The result in this case is simply System.out, but can be any choice normally available to a transformation. Transform as usual.

posted on 2007-12-17 17:27 刘铮 阅读(388) 评论(0)  编辑  收藏 所属分类: WebService


只有注册用户登录后才能发表评论。


网站导航:
 
<2024年11月>
272829303112
3456789
10111213141516
17181920212223
24252627282930
1234567

导航

统计

留言簿(1)

文章分类(141)

文章档案(147)

搜索

最新评论