Download FAQ History |  | API Search Feedback

> ## SAAJ

> The SOAP with Attachments API for Java (SAAJ) provides a standard way to send XML documents over the Internet from the Java platform. It is based on the SOAP 1.1 and SOAP with Attachments specifications, which define a basic framework for exchanging XML messages.

> See Chapter 13 to see how to use the SAAJ API and run the SAAJ examples that are included with this tutorial.

> A SAAJ client is a standalone client. That is, it sends point-to-point messages directly to a Web service that is implemented for request-response messaging. Request-response messaging is synchronous, meaning that a request is sent and its response is received in the same operation. A request-response message is sent over a `SOAPConnection` object via the method `SOAPConnection.call`, which sends the message and blocks until it receives a response. A standalone client can operate only in a client role, that is, it can only send requests and receive their responses.

> A `SOAPMessage` object represents an XML document that is a SOAP message. A `SOAPMessage` object always has a required SOAP part, and it may also have one or more attachment parts. The SOAP part must always have a `SOAPEnvelope` object, which must in turn always contain a `SOAPBody` object. The `SOAPEnvelope` object may also contain a `SOAPHeader` object, to which one or more headers can be added.

> The `SOAPBody` object can hold XML fragments as the content of the message being sent. If you want to send content that is not in XML format or that is an entire XML document, your message will need to contain an attachment part in addition to the SOAP part. There is no limitation on the content in the attachment part, so it can include images or any other kind of content, including XML fragments and documents. Common types of attachment include sound, picture, and movie data: `.mp3`, `.jpg`, and `.mpg` files.

> ### Getting a Connection

> The first thing a SAAJ client needs to do is get a connection in the form of a `SOAPConnection` object. A `SOAPConnection` object is a point-to-point connection that goes directly from the sender to the recipient. The connection is created by a `SOAPConnectionFactory` object. A client obtains the default implementation for `SOAPConnectionFactory` by calling the following line of code.

>     SOAPConnectionFactory factory =
>         SOAPConnectionFactory.newInstance();

> The client can use `factory` to create a `SOAPConnection` object.

>     SOAPConnection connection = factory.createConnection();

> ### Creating a Message

> Messages, like connections, are created by a factory. To obtain a `MessageFactory` object, you get an instance of the default implementation for the `MessageFactory` class. This instance can then be used to create a `SOAPMessage` object.

>     MessageFactory messageFactory = MessageFactory.newInstance();
>     SOAPMessage message = messageFactory.createMessage();

> All of the `SOAPMessage` objects that `messageFactory` creates, including `message` in the previous line of code, will be SOAP messages. This means that they will have no pre-defined headers.

> The new `SOAPMessage` object `message` automatically contains the required elements `SOAPPart`, `SOAPEnvelope`, and `SOAPBody`, plus the optional element `SOAPHeader` (which is included for convenience). The `SOAPHeader` and `SOAPBody` objects are initially empty, and the following sections will illustrate some of the typical ways to add content.

> ### Populating a Message

> Content can be added to the `SOAPPart` object, to one or more `AttachmentPart` objects, or to both parts of a message.

> #### Populating the SOAP Part of a Message

> As stated earlier, all messages have a `SOAPPart` object, which has a `SOAPEnvelope` object containing a `SOAPHeader` object and a `SOAPBody` object. One way to add content to the SOAP part of a message is to create a `SOAPHeaderElement` object or a `SOAPBodyElement` object and add an XML fragment that you build with the method `SOAPElement.addTextNode`. The first three lines of the following code fragment access the `SOAPBody` object `body`, which is used to create a new `SOAPBodyElement` object and add it to `body`. The argument passed to the `createName` method is a `Name` object identifying the `SOAPBodyElement` being added. The last line adds the XML string passed to the method `addTextNode`.

>     SOAPPart soapPart = message.getSOAPPart();
>     SOAPEnvelope envelope = soapPart.getSOAPEnvelope();
>     SOAPBody body = envelope.getSOAPBody();
>     SOAPBodyElement bodyElement = body.addBodyElement(
>         envelope.createName("text", "hotitems",
>         "http://hotitems.com/products/gizmo");
>     bodyElement.addTextNode("some-xml-text");

> Another way is to add content to the `SOAPPart` object by passing it a `j` `avax.xml.transform.Source` object, which may be a `SAXSource`, `DOMSource`, or `StreamSource` object. The `Source` object contains content for the SOAP part of the message and also the information needed for it to act as source input. A `StreamSource` object will contain the content as an XML document; the `SAXSource` or `DOMSource` object will contain content and instructions for transforming it into an XML document.

> The following code fragments illustrates adding content as a `DOMSource` object. The first step is to get the `SOAPPart` object from the `SOAPMessage` object. Next the code uses methods from the JAXP API to build the XML document to be added. It uses a `DocumentBuilderFactory` object to get a `DocumentBuilder` object. Then it parses the given file to produce the document that will be used to initialize a new `DOMSource` object. Finally, the code passes the `DOMSource` object `domSource` to the method `SOAPPart.setContent`.

>     SOAPPart soapPart = message.getSOAPPart();

>     DocumentBuilderFactory dbFactory=
>         DocumentBuilderFactory.newInstance();
>     DocumentBuilder builder = dbFactory.newDocumentBuilder();
>     Document document = builder.parse("file:///foo.bar/soap.xml");
>     DOMSource domSource = new DOMSource(document);

>     soapPart.setContent(domSource);

> This code would work equally well with a `SAXSource` or a `StreamSource` object.

> You use the `setContent` method when you want to send an existing SOAP message. If you have an XML document that you want to send as the content of a SOAP message, you use the `addDocument` method on the body of the message:

>     SOAPBodyElement docElement = body.addDocument(document);

> This allows you to keep your application data in a document that is separate from the SOAP envelope unless and until it is time to send that data as a message.

> #### Populating the Attachment Part of a Message

> A `Message` object may have no attachment parts, but if it is to contain anything that is not in XML format, that content must be contained in an attachment part. There may be any number of attachment parts, and they may contain anything from plain text to image files. In the following code fragment, the content is an image in a JPEG file, whose URL is used to initialize the `javax.activation.DataHandler` object `handler`. The `Message` object `message` creates the `AttachmentPart` object `attachPart`, which is initialized with the data handler containing the URL for the image. Finally, the message adds `attachPart` to itself.

>     URL url = new URL("http://foo.bar/img.jpg");
>     DataHandler handler = new DataHandler(url);
>     AttachmentPart attachPart =
>         message.createAttachmentPart(handler);
>     message.addAttachmentPart(attachPart);

> A `SOAPMessage` object can also give content to an `AttachmentPart` object by passing an `Object` and its content type to the method `createAttachmentPart`.

>     AttachmentPart attachPart =
>         message.createAttachmentPart("content-string",
>             "text/plain");
>     message.addAttachmentPart(attachPart);

> ### Sending a Message

> Once you have populated a `SOAPMessage` object, you are ready to send it. A client uses the `SOAPConnection` method `call` to send a message. This method sends the message and then blocks until it gets back a response. The arguments to the method `call` are the message being sent and a `URL` object that contains the URL specifying the endpoint of the receiver.

>     SOAPMessage response = soapConnection.call(message, endpoint);

Download FAQ History |  | API Search Feedback

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.