SOAP with Attachment API for Java (SAAJ) example

SAAJ is an indispensable tool for manipulating SOAP messages, especially if they have got attachments. We have illustrated all the steps in creating a SwA (SOAP Messages with Attachments) in the short self-explanatory example which can be adapted for all purposes.

package saajexample;

import java.awt.Image;
import java.awt.Toolkit;
import javax.xml.soap.*;

public class Main {

public static void main(String[] args) throws Exception {
// Factory needed to create SOAP message
MessageFactory msgFactory = MessageFactory.newInstance();
SOAPMessage message = msgFactory.createMessage();
// illustrate the story so far by dumping out the message
message.writeTo(System.out);
// detach the header from the SOAP Envelope
message.getSOAPHeader().detachNode();
System.out.println("");
message.writeTo(System.out);
// manipulate the body of the SOAP message
SOAPBody body = message.getSOAPBody();
SOAPElement getStockPrice = body.addChildElement(
"getStockPrice",
"rt",
"http://www.rajeev.com/jws/StockQuote");
System.out.println("");
message.writeTo(System.out);
getStockPrice.setEncodingStyle(SOAPConstants.URI_NS_SOAP_ENCODING);
System.out.println("");
message.writeTo(System.out);
SOAPElement code = getStockPrice.addChildElement("stockCode");
System.out.println("");
message.writeTo(System.out);
code.addTextNode("IBM");
System.out.println("");
message.writeTo(System.out);
// attach an image
Image image = Toolkit.getDefaultToolkit().createImage("raj.jpg");
AttachmentPart jpegAttach = message.createAttachmentPart();
// use setDataHandler method below if connecting to FileDataSource object for pdf file
jpegAttach.setContent(image, "image/jpeg");
// add the mime type for the image
jpegAttach.addMimeHeader("Content-Transfer-Encoding", "binary");
jpegAttach.setContentId("xxx");
message.addAttachmentPart(jpegAttach);
System.out.println("");
// message.writeTo(System.out); // cannot stream image
// check attachment created successfully
System.out.printf("Number of attachments: %d%n", message.countAttachments());
// remove the attachment and verify
message.removeAllAttachments();
System.out.printf("Number of attachments: %d%n", message.countAttachments());

}
}

W3C standards for web services

The key W3C standards for web services are SOAP (previously Simple Object Access Protocol), eXtensible Markup Language (XML), Web Services Description Language (WSDL) and, peripherally, Universal Description, Discovery and Integration (UDDI).

SOAP is protocol which facilitates message-based communication between heterogeneous systems using XML over HTTP (usually) in a defined form. The SOAP message envelop is well-formed, its tags are qualified by a namespace, avoids firewall issues as HTTP port is always open and is part of the body of HTTP request or response.

XML has become the de facto standard for exchanging data between systems as it segregates the meaning of data from its presentation in a plain Unicode text file. SOAP, WSDL and UDDI entries use XML. XML Schema Definition (XSD) is W3C standard for constraining documents vocabularies. The XML files are inherently readable, compressible, portable and support internationalisation, which are pre-requisites in a complex heterogeneous environment. To testify to its popularity, the vocabularies with defined elements and attributes exist for various business domains and the language is extensible. It has become the lingua franca of inter-system communication. SOAP protocol and WSDL descriptions use it. XML messages can be sent over HTTP channels, XML parsers exist in abundance and Data Type Definitions (DTD) or XML Schemas of various vocabularies means that irrespective of platform and implementation language a received XML document can be checked for conformance and meaning and facilitates communication.

WSDL provides platform-independent definition of interfaces of a web service. A WSDL definition describes the location, protocol, service operations, parameters etc in an XML file thus facilitating the segregation of description from the actual implementation. The definition enables one to understand the service and its operations and invoke them.

The UDDI specification is managed by OASIS but it is so central to web services use that it will be churlish to avoid it. UDDI enables web services to be registered and discovered in standard way. The creators of web services register their services in the registry and the potential customers/users discover them there and use them. The white pages, yellow pages and green pages of UDDI entries are well understood and utilised by all who are interested in services-oriented architecture.