Code Examples | The JavaT EE 5 Tutorial

The first part of this tutorial uses code fragments to walk you through the fundamentals of using the SAAJ API. In this section, you will use some of those code fragments to create applications. First, you will see the program Request.java. Then you will see how to run the programs MyUddiPing.java, HeaderExample.java, DOMExample.java, DOMSrcExample.java, Attachments.java, and SOAPFaultTest.java.

Note

Before you run any of the examples, follow the preliminary setup instructions in Building the Examples (page xxxv).

Request.java

The class Request.java puts together the code fragments used in the section Tutorial (page 639) and adds what is needed to make it a complete example of a client sending a request-response message. In addition to putting all the code together, it adds import statements, a main method, and a try/catch block with exception handling.

   import javax.xml.soap.*;    import javax.xml.namespace.QName;    import java.util.Iterator;    import java.net.URL;    public class Request {      public static void main(String[] args){        try {          SOAPConnectionFactory soapConnectionFactory =             SOAPConnectionFactory.newInstance();          SOAPConnection connection =             soapConnectionFactory.createConnection();          MessageFactory factory =             MessageFactory.newInstance();          SOAPMessage message = factory.createMessage();          SOAPHeader header = message.getSOAPHeader();          SOAPBody body = message.getSOAPBody();          header.detachNode();          QName bodyName = new QName("http://wombat.ztrade.com",             "GetLastTradePrice", "m");          SOAPBodyElement bodyElement =             body.addBodyElement(bodyName);          QName name = new QName("symbol");          SOAPElement symbol =             bodyElement.addChildElement(name);          symbol.addTextNode("SUNW");          URL endpoint = new URL             ("http://wombat.ztrade.com/quotes");          SOAPMessage response =             connection.call(message, endpoint);          connection.close();          SOAPBody soapBody = response.getSOAPBody();          Iterator iterator =             soapBody.getChildElements(bodyName);          bodyElement = (SOAPBodyElement)iterator.next();          String lastPrice = bodyElement.getValue();          System.out.print("The last price for SUNW is ");          System.out.println(lastPrice);        } catch (Exception ex) {          ex.printStackTrace();        }      }    }

For Request.java to be runnable, the second argument supplied to the call method would have to be a valid existing URI, and this is not true in this case. However, the application in the next section is one that you can run.

MyUddiPing.java

The program MyUddiPing.java is another example of a SAAJ client application. It sends a request to a Universal Description, Discovery and Integration (UDDI) service and gets back the response. A UDDI service is a business registry from which you can get information about businesses that have registered themselves with the registry service. For this example, the MyUddiPing application accesses a private UDDI service registry. Because of this, the number of businesses you can get information about is limited. Nevertheless, MyUddiPing demonstrates a request being sent and a response being received.

The MyUddiPing example is in the following directory:

   <INSTALL>/javaeetutorial5/examples/saaj/myuddiping/

Note

<INSTALL> is the directory where you installed the tutorial bundle.

Examining MyUddiPing

We will go through the file MyUddiPing.java a few lines at a time, concentrating on the last section. This is the part of the application that accesses only the content you want from the XML message returned by the UDDI registry.

The first lines of code import the interfaces used in the application.

   import javax.xml.soap.SOAPConnectionFactory;    import javax.xml.soap.SOAPConnection;    import javax.xml.soap.MessageFactory;    import javax.xml.soap.SOAPMessage;    import javax.xml.soap.SOAPHeader;    import javax.xml.soap.SOAPBody;    import javax.xml.soap.SOAPBodyElement;    import javax.xml.soap.SOAPElement;    import javax.xml.namespace.QName;    import java.net.URL;    import java.util.Properties;    import java.util.Enumeration;    import java.util.Iterator;    import java.util.Locale;    import java.io.FileInputStream;

The next few lines begin the definition of the class MyUddiPing, which starts with the definition of its main method. The following lines create a java.util.Properties object that contains the system properties and the properties from the file uddi.properties, which is in the myuddiping directory.

   public class MyUddiPing {      public static void main(String[] args) {        try {          Properties myprops = new Properties();          myprops.load(new FileInputStream(args[0]));          Properties props = System.getProperties();          Enumeration propNames = myprops.propertyNames();          while (propNames.hasMoreElements()) {            String s = (String) propNames.nextElement();            props.setProperty(s, myprops.getProperty(s));          }

The next four lines create a SOAPMessage object. First, the code gets an instance of SOAPConnectionFactory and uses it to create a connection. Then it gets an instance of a SOAP 1.1 MessageFactory, using the MessageFactory instance to create a message.

   SOAPConnectionFactory soapConnectionFactory =      SOAPConnectionFactory.newInstance();    SOAPConnection connection =      soapConnectionFactory.createConnection();    MessageFactory messageFactory =      MessageFactory.newInstance();    SOAPMessage message = messageFactory.createMessage();

The next lines of code retrieve the SOAPHeader and SOAPBody objects from the message and remove the header.

   SOAPHeader header = message.getSOAPHeader();    header.detachNode();    SOAPBody body = message.getSOAPBody();

The following lines of code create the UDDI find_business message. The first line creates a SOAPBodyElement with a fully qualified name, including the required namespace for a UDDI version 2 message. The next lines add two attributes to the new element: the required attribute generic, with the UDDI version number 2.0, and the optional attribute maxRows, with the value 100. Then the code adds a child element that has the QName object name and adds the xml:lang attribute set to the default locale. The code then adds text to the element by using the method addTextNode. The added text is the business name you will supply at the command line when you run the application.

   SOAPBodyElement findBusiness =       body.addBodyElement(new QName(          "urn:uddi-org:api_v2", "find_business"));    findBusiness.addAttribute(new QName("generic"), "2.0");    findBusiness.addAttribute(new QName("maxRows"), "100");    SOAPElement businessName =       findBusiness.addChildElement(new QName("name"));    Locale loc = Locale.getDefault();    businessName.addAttribute(new QName("xml:lang"),       loc.toString());       //"en-US");    businessName.addTextNode(args[1]);

The next line of code saves the changes that have been made to the message. This method will be called automatically when the message is sent, but it does not hurt to call it explicitly.

   message.saveChanges();

The following lines display the message that will be sent:

   System.out.println("\n---- Request Message ----\n");    message.writeTo(System.out);

The next line of code creates the java.net.URL object that represents the destination for this message. It gets the value of the property named URL from the system properties.

   URL endpoint = new URL(      System.getProperties().getProperty("URL"));

Next, the message message is sent to the destination that endpoint represents, which is the UDDI test registry. The call method will block until it gets a SOAPMessage object back, at which point it returns the reply.

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

In the next lines of code, the first line prints a line giving the URL of the sender (the test registry), and the others display the returned message.

   System.out.println("\n\nReceived reply from: " +      endpoint);    System.out.println("\n---- Reply Message ----\n");    reply.writeTo(System.out);

The returned message is the complete SOAP message, an XML document, as it looks when it comes over the wire. It is a businessList that follows the format specified in http://uddi.org/pubs/DataStructure-V2.03-Published-20020719.htm#_Toc25130802.

As interesting as it is to see the XML that is actually transmitted, the XML document format does not make it easy to see the text that is the message's content. To remedy this, the last part of MyUddiPing.java contains code that prints only the text content of the response, making it much easier to see the information you want.

Because the content is in the SOAPBody object, the first step is to access it, as shown in the following line of code.

   SOAPBody replyBody = reply.getSOAPBody();

Next, the code displays a message describing the content:

   System.out.println("\n\nContent extracted from " +      "the reply message:\n");

To display the content of the message, the code uses the known format of the reply message. First, it gets all the reply body's child elements named businessList:

   Iterator businessListIterator =      replyBody.getChildElements(new QName(        "urn:uddi-org:api_v2",        "businessList"));

The method getChildElements returns the elements in the form of a java.util.Iterator object. You access the child elements by calling the method next on the Iterator object. An immediate child of a SOAPBody object is a SOAPBodyElement object.

We know that the reply can contain only one businessList element, so the code then retrieves this one element by calling the iterator's next method. Note that the method Iterator.next returns an Object, which must be cast to the specific kind of object you are retrieving. Thus, the result of calling businessListIterator.next is cast to a SOAPBodyElement object:

   SOAPBodyElement businessList =      (SOAPBodyElement) businessListIterator.next();

The next element in the hierarchy is a single businessInfos element, so the code retrieves this element in the same way it retrieved the businessList. Children of SOAPBodyElement objects and all child elements from this point forward are SOAPElement objects.

   Iterator businessInfosIterator =      businessList.getChildElements(new QName(        "urn:uddi-org:api_v2", "businessInfos"));    SOAPElement businessInfos =      (SOAPElement) businessInfosIterator.next();

The businessInfos element contains zero or more businessInfo elements. If the query returned no businesses, the code prints a message saying that none were found. If the query returned businesses, however, the code extracts the name and optional description by retrieving the child elements that have those names. The method Iterator.hasNext can be used in a while loop because it returns true as long as the next call to the method next will return a child element. Accordingly, the loop ends when there are no more child elements to retrieve.

   Iterator businessInfoIterator =      businessInfos.getChildElements(        soapFactory.createName("businessInfo",          "", "urn:uddi-org:api_v2"));    if (! businessInfoIterator.hasNext()) {      System.out.println("No businesses found " +         "matching the name \"" + args[1] + "\".");    } else {         while (businessInfoIterator.hasNext()) {           SOAPElement businessInfo =              (SOAPElement) businessInfoIterator.next();           Iterator nameIterator =             businessInfo.getChildElements(new QName(               "urn:uddi-org:api_v2", "name"));           while (nameIterator.hasNext()) {             businessName =               (SOAPElement)nameIterator.next();             System.out.println("Company name: " +               businessName.getValue());           }           Iterator descriptionIterator =             businessInfo.getChildElements(new QName(               "urn:uddi-org:api_v2", "description"));           while (descriptionIterator.hasNext()) {             SOAPElement businessDescription =               (SOAPElement) descriptionIterator.next();             System.out.println("Description: " +               businessDescription.getValue());           }           System.out.println("");         }       }    }

Finally, the program closes the connection:

   connection.close();

Accessing a Registry

Before you can run MyUddiPing, you must install the Java WSDP Registry Server, a private UDDI registry. To install this registry, follow the instructions in Preliminaries: Getting Access to a Registry (page 697).

MyUddiPing will not return any results until you have run some of the examples in Chapter 19.

The file uddi.properties contains the URL of the destination. If the Application Server where you install the registry is running on a remote system, open uddi.properties in a text editor and replace localhost with the name of the remote system.

Building and Running MyUddiPing Using NetBeans 5.5

To build the program using NetBeans 5.5, follow these steps:

1.	In NetBeans 5.5, choose Open Project from the File menu.
2.	In the Open Project dialog, navigate to `<INSTALL>/javaeetutorial5/examples/saaj/`.
3.	Select the `myuddiping` folder.
4.	Select the Open as Main Project checkbox.
5.	Click Open Project Folder. A Reference Problems dialog appears. Click Close.
6.	Right-click the `myuddiping` project and choose Resolve Reference Problems.
7.	In the Resolve Reference Problems dialog, select the first of the missing JAR files and click Resolve. The missing files are `activation.jar`, `javaee.jar`, and `appserv-ws.jar`.
8.	Navigate to the `<JAVAEE_HOME>/lib/` directory.
9.	Select the missing JAR file (`activation.jar`, for example) and click Open. In the Resolve Reference Problems dialog, all the files have green check marks to the left of their names.
10.	Click Close.
11.	Right-click the project and choose Build Project.

To run the program using NetBeans 5.5, follow these steps:

1.	Right-click the `myuddiping` project and choose Properties.
2.	Select Run from the Categories tree.
3.	In the Arguments field, type the following: uddi.properties the The first argument is the name of the file `uddi.properties`. The second argument represents the first few letters of the name of the business for which you want to get a description.

4.	Click OK.
5.	Right-click the project and choose Run Project.

The program output depends on the contents of the registry. For example:

   Content extracted from the reply message:    Company name: The Coffee Break    Description: Purveyor of the finest coffees. Established 1950    Company name: The Coffee Enterprise Bean Break    Description: Purveyor of the finest coffees. Established 1950

If the program returns no results, see Troubleshooting MyUddiPing (page 677) for a possible solution.

To remove the generated files, right-click the project and choose Clean Project.

Building and Running MyUddiPing Using Ant

To build and run MyUddiPing using Ant, go to the directory <INSTALL>/javaeetutorial5/examples/saaj/myuddiping/ and use the run-ping target.

The run-ping target takes two arguments, but you need to supply only one of them. The first argument is the file uddi.properties, which is supplied by a property that is set in build.xml. The other argument is the first few letters of the name of the business for which you want to get a description, and you need to supply this argument on the command line. Note that any property set on the command line overrides any value set for that property in the build.xml file.

The run-ping target depends on the compile target, which compiles the source file and places the resulting .class file in the directory build/classes.

Use a command like the following to run the example:

   ant run-ping -Dbusiness-name=the

The program output depends on the contents of the registry. For example:

   Content extracted from the reply message:    Company name: The Coffee Break    Description: Purveyor of the finest coffees. Established 1950    Company name: The Coffee Enterprise Bean Break    Description: Purveyor of the finest coffees. Established 1950

To remove the generated files, use the following command:

   ant clean

Troubleshooting MyUddiPing

If MyUddiPing returns no matching businesses, even if you know that the registry contains at least one, there may be a mismatch between the default locale setting on your system and the way JAXR stores names and descriptions of objects. This problem is most likely to occur on Windows systems. Look for the part of the output Request Message that contains the xml:lang attribute. It may look like this:

   <name xml:lang="en_US">

The default locale setting being used by the program is en_US, but JAXR may have stored the business in the registry using the locale setting en-US. If you have this problem with your locale, follow these steps:

1.	Open the file `src/MyUddiPing.java` in a text editor.
2.	Find the following lines: businessName.addAttribute(new QName("xml:lang"), loc.toString()); //"en-US");
3.	Remove the comment characters from the last line and, if necessary, edit the string to specify your own locale.
4.	Put comment characters at the beginning of the second line. The result should look something like this: //loc.toString()); "en-US");
5.	Rebuild and rerun MyUddiPing.

HeaderExample.java

The example HeaderExample.java, based on the code fragments in the section Adding Attributes (page 655), creates a message that has several headers. It then retrieves the contents of the headers and prints them. The example generates either a SOAP 1.1 message or a SOAP 1.2 message, depending on arguments you specify. You will find the code for HeaderExample in the following directory:

   <INSTALL>/javaeetutorial5/examples/saaj/headers/src/

Building and Running HeaderExample

To build the program using NetBeans 5.5, follow these steps:

1.	In NetBeans 5.5, choose Open Project from the File menu.
2.	In the Open Project dialog, navigate to `<INSTALL>/javaeetutorial5/examples/saaj/`.
3.	Select the `headers` folder.
4.	Select the Open as Main Project checkbox.
5.	Click Open Project Folder. A Reference Problems dialog appears. Click Close.
6.	Right-click the `headers` project and choose Resolve Reference Problems.
7.	In the Resolve Reference Problems dialog, select the first of the missing JAR files and click Resolve. The missing files are `activation.jar`, `javaee.jar`, and `appserv-ws.jar`.
8.	Navigate to the `<JAVAEE_HOME>/lib/` directory.
9.	Select the missing JAR file (`activation.jar`, for example) and click Open. In the Resolve Reference Problems dialog, all the files have green check marks to the left of their names.
10.	Click Close.
11.	Right-click the project and choose Build Project.

To run the program using NetBeans 5.5, follow these steps:

1.	Right-click the `headers` project and choose Properties.
2.	Select Run from the Categories tree.
3.	In the Arguments field, type the following: 1.1 This argument specifies the version of SOAP to be used in generating the message.
4.	Click OK.
5.	Right-click the project and choose Run Project.
6.	Right-click the project and choose Properties.
7.	Select Run from the Categories tree.
8.	In the Arguments field, type the following: 1.2
9.	Click OK.
10.	Right-click the project and choose Run Project.

To build and run HeaderExample using Ant, go to the directory <INSTALL>/javaeetutorial5/examples/saaj/headers/. Use one of the following commands:

   ant run-headers -Dsoap=1.1    ant run-headers -Dsoap=1.2

When you run HeaderExample to generate a SOAP 1.1 message, you will see output similar to the following:

   ----- Request Message ----    <SOAP-ENV:Envelope    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">    <SOAP-ENV:Header>    <ns:orderDesk xmlns:ns="http://gizmos.com/NSURI"    SOAP-ENV:actor="http://gizmos.com/orders"/>    <ns:shippingDesk xmlns:ns="http://gizmos.com/NSURI"    SOAP-ENV:actor="http://gizmos.com/shipping"/>    <ns:confirmationDesk xmlns:ns="http://gizmos.com/NSURI"    SOAP-ENV:actor="http://gizmos.com/confirmations"    SOAP-ENV:mustUnderstand="1"/>    <ns:billingDesk xmlns:ns="http://gizmos.com/NSURI"    SOAP-ENV:actor="http://gizmos.com/billing"/>    </SOAP-ENV:Header><SOAP-ENV:Body/></SOAP-ENV:Envelope>    Header name is {http://gizmos.com/NSURI}orderDesk    Actor is http://gizmos.com/orders    mustUnderstand is false    Header name is {http://gizmos.com/NSURI}shippingDesk    Actor is http://gizmos.com/shipping    mustUnderstand is false    Header name is {http://gizmos.com/NSURI}confirmationDesk    Actor is http://gizmos.com/confirmations    mustUnderstand is true    Header name is {http://gizmos.com/NSURI}billingDesk    Actor is http://gizmos.com/billing    mustUnderstand is false

When you run HeaderExample to generate a SOAP 1.2 message, you will see output similar to the following:

   ----- Request Message ----    <env:Envelope    xmlns:env="http://www.w3.org/2003/05/soap-envelope">    <env:Header>    <ns:orderDesk xmlns:ns="http://gizmos.com/NSURI"    env:role="http://gizmos.com/orders"/>    <ns:shippingDesk xmlns:ns="http://gizmos.com/NSURI"    env:role="http://gizmos.com/shipping"/>    <ns:confirmationDesk xmlns:ns="http://gizmos.com/NSURI"    env:mustUnderstand="true"    env:role="http://gizmos.com/confirmations"/>    <ns:billingDesk xmlns:ns="http://gizmos.com/NSURI"    env:relay="true" env:role="http://gizmos.com/billing"/>    </env:Header><env:Body/></env:Envelope>    Header name is {http://gizmos.com/NSURI}orderDesk    Role is http://gizmos.com/orders    mustUnderstand is false    relay is false    Header name is {http://gizmos.com/NSURI}shippingDesk    Role is http://gizmos.com/shipping    mustUnderstand is false    relay is false    Header name is {http://gizmos.com/NSURI}confirmationDesk    Role is http://gizmos.com/confirmations    mustUnderstand is true    relay is false    Header name is {http://gizmos.com/NSURI}billingDesk    Role is http://gizmos.com/billing    mustUnderstand is false    relay is true

DOMExample.java and DOMSrcExample.java

The examples DOMExample.java and DOMSrcExample.java show how to add a DOM document to a message and then traverse its contents. They show two ways to do this:

DOMExample.java creates a DOM document and adds it to the body of a message.
DOMSrcExample.java creates the document, uses it to create a DOMSource object, and then sets the DOMSource object as the content of the message's SOAP part.

You will find the code for DOMExample and DOMSrcExample in the following directory:

   <INSTALL>/javaeetutorial5/examples/saaj/dom/src/

Examining DOMExample

DOMExample first creates a DOM document by parsing an XML document. The file it parses is one that you specify on the command line.

   static Document document;    ...      DocumentBuilderFactory factory =        DocumentBuilderFactory.newInstance();      factory.setNamespaceAware(true);      try {        DocumentBuilder builder = factory.newDocumentBuilder();        document = builder.parse( new File(args[0]) );        ...

Next, the example creates a SOAP message in the usual way. Then it adds the document to the message body:

   SOAPBodyElement docElement = body.addDocument(document);

This example does not change the content of the message. Instead, it displays the message content and then uses a recursive method, getContents, to traverse the element tree using SAAJ APIs and display the message contents in a readable form.

   public void getContents(Iterator iterator, String indent) {      while (iterator.hasNext()) {        Node node = (Node) iterator.next();        SOAPElement element = null;        Text text = null;        if (node instanceof SOAPElement) {          element = (SOAPElement)node;          QName name = element.getElementQName();          System.out.println(indent + "Name is " +            name.toString());          Iterator attrs = element.getAllAttributesAsQNames();          while (attrs.hasNext()){            QName attrName = (QName)attrs.next();            System.out.println(indent + " Attribute name is " +              attrName.toString());            System.out.println(indent + " Attribute value is " +              element.getAttributeValue(attrName));          }          Iterator iter2 = element.getChildElements();          getContents(iter2, indent + " ");       } else {          text = (Text) node;          String content = text.getValue();          System.out.println(indent +            "Content is: " + content);          }       }    }

Examining DOMSrcExample

DOMSrcExample differs from DOMExample in only a few ways. First, after it parses the document, DOMSrcExample uses the document to create a DOMSource object. This code is the same as that of DOMExample except for the last line:

   static DOMSource domSource;    ...    try {       DocumentBuilder builder = factory.newDocumentBuilder();       Document document = builder.parse(new File(args[0]));       domSource = new DOMSource(document);       ...

Then, after DOMSrcExample creates the message, it does not get the header and body and add the document to the body, as DOMExample does. Instead, DOMSrcExample gets the SOAP part and sets the DOMSource object as its content:

   // Create a message    SOAPMessage message = messageFactory.createMessage();    // Get the SOAP part and set its content to domSource    SOAPPart soapPart = message.getSOAPPart();    soapPart.setContent(domSource);

The example then uses the getContents method to obtain the contents of both the header (if it exists) and the body of the message.

The most important difference between these two examples is the kind of document you can use to create the message. Because DOMExample adds the document to the body of the SOAP message, you can use any valid XML file to create the document. But because DOMSrcExample makes the document the entire content of the message, the document must already be in the form of a valid SOAP message, and not just any XML document.

Building and Running DOMExample and DOMSrcExample

When you run DOMExample and DOMSrcExample, you can specify one of several sample XML files in the directory <INSTALL>/javaeetutorial5/examples/saaj/dom/:

domsrc1.xml, an example that has a SOAP header (the contents of the HeaderExample SOAP 1.1 output) and the body of a UDDI query
domsrc2.xml, an example of a reply to a UDDI query (sample output from the MyUddiPing example), but with spaces added for readability
uddimsg.xml, similar to domsrc2.xml except that it is only the body of the message and contains no spaces
slide.xml, another file that consists only of a body but that contains spaces

You can use any of these four files when you run DOMExample. You can use either domsrc1.xml or domsrc2.xml to run DOMSrcExample.

To build the programs using NetBeans 5.5, follow these steps:

1.	In NetBeans 5.5, choose Open Project from the File menu.
2.	In the Open Project dialog, navigate to `<INSTALL>/javaeetutorial5/examples/saaj/`.
3.	Select the `dom` folder.
4.	Select the Open as Main Project checkbox.
5.	Click Open Project Folder. A Reference Problems dialog appears. Click Close.
6.	Right-click the `dom` project and choose Resolve Reference Problems.
7.	In the Resolve Reference Problems dialog, select the first of the missing JAR files and click Resolve. The missing files are `activation.jar`, `javaee.jar`, and `appserv-ws.jar`.
8.	Navigate to the `<JAVAEE_HOME>/lib/` directory.
9.	Select the missing JAR file (`activation.jar`, for example) and click Open. In the Resolve Reference Problems dialog, all the files have green check marks to the left of their names.
10.	Click Close.
11.	Right-click the project and choose Build Project.

To run DOMExample using NetBeans 5.5, follow these steps:

1.	Right-click the `dom` project and choose Properties.
2.	Select Run from the Categories tree.
3.	Click Browse next to the Main Class field.
4.	In the Browse Main Classes dialog, select `DomExample`.
5.	Click Select Main Class.

6.	In the Arguments field, type the name of one of the four files: slide.xml
7.	Click OK.
8.	Right-click the project and choose Run Project.

To run DOMSrcExample using NetBeans 5.5, follow these steps:

1.	Right-click the `dom` project and choose Properties.
2.	Select Run from the Categories tree.
3.	Click Browse next to the Main Class field.
4.	In the Browse Main Classes dialog, select `DomSrcExample`.
5.	Click Select Main Class.
6.	In the Arguments field, type either `domsrc1.xml` or `domsrc2.xml`: domsrc1.xml
7.	Click OK.
8.	Right-click the project and choose Run Project.

To run the examples using Ant, go to the directory <INSTALL>/javaeetutorial5/examples/saaj/dom/.

To run DOMExample using Ant, use a command like the following:

   ant run-dom -Dxml-file=uddimsg.xml

To run DOMSrcExample using Ant, use a command like the following:

   ant run-domsrc -Dxml-file=domsrc2.xml

When you run DOMExample using the file uddimsg.xml, you will see output that begins like the following:

   Name is {urn:uddi-org:api_v2}businessList    Attribute name is generic    Attribute value is 2.0    Attribute name is operator    Attribute value is Sun Microsystems Inc.    Attribute name is truncated    Attribute value is false    Attribute name is xmlns    Attribute value is urn:uddi-org:api_v2    ...

When you run DOMSrcExample using the file domsrc2.xml, you will see output that begins like the following:

   Body contents:    Content is:    Name is {urn:uddi-org:api_v2}businessList     Attribute name is generic     Attribute value is 2.0     Attribute name is operator     Attribute value is Sun Microsystems Inc.     Attribute name is truncated     Attribute value is false     Attribute name is xmlns     Attribute value is urn:uddi-org:api_v2     ...

If you run DOMSrcExample with the file uddimsg.xml or slide.xml, you will see runtime errors.

Attachments.java

The example Attachments.java, based on the code fragments in the sections Creating an AttachmentPart Object and Adding Content (page 653) and Accessing an AttachmentPart Object (page 655), creates a message that has a text attachment and an image attachment. It then retrieves the contents of the attachments and prints the contents of the text attachment. You will find the code for Attachments in the following directory:

   <INSTALL>/javaeetutorial5/examples/saaj/attachments/src/

Attachments first creates a message in the usual way. It then creates an AttachmentPart for the text attachment:

   AttachmentPart attachment1 = message.createAttachmentPart();

After it reads input from a file into a string named stringContent, it sets the content of the attachment to the value of the string and the type to text/plain and also sets a content ID.

   attachment1.setContent(stringContent, "text/plain");    attachment1.setContentId("attached_text");

It then adds the attachment to the message:

   message.addAttachmentPart(attachment1);

The example uses a javax.activation.DataHandler object to hold a reference to the graphic that constitutes the second attachment. It creates this attachment using the form of the createAttachmentPart method that takes a DataHandler argument.

   // Create attachment part for image    URL url = new URL("file:///../xml-pic.jpg");    DataHandler dataHandler = new DataHandler(url);    AttachmentPart attachment2 =      message.createAttachmentPart(dataHandler);    attachment2.setContentId("attached_image");    message.addAttachmentPart(attachment2);

The example then retrieves the attachments from the message. It displays the contentId and contentType attributes of each attachment and the contents of the text attachment.

Building and Running Attachments

The Attachments example takes a text file as an argument. You can specify any text file. The attachments directory contains a file named addr.txt that you can use.

To build the program using NetBeans 5.5, follow these steps:

1.	In NetBeans 5.5, choose Open Project from the File menu.
2.	In the Open Project dialog, navigate to `<INSTALL>/javaeetutorial5/examples/saaj/`.
3.	Select the `attachments` folder.
4.	Select the Open as Main Project checkbox.
5.	Click Open Project Folder. A Reference Problems dialog appears. Click Close.
6.	Right-click the `attachments` project and choose Resolve Reference Problems.

7.	In the Resolve Reference Problems dialog, select the first of the missing JAR files and click Resolve. The missing files are `activation.jar`, `javaee.jar`, and `appserv-ws.jar`.
8.	Navigate to the `<JAVAEE_HOME>/lib/` directory.
9.	Select the missing JAR file (`activation.jar`, for example) and click Open. In the Resolve Reference Problems dialog, all the files have green check marks to the left of their names.
10.	Click Close.
11.	Right-click the project and choose Build Project.

To run the program using NetBeans 5.5, follow these steps:

1.	Right-click the `attachments` project and choose Properties.
2.	Select Run from the Categories tree.
3.	In the Arguments field, type the name of a text file: addr.txt
4.	Click OK.
5.	Right-click the project and choose Run Project.

To run Attachments using Ant, go to the directory <INSTALL>/javaeetutorial5/examples/saaj/attachments/. Use the following command:

   ant run-att -Dfile=path_name

Specify a text file as the path_name argument:

   ant run-att -Dfile=addr.txt

When you run Attachments using this file, you will see output like the following:

   Running Attachments.    Attachment attached_text has content type text/plain    Attachment contains:    Update address for Sunny Skies, Inc., to    10 Upbeat Street    Pleasant Grove, CA 95439    USA    Attachment attached_image has content type image/jpeg

SOAPFaultTest.java

The example SOAPFaultTest.java, based on the code fragments in the sections Creating and Populating a SOAPFault Object (page 663) and Retrieving Fault Information (page 665), creates a message that has a SOAPFault object. It then retrieves the contents of the SOAPFault object and prints them. You will find the code for SOAPFaultTest in the following directory:

   <INSTALL>/javaeetutorial5/examples/saaj/fault/src/

Like HeaderExample, the SOAPFaultTest example contains code that allows you to generate either a SOAP 1.1 or a SOAP 1.2 message.

Running SOAPFaultTest

To build the program using NetBeans 5.5, follow these steps:

1.	In NetBeans 5.5, choose Open Project from the File menu.
2.	In the Open Project dialog, navigate to `<INSTALL>/javaeetutorial5/examples/saaj/`.
3.	Select the `fault` folder.
4.	Select the Open as Main Project checkbox.
5.	Click Open Project Folder. A Reference Problems dialog appears. Click Close.
6.	Right-click the `fault` project and choose Resolve Reference Problems.
7.	In the Resolve Reference Problems dialog, select the first of the missing JAR files and click Resolve. The missing files are `activation.jar`, `javaee.jar`, and `appserv-ws.jar`.
8.	Navigate to the `<JAVAEE_HOME>/lib/` directory.
9.	Select the missing JAR file (`activation.jar`, for example) and click Open. In the Resolve Reference Problems dialog, all the files have green check marks to the left of their names.
10.	Click Close.
11.	Right-click the project and choose Build Project.

To run the program using NetBeans 5.5, follow these steps:

1.	Right-click the `fault` project and choose Properties.
2.	Select Run from the Categories tree.
3.	In the Arguments field, type the following: 1.1 This argument specifies the version of SOAP to be used in generating the message.
4.	Click OK.
5.	Right-click the project and choose Run Project.
6.	Right-click the project and choose Properties.
7.	Select Run from the Categories tree.
8.	In the Arguments field, type the following: 1.2
9.	Click OK.
10.	Right-click the project and choose Run Project.

To build and run SOAPFaultTest using Ant, go to the directory <INSTALL>/javaeetutorial5/examples/saaj/fault/. Use one of the following commands:

   ant run -Dsoap=1.1    ant run -Dsoap=1.2

When you run SOAPFaultTest to generate a SOAP 1.1 message, you will see output like the following (line breaks have been inserted in the message for readability):

   Here is what the XML message looks like:    <SOAP-ENV:Envelope    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">    <SOAP-ENV:Header/><SOAP-ENV:Body>    <SOAP-ENV:Fault><faultcode>SOAP-ENV:Client</faultcode>    <faultstring>Message does not have necessary info</faultstring>    <faultactor>http://gizmos.com/order</faultactor>    <detail>    <PO:order xmlns:PO="http://gizmos.com/orders/">    Quantity element does not have a value</PO:order>    <PO:confirmation xmlns:PO="http://gizmos.com/confirm">    Incomplete address: no zip code</PO:confirmation>    </detail></SOAP-ENV:Fault>    </SOAP-ENV:Body></SOAP-ENV:Envelope>    SOAP fault contains:     Fault code={http://schemas.xmlsoap.org/soap/envelope/}Client     Local name = Client     Namespace prefix = SOAP-ENV, bound to    http://schemas.xmlsoap.org/soap/envelope/     Fault string = Message does not have necessary info     Fault actor = http://gizmos.com/order     Detail entry = Quantity element does not have a value     Detail entry = Incomplete address: no zip code

When you run SOAPFaultTest to generate a SOAP 1.2 message, the output looks like this:

   Here is what the XML message looks like:    <env:Envelope    xmlns:env="http://www.w3.org/2003/05/soap-envelope">    <env:Header/><env:Body>    <env:Fault>    <env:Code><env:Value>env:Sender</env:Value></env:Code>    <env:Reason><env:Text xml:lang="en-US">    Message does not have necessary info    </env:Text></env:Reason>    <env:Role>http://gizmos.com/order</env:Role>    <env:Detail>    <PO:order xmlns:PO="http://gizmos.com/orders/">    Quantity element does not have a value</PO:order>    <PO:confirmation xmlns:PO="http://gizmos.com/confirm">    Incomplete address: no zip code</PO:confirmation>    </env:Detail></env:Fault>    </env:Body></env:Envelope>    SOAP fault contains:     Fault code = {http://www.w3.org/2003/05/soap-envelope}Sender     Local name = Sender     Namespace prefix = env, bound to    http://www.w3.org/2003/05/soap-envelope     Fault reason text = Message does not have necessary info     Fault role = http://gizmos.com/order     Detail entry = Quantity element does not have a value     Detail entry = Incomplete address: no zip code