Create a SOAP message that contains an attachment.

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.

The process of creation and sending SOAP message includes following steps:

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.

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.

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();
					

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. Content can be added to the SOAPPart object, to one or more AttachmentPart objects, or to both parts of a message.

package javax.xml.soap;

public abstract class SOAPPart implements org.w3c.dom.Document {
    public abstract SOAPEnvelope getEnvelope() throws SOAPException;				
    ...
}    
					

As stated earlier, all messages have a SOAPPart object, which has a SOAPEnvelope object containing a SOAPHeader object and a SOAPBody object.

package javax.xml.soap;

public interface SOAPEnvelope extends SOAPElement {
    public abstract Name createName(String localName, String prefix, String uri)
        throws SOAPException;
    public abstract Name createName(String localName) throws SOAPException;
    public abstract SOAPHeader getHeader() throws SOAPException;
    public abstract SOAPHeader addHeader() throws SOAPException;
    public abstract SOAPBody getBody() throws SOAPException;
    public abstract SOAPBody addBody() throws SOAPException;
}					
					

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.getEnvelope();
SOAPBody body = envelope.getBody();
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 javax.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.

A SOAPMessage 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); 					
					

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);
					

The following example shows a SOAP 1.1 message with an attached facsimile image of the signed claim form (claim.tiff), also it illustrates the use of the cid reference in the body of the SOAP 1.1 message:


MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml;
        start="<claim.xml@claiming-it.com>"
Content-Description: This is the optional message description.

--MIME_boundary
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <claim.xml@claiming-it.com>

<?xml version='1.0' ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    ..
    <theSignedForm href="cid:claim.tiff@claiming-it.com"/>
    ..
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

--MIME_boundary
Content-Type: image/tiff
Content-Transfer-Encoding: binary
Content-ID: <claim.tiff@claiming-it.com>

d3d3Lm1hcmNoYWwuY29taesgfSEVFES45345sdvgfszd==
--MIME_boundary--

					
NOTE: In this example the "Content-Type" header line has been continued across two lines so the example prints easily. SOAP message senders should send headers on a single long line.

NOTE: Associate the attachment to theSignedForm element by adding an href attribute. The attachment is referred to through a cid (Content-ID) URL:

					
...
<myElement href="cid:xxxx" />
...
--MIME_boundary
Content-Type: image/tiff
Content-Transfer-Encoding: binary
Content-ID: <xxxx>
...
					
					
NOTE: Unlike SOAP 1.1 XML references, do not use '#' (pound sign) in href attribute value when you refer to attachment, also when you refer to attachment you must prepend unique identifier with prefix 'cid:'.

The following listing illustrates the creation of the SOAP request. The request asks a server to resize an image. The procedure is as follows:

  1. Create SOAP connection and SOAP message objects through factories.

  2. Retrieve the message body from the message object (intermediary steps: retrieve the SOAP part and envelope).

  3. Create a new XML element to represent the request.

  4. Create the attachment and initialize it with a DataHandler object.

  5. Create more elements to represent the two parameters (source and percent).

  6. Associate the attachment to the first parameter by adding an href attribute. The attachment is referred to through a cid (Content-ID) URI.

  7. Set the value of the second parameter directly as text and call the service.

The service replies with the resized image, again as an attachment. To retrieve it, you can test for a SOAP fault (which indicates an error). If there are no faults, retrieve the attachment as a file and process it. Using SAAJ API:

// Using SAAJ
					
public File resize(String endPoint,File file) {
   SOAPConnection connection = SOAPConnectionFactory.newInstance().createConnection();
   SOAPMessage message = MessageFactory.newInstance().createMessage();
   SOAPPart part = message.getSOAPPart();
   SOAPEnvelope envelope = part.getEnvelope();
   SOAPBody body = envelope.getBody();
   SOAPBodyElement operation = body.addBodyElement(
       envelope.createName("resize", "ps", "http://example.com"));
   DataHandler dh = new DataHandler(new FileDataSource(file));
   AttachmentPart attachment = message.createAttachmentPart(dh);
   SOAPElement source  = operation.addChildElement("source",""),
   SOAPElement percent = operation.addChildElement("percent","");
   message.addAttachmentPart(attachment);
   source.addAttribute(envelope.createName("href"), "cid:" + attachment.getContentId());
   percent.addTextNode("20");

   SOAPMessage result = connection.call(message,endPoint);
   part = result.getSOAPPart();
   envelope = part.getEnvelope();
   body = envelope.getBody();
   if(!body.hasFault())  {
      Iterator iterator = result.getAttachments();
      if(iterator.hasNext()) {
         dh = ((AttachmentPart)iterator.next()).getDataHandler();
         String fname = dh.getName();
         if (null != fname) return new File(fname);
      }
   }
   return null;
}
					

The code above will produce following SOAP 1.1 message with attachment:


POST /ws/resize HTTP/1.0
Content-Type: multipart/related; type="text/xml"; 
     start="<EB6FC7EDE9EF4E510F641C481A9FF1F3>"; 
     boundary="----=_Part_0_7145370.1075485514903"
Accept: application/soap+xml, multipart/related, text/*
Host: example.com:8080
SOAPAction: ""
Content-Length: 1506005

------=_Part_0_7145370.1075485514903
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: binary
Content-Id: <EB6FC7EDE9EF4E510F641C481A9FF1F3>

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soapenv:Body>
    <ps:resize  xmlns:ps="http://example.com">
      <source href="cid:E1A97E9D40359F85CA19D1B8A7C52AA3"/>
      <percent>20</percent>
    </ps:resize>
  </soapenv:Body>
</soapenv:Envelope>

------=_Part_0_7145370.1075485514903
Content-Type: image/jpeg
Content-Transfer-Encoding: binary
Content-Id: <E1A97E9D40359F85CA19D1B8A7C52AA3>

d3d3Lm1hcmNoYWwuY29taesgfSEVFES45345sdvgfszd==
------=_Part_0_7145370.1075485514903--
					
					

Professional hosting     Belorussian informational portal         Free SCWCD 1.4 Study Guide     Free SCBCD 1.3 Study Guide     SCDJWS 1.4 Quiz     Free IBM Certified Associate Developer Study Guide     Free SCJP 5.0 (Tiger) Study Guide     Free Mock Exam Engine     IBM Test 000-287. Enterprise Application Development with IBM WebSphere Studio, V5.0 Study Guide     IBM Test 000-255. Developing with IBM Rational Application Developer for WebSphere Software V6 Study Guide


Hosting provided by PerfoHost: KVM VPS provider. See PefoHost's KVM VPS vs OpenVZ/Virtuozzo vs XEN VPS comparative chart.
CRM-exporter: Vehicle Database Script 1999-2011