Tuesday, December 19, 2006

Creating a SOAP message

The first step is to create a message using a MessageFactory object. The SAAJ API provides a default implementation of the MessageFactory class, thus making it easy to get an instance. The following code fragment illustrates getting an instance of the default message factory and then using it to create a message.

MessageFactory factory = MessageFactory.newInstance();
SOAPMessage message = factory.createMessage();
Parts of a Message

A SOAPMessage object is required to have certain elements, and, as stated previously, the SAAJ API simplifies things for you by returning a new SOAPMessage object that already contains these elements. So message, which was created in the preceding line of code, automatically has the following:

I. A SOAPPart object that contains

A. A SOAPEnvelope object that contains

1. An empty SOAPHeader object

2. An empty SOAPBody object


SOAPPart soapPart = message.getSOAPPart();


SOAPEnvelope envelope = soapPart.getEnvelope();

SOAPHeader header = envelope.getHeader();

SOAPBody body = envelope.getBody();

OR you can directly access a soap header llike:

SOAPHeader header = message.getSOAPHeader();

SOAPBody body = message.getSOAPBody();

This example of a SAAJ client does not use a SOAP header, so you can delete it. (You will see more about headers later.) Because all SOAPElement objects, including SOAPHeader objects, are derived from the Node interface, you use the method Node.detachNode to delete header.

header.detachNode();

Adding Content to the Body


SOAPBody body = message.getSOAPBody();

SOAPFactory soapFactory = SOAPFactory.newInstance();

Name bodyName = soapFactory.createName
("GetLastTradePrice", "m", "http://wombat.ztrade.com");


SOAPBodyElement bodyElement = body.addBodyElement(bodyName);

Name name = soapFactory.createName("symbol");

SOAPElement symbol = bodyElement.addChildElement(name);

symbol.addTextNode("SUNW");

The content that you have just added to your SOAPBody object will look like the following when it is sent over the wire:







SUNW







Getting a SOAPConnection Object

SOAPConnectionFactory soapConnectionFactory =
SOAPConnectionFactory.newInstance();


Now you can use soapConnectionFactory to create a SOAPConnection object.

SOAPConnection connection =
soapConnectionFactory.createConnection();


Sending a Message

A SAAJ client calls the SOAPConnection method call on a SOAPConnection object to send a message. The call method takes two arguments: the message being sent and the destination to which the message should go. This message is going to the stock quote service indicated by the URL object endpoint.

java.net.URL endpoint = new URL("http://wombat.ztrade.com/quotes");

SOAPMessage response = connection.call(message, endpoint);

The content of the message you sent is the stock symbol SUNW; the SOAPMessage object response should contain the last stock price for Sun Microsystems, which you will retrieve in the next section.

A connection uses a fair amount of resources, so it is a good idea to close a connection as soon as you are finished using it.

connection.close();

Getting the Content of a Message

To add content to the header, you create a SOAPHeaderElement object. As with all new elements, it must have an associated Name object, which you can create using the message's SOAPEnvelope object or a SOAPFactory object.

For example, suppose you want to add a conformance claim header to the message to state that your message conforms to the WS-I Basic Profile. The following code fragment retrieves the SOAPHeader object from message and adds a new SOAPHeaderElement object to it. This SOAPHeaderElement object contains the correct qualified name and attribute for a WS-I conformance claim header.

SOAPHeader header = message.getSOAPHeader();

Name headerName = soapFactory.createName("Claim","wsi", "http://ws-i.org/schemas/conformanceClaim/");

SOAPHeaderElement headerElement = header.addHeaderElement(headerName);

headerElement.addAttribute(soapFactory.createName("conformsTo"), "http://ws-i.org/profiles/basic1.0/");


conformance claim header has no content. This code produces the following XML header:






For a different kind of header, you might want to add content to headerElement. The following line of code uses the method addTextNode to do this.

headerElement.addTextNode("order");

No comments: