Tutorial

The Java^TM Web Services Tutorial

Tutorial

This section will walk you through the basics of sending a SOAP message using the JAXM API. At the end of this chapter, you will know how to do the following:

Get a connection
Create a message
Add content to a message
Send a message
Retrieve the content from a response message
Create and retrieve a SOAP fault element

First, we'll walk through the steps in sending a request-response message for a client that does not use a messaging provider. Then we'll do a walkthrough of a client that uses a messaging provider sending a one-way message. Both types of client may add attachments to a message, so adding attachments is covered as a separate topic. Finally, we'll see what SOAP faults are and how they work.

The section Code Examples puts the code fragments you will produce into runnable applications, which you can test yourself. The JAXM part of the case study (JAXM Distributor Service) demonstrates how JAXM code can be used in a Web service, showing both the client and server code.

Client without a Messaging Provider

An application that does not use a messaging provider is limited to operating in a client role and can send only request-response messages. Though limited, it can make use of Web services that are implemented to do request-response messaging.

Getting a SOAPConnection Object

The first thing any JAXM client needs to do is get a connection, either a SOAPConnection object or a ProviderConnection object. The overview section (Connections) discusses these two types of connections and how they are used.

A client that does not use a messaging provider has only one choice for creating a connection, which is to create a SOAPConnection object. This kind of connection is a point-to-point connection, meaning that it goes directly from the sender to the destination (usually a URL) that the sender specifies.

The first step is to obtain a SOAPConnectionFactory object that you can use to create your connection. The SAAJ API makes this easy by providing the SOAPConnectionFactory class with a default implementation. You can get an instance of this implementation with the following line of code.
SOAPConnectionFactory scFactory = 
                    SOAPConnectionFactory.newInstance();
 
Notice that because newInstance is a static method, you will always use the class name SOAPConnectionFactory when you invoke its newInstance method.

Now you can use scFactory to create a SOAPConnection object.
SOAPConnection con = scFactory.createConnection();
 
You will use con later to send the message that is created in the next part.

Creating a Message

The next step is to create a message, which you do using a MessageFactory object. If you are a standalone client, you can use the default implementation of the MessageFactory class that the SAAJ API provides. The following code fragment illustrates getting an instance of this default message factory and then using it to create a message.
MessageFactory factory = MessageFactory.newInstance();
SOAPMessage message = factory.createMessage();
 
As is true of the newInstance method for SOAPConnectionFactory, the newInstance method for MessageFactory is static, so you invoke it by calling MessageFactory.newInstance. Note that it is possible to write your own implementation of a message factory and plug it in via system properties, but the default message factory is the one that will generally be used.

The other way to get a MessageFactory object is to retrieve it from a naming service where it has been registered. This way is available only to applications that use a messaging provider, and it will be covered later (in Creating a Message).

Parts of a Message

A SOAPMessage object is required to have certain elements, and 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

The SOAPHeader object, though optional, is included for convenience because most messages will use it. The SOAPBody object can hold the content of the message and can also contain fault messages that contain status information or details about a problem with the message. The section SOAP Faults walks you through how to use SOAPFault objects.

Accessing Elements of a Message

The next step in creating a message is to access its parts so that content can be added. The SOAPMessage object message, created in the previous code fragment, is where to start. It contains a SOAPPart object, so you use message to retrieve it.
SOAPPart soapPart = message.getSOAPPart();
 
Next you can use soapPart to retrieve the SOAPEnvelope object that it contains.
SOAPEnvelope envelope = soapPart.getEnvelope();
 
You can now use envelope to retrieve its empty SOAPHeader and SOAPBody objects.
SOAPHeader header = envelope.getHeader();
SOAPBody body = envelope.getBody();
 
Our example of a standalone client does not use a SOAP header, so you can delete it. 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

To add content to the body, you need to create a SOAPBodyElement object to hold the content. When you create any new element, you also need to create an associated Name object to identify it. One way to create Name objects is by using SOAPEnvelope methods, so you can use envelope from the previous code fragment to create the Name object for your new element.

Note: The SAAJ API augments the javax.xml.soap package by adding the SOAPFactory class, which lets you create Name objects without using a SOAPEnvelope object. This capability is useful for creating XML elements when you are not creating an entire message. For example, JAX-RPC implementations find this ability useful. When you are not working with a SOAPMessage object, you do not have access to a SOAPEnvelope object and thus need an alternate means of creating Name objects. In addition to a method for creating Name objects, the SOAPFactory class provides methods for creating Detail objects and SOAP fragments. You will find an explanation of Detail objects in the SOAP Fault sections Overview and Creating and Populating a SOAPFault Object.

Name objects associated with SOAPBody and SOAPHeader objects must be fully qualified; that is, they must be created with a local name, a prefix for the namespace being used, and a URI for the namespace. Specifying a namespace for an element makes clear which one is meant if there is more than one element with the same local name.

The code fragment that follows retrieves the SOAPBody object body from envelope, creates a Name object for the element to be added, and adds a new SOAPBodyElement object to body.
SOAPBody body = envelope.getBody();
Name bodyName = envelope.createName(""GetLastTradePrice"",
          ""m"", ""http://wombat.ztrade.com"");
SOAPBodyElement gltp = body.addBodyElement(bodyName);
 
At this point, body contains a SOAPBodyElement object identified by the Name object bodyName, but there is still no content in gltp. Assuming that you want to get a quote for the stock of Sun Microsystems, Inc., you need to create a child element for the symbol using the method addChildElement. Then you need to give it the stock symbol using the method addTextNode. The Name object for the new SOAPElement object symbol is initialized with only a local name, which is allowed for child elements.
Name name = envelope.createName("symbol");
SOAPElement symbol = gltp.addChildElement(name);
symbol.addTextNode(""SUNW"");
 
You might recall that the headers and content in a SOAPPart object must be in XML format. The JAXM API takes care of this for you, building the appropriate XML constructs automatically when you call methods such as addBodyElement, addChildElement, and addTextNode. Note that you can call the method addTextNode only on an element such as bodyElement or any child elements that are added to it. You cannot call addTextNode on a SOAPHeader or SOAPBody object because they contain elements, not text.

The content that you have just added to your SOAPBody object will look like the following when it is sent over the wire:
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  <SOAP-ENV:Body>
    <m:GetLastTradePrice xmlns:m=
              "http://wombat.ztrade.com">
      <symbol>SUNW</symbol>
    </m:GetLastTradePrice>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
 
Let's examine this XML excerpt line by line to see how it relates to your JAXM code. Note that an XML parser does not care about indentations, but they are generally used to indicate element levels and thereby make it easier for a human reader to understand.

JAXM code:
SOAPPart soapPart = message.getSOAPPart();
SOAPEnvelope envelope = soapPart.getEnvelope();
 
XML it produces:
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  . . . . . . (intervening elements omitted)  
</SOAP-ENV:Envelope>
 
The outermost element in this XML example is the SOAP envelope element, indicated by SOAP-ENV:Envelope. Envelope is the name of the element, and SOAP-ENV is the namespace prefix. The interface SOAPEnvelope represents a SOAP envelope.

The first line signals the beginning of the SOAP envelope element, and the last line signals the end of it; everything in between is part of the SOAP envelope. The second line has an attribute for the SOAP envelope element. xmlns stands for "XML namespace," and its value is the URI of the namespace associated with Envelope. This attribute is automatically included for you.

JAXM code:
SOAPBody body = envelope.getBody();
 
XML it produces:
  <SOAP-ENV:Body>
      . . . . . .
  </SOAP-ENV:Body>
 
These two lines mark the beginning and end of the SOAP body, represented in JAXM by a SOAPBody object.

JAXM code:
Name bodyName = envelope.createName("GetLastTradePrice",
          "m", "http://wombat.ztrade.com");
SOAPBodyElement gltp = body.addBodyElement(bodyName);
 
XML it produces:
  <m:GetLastTradePrice xmlns:m=
            "http://wombat.ztrade.com">
 
    . . . .
  </m:GetLastTradePrice>
 
These lines are what the SOAPBodyElement gltp in your code represents. "GetLastTradePrice" is its local name, "m" is its namespace prefix, and "http://wombat.ztrade.com" is its namespace URI.

JAXM code:
Name name = envelope.createName("symbol");
SOAPElement symbol = gltp.addChildElement(name);
symbol.addTextNode("SUNW");
 
XML it produces:
  <symbol>SUNW</symbol>
 
The String "SUNW" is the message content that your recipient, the stock quote service, receives.

Sending a Message

A standalone client uses a SOAPConnection object and must therefore use the SOAPConnection method call to send a message. This 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 = con.call(message, endpoint);
 
Your message sent 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 through using it.
con.close();
 
Getting the Content of a Message

The initial steps for retrieving a message's content are the same as those for giving content to a message: You first access the SOAPBody object, using the message to get the envelope and the envelope to get the body. Then you access its SOAPBodyElement object because that is the element to which content was added in the example. (In a later section you will see how to add content directly to the SOAPBody object, in which case you would not need to access the SOAPBodyElement object for adding content or for retrieving it.) To get the content, which was added with the method SOAPElement.addTextNode, you call the method Node.getValue. Note that getValue returns the value of the immediate child of the element that calls the method. Therefore, in the following code fragment, the method getValue is called on bodyElement, the element on which the method addTextNode was called.

In order to access bodyElement, you need to call the method getChildElement on body. Passing bodyName to getChildElement returns a java.util.Iterator object that contains all of the child elements identified by the Name object bodyName. You already know that there is only one, so just calling the method next on it will return the SOAPBodyElement you want. Note that the method Iterator.next returns a Java Object, so it is necessary to cast the Object it returns to a SOAPBodyElement object before assigning it to the variable bodyElement.
SOAPPart sp = response.getSOAPPart();
SOAPEnvelope env = sp.getEnvelope();
SOAPBody sb = env.getBody();
java.util.Iterator it = sb.getChildElements(bodyName);
SOAPBodyElement bodyElement = (SOAPBodyElement)it.next();
String lastPrice = bodyElement.getValue();
System.out.print("The last price for SUNW is "); 
System.out.println(lastPrice);
 
If there were more than one element with the name bodyName, you would have had to use a while loop using the method Iterator.hasNext to make sure that you got all of them.
while (it.hasNext()) {
  SOAPBodyElement bodyElement = (SOAPBodyElement)it.next();
  String lastPrice = bodyElement.getValue();
  System.out.print("The last price for SUNW is "); 
  System.out.println(lastPrice);
}
 
At this point, you have seen how to send a request-response message as a standalone client. You have also seen how to get the content from the response. The next part shows you how to send a message using a messaging provider.

Client with a Messaging Provider

Using a messaging provider gives you more flexibility than a standalone client has because it can take advantage of the additional functionality that a messaging provider can offer.

Getting a ProviderConnection Object

Whereas a SOAPConnection object is a point-to-point connection directly to a particular URL, a ProviderConnection object is a connection to a messaging provider. With this kind of connection, all messages that you send or receive go through the messaging provider.

As with getting a SOAPConnection object, the first step is to get a connection factory, but in this case, it is a ProviderConnectionFactory object. You can obtain a ProviderConnectionFactory object by retrieving it from a naming service. This is possible when your application is using a messaging provider and is deployed in a servlet or J2EE container. With a ProviderConnectionFactory object, you can create a connection to a particular messaging provider and thus be able to use the capabilities of a profile that the messaging provider supports.

To get a ProviderConnectionFactory object, you first supply the logical name of your messaging provider to the container at deployment time. This is the name associated with your messaging provider that has been registered with a naming service based on the Java Naming and Directory Interface (JNDI). You can then do a lookup using this name to obtain a ProviderConnectionFactory object that will create connections to your messaging provider. For example, if the name registered for your messaging provider is "ProviderABC", you can do a lookup on "ProviderABC" to get a ProviderConnectionFactory object and use it to create a connection to your messaging provider. This is what is done in the following code fragment. The first two lines use methods from the JNDI API to retrieve the ProviderConnectionFactory object, and the last line uses a method from the JAXM API to create the connection to the messaging provider. Note that because the JNDI method lookup returns a Java Object, you must convert it to a ProviderConnectionFactory object before assigning it to the variable pcFactory.
Context ctx = new InitialContext(); 
ProviderConnectionFactory pcFactory =
    (ProviderConnectionFactory)ctx.lookup("ProviderABC");

ProviderConnection pcCon = pcFactory.createConnection();
 
You will use pcCon, which represents a connection to your messaging provider, to get information about your messaging provider and to send the message you will create in the next section.

Creating a Message

You create all JAXM messages by getting a MessageFactory object and using it to create the SOAPMessage object. For the standalone client example, you simply used the default MessageFactory object obtained via the method MessageFactory.newInstance. However, when you are using a messaging provider, you obtain the MessageFactory object in a different way.

Getting a MessageFactory

If you are using a messaging provider, you create a MessageFactory object by using the method ProviderConnection.createMessageFactory. In addition, you pass it a String indicating the profile you want to use. To find out which profiles your messaging provider supports, you need to get a ProviderMetaData object with information about your provider. This is done by calling the method getMetaData on the connection to your provider. Then you need to call the method getSupportedProfiles to get an array of the profiles your messaging provider supports. Supposing that you want to use the ebXML profile, you need to see if any of the profiles in the array matches "ebxml". If there is a match, that profile is assigned to the variable profile, which can then be passed to the method createMessageFactory.
ProviderMetaData metaData = pcCon.getMetaData();
String[] supportedProfiles = metaData.getSupportedProfiles();
String profile = null;

for (int i=0; i < supportedProfiles.length; i++) {
  if (supportedProfiles[i].equals("ebxml")) {
    profile = supportedProfiles[i];
    break;
  }
}

MessageFactory factory = pcCon.createMessageFactory(profile);
 
You can now use factory to create a SOAPMessage object that conforms to the ebXML profile. This example uses the minimal ebXML profile implementation included in the Java WSDP. Note that the following line of code uses the class EbXMLMessageImpl, which is defined in the ebXML profile implementation and is not part of the JAXM API.
EbXMLMessageImpl message = (EbXMLMessageImpl)factory.
                    createMessage();
 
For this profile, instead of using Endpoint objects, you indicate Party objects for the sender and the receiver. This information will appear in the message's header, and the messaging provider will use it to determine where to send the message. The following lines of code use the methods setSender and setReceiver, which are defined in the EbXMLMessageImpl implementation. These methods not only create a SOAPHeader object but also give it content. You can use these methods because your SOAPMessage object is an EbXMLMessageImpl object, giving you access to the methods defined in EbXMLMessageImpl.
message.setSender(new Party("http://grand.products.com"));
message.setReceiver(new Party("http://whiz.gizmos.com"));
 
You can view the Javadoc comments for the ebXML and SOAP-RP profile implementations provided in this Java WSDP at the following location:
<JWSDP_HOME>/docs/jaxm/profile/com/sun/xml/messaging/
 
If you are not using a profile or you want to set content for a header not covered by your profile's implementation, you need to follow the steps shown in the next section.

Adding Content to the Header

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

The following code fragment retrieves the SOAPHeader object from envelope and adds a new SOAPHeaderElement object to it.
SOAPHeader header = envelope.getHeader();
Name headerName = envelope.createName("Purchase Order",
            "PO", "http://www.sonata.com/order");
SOAPHeaderElement headerElement =
            header.addHeaderElement(headerName);
 
At this point, header contains the SOAPHeaderElement object headerElement identified by the Name object headerName. Note that the addHeaderElement method both creates headerElement and adds it to header.

Now that you have identified headerElement with headerName and added it to header, the next step is to add content to headerElement, which the next line of code does with the method addTextNode.
headerElement.addTextNode("order");
 
Now you have the SOAPHeader object header that contains a SOAPHeaderElement object whose content is "order".

Adding Content to the SOAP Body

The process for adding content to the SOAPBody object is the same for clients using a messaging provider as it is for standalone clients. This is also the same as the process for adding content to the SOAPHeader object. You access the SOAPBody object, add a SOAPBodyElement object to it, and add text to the SOAPBodyElement object. It is possible to add additional SOAPBodyElement objects, and it is possible to add subelements to the SOAPBodyElement objects with the method addChildElement. For each element or child element, you add content with the method addTextNode.

The section on the standalone client demonstrated adding one SOAPBodyElement object, adding a child element, and giving it some text. The following example shows adding more than one SOAPBodyElement and adding text to each of them.

The code first creates the SOAPBodyElement object purchaseLineItems, which has a fully-qualified namespace associated with it. That is, the Name object for it has a local name, a namespace prefix, and a namespace URI. As you saw earlier, a SOAPBodyElement object is required to have a fully-qualified namespace, but child elements added to it may have Name objects with only the local name.
SOAPBody body = envelope.getBody();
Name bodyName = envelope.createName("PurchaseLineItems", "PO",
            "http://sonata.fruitsgalore.com");
SOAPBodyElement purchaseLineItems =
              body.addBodyElement(bodyName);

Name childName = envelope.createName("Order");
SOAPElement order =
      purchaseLineItems.addChildElement(childName);

childName = envelope.createName("Product");
SOAPElement product = order.addChildElement(childName);
product.addTextNode("Apple");

childName = envelope.createName("Price");
SOAPElement price = order.addChildElement(childName);
price.addTextNode("1.56");

childName = envelope.createName("Order");
SOAPElement order2 =
      purchaseLineItems.addChildElement(childName);

childName = envelope.createName("Product");
SOAPElement product2 = order2.addChildElement(childName);
product2.addTextNode("Peach");

childName = envelope.createName("Price");
SOAPElement price2 = order2.addChildElement(childName);
price2.addTextNode("1.48");
 
The JAXM code in the preceding example produces the following XML in the SOAP body:
<PO:PurchaseLineItems
 xmlns:PO="http://www.sonata.fruitsgalore/order">
  <Order>
    <Product>Apple</Product>
    <Price>1.56</Price>
  </Order>

  <Order>
    <Product>Peach</Product>
    <Price>1.48</Price>
  </Order>
</PO:PurchaseLineItems>
 
Adding Content to the SOAPPart Object

If the content you want to send is in a file, JAXM provides an easy way to add it directly to the SOAPPart object. This means that you do not access the SOAPBody object and build the XML content yourself, as you did in the previous section.

To add a file directly to the SOAPPart object, you use a javax.xml.transform.Source object from JAXP (the Java API for XML Processing). There are three types of Source objects: SAXSource, DOMSource, and StreamSource. A StreamSource object holds content as an XML document. SAXSource and DOMSource objects hold content along with the instructions for transforming the content into an XML document.

The following code fragment uses JAXP API to build a DOMSource object that is passed to the SOAPPart.setContent method. The first two lines of code get a DocumentBuilderFactory object and use it to create the DocumentBuilder object builder. Then builder parses the content file to produce a Document object, which is used to initialize a new DOMSource object.
DocumentBuilderFactory dbFactory = DocumentBuilderFactory.
                    newInstance();
DocumentBuilder builder = dbFactory.newDocumentBuilder();
Document doc = builder.parse("file:///music/order/soap.xml");
DOMSource domSource = new DOMSource(doc);
 
The following two lines of code access the SOAPPart object (using the SOAPMessage object message) and set the new DOMSource object as its content. The method SOAPPart.setContent not only sets content for the SOAPBody object but also sets the appropriate header for the SOAPHeader object.
SOAPPart soapPart = message.getSOAPPart();
soapPart.setContent(domSource);
 
You will see other ways to add content to a message in the section on AttachmentPart objects. One big difference to keep in mind is that a SOAPPart object must contain only XML data, whereas an AttachmentPart object may contain any type of content.

Sending the Message

When the connection is a ProviderConnection object, messages have to be sent using the method ProviderConnection.send. This method sends the message passed to it and returns immediately. Unlike the SOAPConnection method call, it does not have to block until it receives a response, which leaves the application free to do other things.

The send method takes only one argument, the message to be sent. It does not need to be given the destination because the messaging provider can use information in the header to figure out where the message needs to go.
pcCon.send(message);
pcCon.close();
 
Adding Attachments

Adding AttachmentPart objects to a message is the same for all clients, whether they use a messaging provider or not. As noted in earlier sections, you can put any type of content, including XML, in an AttachmentPart object. And because the SOAP part can contain only XML content, you must use an AttachmentPart object for any content that is not in XML format.

Creating an AttachmentPart Object and Adding Content

The SOAPMessage object creates an AttachmentPart object, and the message also has to add the attachment to itself after content has been added. The SOAPMessage class has three methods for creating an AttachmentPart object.

The first method creates an attachment with no content. In this case, an AttachmentPart method is used later to add content to the attachment.
AttachmentPart attachment = message.createAttachmentPart();
 
You add content to attachment with the AttachmentPart method setContent. This method takes two parameters, a Java Object for the content, and a String object that gives the content type. Content in the SOAPBody part of a message automatically has a Content-Type header with the value "text/xml" because the content has to be in XML. In contrast, the type of content in an AttachmentPart object has to be specified because it can be any type.

Each AttachmentPart object has one or more headers associated with it. When you specify a type to the method setContent, that type is used for the header Content-Type. Content-Type is the only header that is required. You may set other optional headers, such as Content-Id and Content-Location. For convenience, JAXM provides get and set methods for the headers Content-Type, Content-Id, and Content-Location. These headers can be helpful in accessing a particular attachment when a message has multiple attachments. For example, to access the attachments that have particular headers, you call the SOAPMessage method getAttachments and pass it the header or headers you are interested in.

The following code fragment shows one of the ways to use the method setContent. The Java Object being added is a String, which is plain text, so the second argument has to be "text/plain". The code also sets a content identifier, which can be used to identify this AttachmentPart object. After you have added content to attachment, you need to add attachment to the SOAPMessage object, which is done in the last line.
String stringContent = "Update address for Sunny Skies " + 
  "Inc., to 10 Upbeat Street, Pleasant Grove, CA 95439";

attachment.setContent(stringContent, "text/plain");
attachment.setContentId("update_address");

message.addAttachmentPart(attachment);
 
The variable attachment now represents an AttachmentPart object that contains the String stringContent and has a header that contains the String "text/plain". It also has a Content-Id header with "update_address" as its value. And now attachment is part of message.

Let's say you also want to attach a jpeg image showing how beautiful the new location is. In this case, the second argument passed to setContent must be "image/jpeg" to match the content being added. The code for adding an image might look like the following. For the first attachment, the Object passed to the method setContent was a String. In this case, it is a stream.
AttachmentPart attachment2 = message.createAttachmentPart();

byte[] jpegData = . . .;
ByteArrayInputStream stream = new ByteArrayInputStream(
                jpegData);

attachment2.setContent(stream, "image/jpeg");

message.addAttachmentPart(attachment);
 
The other two SOAPMessage.createAttachment methods create an AttachmentPart object complete with content. One is very similar to the AttachmentPart.setContent method in that it takes the same parameters and does essentially the same thing. It takes a Java Object containing the content and a String giving the content type. As with AttachmentPart.setContent, the Object may be a String, a stream, a javax.xml.transform.Source object, or a javax.activation.DataHandler object. You have already seen an example of using a Source object as content. The next example will show how to use a DataHandler object for content.

The other method for creating an AttachmentPart object with content takes a DataHandler object, which is part of the JavaBeans Activation Framework (JAF). Using a DataHandler object is fairly straightforward. First you create a java.net.URL object for the file you want to add as content. Then you create a DataHandler object initialized with the URL object and pass it to the method createAttachmentPart.
URL url = new URL("http://greatproducts.com/gizmos/img.jpg");
DataHandler dh = new DataHandler(url);
AttachmentPart attachment = message.createAttachmentPart(dh);
attachment.setContentId("gyro_image");

message.addAttachmentPart(attachment);
 
You might note two things about the previous code fragment. First, it sets a header for Content-ID with the method setContentId. This method takes a String that can be whatever you like to identify the attachment. Second, unlike the other methods for setting content, this one does not take a String for Content-Type. This method takes care of setting the Content-Type header for you, which is possible because one of the things a DataHandler object does is determine the data type of the file it contains.

Accessing an AttachmentPart Object

If you receive a message with attachments or want to change an attachment to a message you are building, you will need to access the attachment. When it is given no argument, the method SOAPMessage.getAttachments returns a java.util.Iterator object over all the AttachmentPart objects in a message. The following code prints out the content of each AttachmentPart object in the SOAPMessage object message.
java.util.Iterator it = message.getAttachments();
while (it.hasNext()) {
  AttachmentPart attachment = (AttachmentPart)it.next();
  Object content = attachment.getContent();
  String id = attachment.getContentId();
  System.out.print("Attachment " + id + " contains: " + 
                        content);
  System.out.println("");
}
 
Summary

In this section, you have been introduced to the basic JAXM API. You have seen how to create and send SOAP messages as a standalone client and as a client using a messaging provider. You have walked through adding content to a SOAP header and a SOAP body and also walked through creating attachments and giving them content. In addition, you have seen how to retrieve the content from the SOAP part and from attachments. In other words, you have walked through using the basic JAXM API.

SOAP Faults

This section expands on the basic JAXM API by showing you how to use the API for creating and accessing a SOAP Fault element in an XML message.

Overview

If you send a message that was not successful for some reason, you may get back a response containing a SOAP Fault element that gives you status information, error information, or both. There can be only one SOAP Fault element in a message, and it must be an entry in the SOAP Body. The SOAP 1.1 specification defines only one Body entry, which is the SOAP Fault element. Of course, the SOAP Body may contain other Body entries, but the SOAP Fault element is the only one that has been defined.

A SOAPFault object, the representation of a SOAP Fault element in the JAXM API, is similar to an Exception object in that it conveys information about a problem. However, a SOAPFault object is quite different in that it is an element in a message's SOAPBody object rather than part of the try/catch mechanism used for Exception objects. Also, as part of the SOAPBody object, which provides a simple means for sending mandatory information intended for the ultimate recipient, a SOAPFault object only reports status or error information. It does not halt the execution of an application the way an Exception object can.

Various parties may supply a SOAPFault object in a message. If you are a standalone client using the SAAJ API, and thus sending point-to-point messages, the recipient of your message may add a SOAPFault object to the response to alert you to a problem. For example, if you sent an order with an incomplete address for where to send the order, the service receiving the order might put a SOAPFault object in the return message telling you that part of the address was missing.

In another scenario, if you use the JAXM 1.1_01 API in order to use a messaging provider, the messaging provider may be the one to supply a SOAPFault object. For example, if the provider has not been able to deliver a message because a server is unavailable, the provider might send you a message with a SOAPFault object containing that information. In this case, there was nothing wrong with the message itself, so you can try sending it again later without any changes. In the previous example, however, you would need to add the missing information before sending the message again.

A SOAPFault object contains the following elements:

a fault code -- always requiredThe SOAP 1.1 specification defines a set of fault code values in section 4.4.1, which a developer may extend to cover other problems. The default fault codes defined in the specification relate to the JAXM API as follows:

VersionMismatch -- the namespace for a SOAPEnvelope object was invalid
MustUnderstand -- an immediate child element of a SOAPHeader object had its mustUnderstand attribute set to "1", and the processing party did not understand the element or did not obey it
Client -- the SOAPMessage object was not formed correctly or did not contain the information needed to succeed
Server -- the SOAPMessage object could not be processed because of a processing error, not because of a problem with the message itself

a fault string -- always requireda human readable explanation of the fault
a fault actor -- required if the SOAPHeader object contains one or more actor attributes; optional if no actors are specified, meaning that the only actor is the ultimate destinationThe fault actor, which is specified as a URI, identifies who caused the fault. For an explanation of what an actor is, see the section Intermediate Destinations.
a Detail object -- required if the fault is an error related to the SOAPBody object If, for example, the fault code is "Client", indicating that the message could not be processed because of a problem in the SOAPBody object, the SOAPFault object must contain a Detail object that gives details about the problem. If a SOAPFault object does not contain a Detail object, it can be assumed that the SOAPBody object was processed successfully.

Creating and Populating a SOAPFault Object

You have already seen how to add content to a SOAPBody object; this section will walk you through adding a SOAPFault object to a SOAPBody object and then adding its constituent parts.

As with adding content, the first step is to access the SOAPBody object.
SOAPEnvelope envelope =
            msg.getSOAPPart().getEnvelope();
SOAPBody body = envelope.getBody();
 
With the SOAPBody object body in hand, you can use it to create a SOAPFault object with the following line of code.
SOAPFault fault = body.addFault();
 
The following code uses convenience methods to add elements and their values to the SOAPFault object fault. For example, the method setFaultCode creates an element, adds it to fault, and adds a Text node with the value "Server".
fault.setFaultCode("Server");
fault.setFaultActor("http://gizmos.com/orders");
fault.setFaultString("Server not responding");
 
The SOAPFault object fault created in the previous lines of code indicates that the cause of the problem is an unavailable server and that the actor at "http://gizmos.com/orders" is having the problem. If the message were being routed only to its ultimate destination, there would have been no need for setting a fault actor. Also note that fault does not have a Detail object because it does not relate to the SOAPBody object.

The following code fragment creates a SOAPFault object that includes a Detail object. Note that a SOAPFault object may have only one Detail object, which is simply a container for DetailEntry objects, but the Detail object may have multiple DetailEntry objects. The Detail object in the following lines of code has two DetailEntry objects added to it.
SOAPFault fault = body.addFault();

fault.setFaultCode("Client");
fault.setFaultString("Message does not have necessary info");

Detail detail = fault.addDetail();

Name entryName = envelope.createName("order", "PO",
                "http://gizmos.com/orders/");
DetailEntry entry = detail.addDetailEntry(entryName);
entry.addTextNode("quantity element does not have a value");

Name entryName2 = envelope.createName("confirmation", "PO",
                  "http://gizmos.com/confirm");
DetailEntry entry2 = detail.addDetailEntry(entryName2);
entry2.addTextNode("Incomplete address: no zip code");
 
Retrieving Fault Information

Just as the SOAPFault interface provides convenience methods for adding information, it also provides convenience methods for retrieving that information. The following code fragment shows what you might write to retrieve fault information from a message you received. In the code fragment, newmsg is the SOAPMessage object that has been sent to you. Because a SOAPFault object must be part of the SOAPBody object, the first step is to access the SOAPBody object. Then the code tests to see if the SOAPBody object contains a SOAPFault object. If so, the code retrieves the SOAPFault object and uses it to retrieve its contents. The convenience methods getFaultCode, getFaultString, and getFaultActor make retrieving the values very easy.
  SOAPBody body = 
          newmsg.getSOAPPart().getEnvelope().getBody();
  if ( body.hasFault() ) {
    SOAPFault newFault = body.getFault();
    String code = newFault.getFaultCode();
    String string = newFault.getFaultString();
    String actor = newFault.getFaultActor();
 
Next the code prints out the values it just retrieved. Not all messages are required to have a fault actor, so the code tests to see if there is one. Testing whether the variable actor is null works because the method getFaultActor returns null if a fault actor has not been set.
    System.out.println("SOAP fault contains: ");
    System.out.println("    fault code = " + code);
    System.out.println("    fault string = " + string);
 
    if ( actor != null ) {
      System.out.println("    fault actor = " + actor);
    }
  }
 
The final task is to retrieve the Detail object and get its DetailEntry objects. The code uses the SOAPFault object newFault to retrieve the Detail object newDetail, and then it uses newDetail to call the method getDetailEntries. This method returns the java.util.Iterator object it, which contains all of the DetailEntry objects in newDetail. Not all SOAPFault objects are required to have a Detail object, so the code tests to see whether newDetail is null. If it is not, the code prints out the values of the DetailEntry object(s) as long as there are any.
  Detail newDetail = newFault.getDetail();
  if ( newDetail != null) {
    Iterator it = newDetail.getDetailEntries();
    while ( it.hasNext() ) {
      DetailEntry entry = (DetailEntry)it.next();
      String value = entry.getValue();
      System.out.println("    Detail entry = " + value);
    }
  }
 
In summary, you have seen how to add a SOAPFault object and its contents to a message as well as how to retrieve the information in a SOAPFault object. A SOAPFault object, which is optional, is added to the SOAPBody object to convey status or error information. It must always have a fault code and a String explanation of the fault. A SOAPFault object must indicate the actor that is the source of the fault only when there are multiple actors; otherwise, it is optional. Similarly, the SOAPFault object must contain a Detail object with one or more DetailEntry objects only when the contents of the SOAPBody object could not be processed successfully.

Home
TOC
Index

This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.

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