• javax.xml.soap

<soap:Envelope xmlns="http://xml.apache.org/axis/wsdd/"
    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
  <soap:Body>
    <myNS:PurchaseOrder xmlns:myNS="http://commerce.com/PO">
      <item>SK001</item>
      <quantity>1</quantity>
      <description>Sushi Knife</description>
    </myNS:PurchaseOrder>
  </soap:Body>
</soap:Envelope>

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <env:Fault>
     <env:Code>
       <env:Value>env:Sender</env:Value>
       <env:Subcode>
        <env:Value>rpc:BadArguments</env:Value>
       </env:Subcode>
     </env:Code>
     <env:Reason>
      <env:Text xml:lang="en-US">Processing error</env:Text>
      <env:Text xml:lang="cs">Chyba zpracování</env:Text>
     </env:Reason>
     <env:Detail>
      <e:myFaultDetails 
        xmlns:e="http://travelcompany.example.org/faults" >
        <e:message>Name does not match card number</e:message>
        <e:errorcode>999</e:errorcode>
      </e:myFaultDetails>
     </env:Detail>
   </env:Fault>
 </env:Body>
</env:Envelope>

• addAttribute(Name name, String value)
• addChildElement(Name name)
  
• // plus 4 more overloaded versions create elements with local or fully qualified names
• addNamespaceDeclaration(String prefix, String uri)
  
• addTextNode(String text)
• getAllAttributes( )
• getAttributeValue(Name name)
• getChildElements
• getChildElements(Name)
• getElementName( )
• getEncodingStyle( )
• getNamespacePrefixes( )
  
• getNamespaceURI(String prefix)
• getVisibleNamespacePrefixes( )
  
• removeAttribute(Name name)
• removeContents( )
• removeNamespaceDeclaration(String prefix)
• setEncodingStyle(String encodingStyle)
  

• A SOAPPart object
• A SOAPEnvelope object
• A SOAPHeader object
• A SOAPBody object
  

Since the header is an optional element that is supplied by default.
it may be removed if it is not being used for anything. The detachNode( )
method may be used to detach the header object from the underlying
tree data structure. 

The sample begins by getting a 'handle' to the SOAPBody object,
then creating a name that will be used as the XML indentifier for
for a SOAPBodyElement object. The SOAPBodyElement is added
to the SOAPBody object with the addBodyElement(  ) method.
The top-level SOAPBodyElement must have a fully qualified name.

Following is the sample that get's the SOAPBody, provides a fully-
qualified name for the SOAPBodyElement and adds this element
to the body using the addBodyElement( ) method.

Sun Java Web Services Tutorial Sample 1

Sun Java Web Services Tutorial Sample 3

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

When this XML code is sent as a SOAP message the
element will take it's place inside the message as is
shown in the following example.

Example

Sending SOAP Messages With SAAJ

The first objective of the SAAJ developers was to supply a Java API
for creating SOAP messages, leaving messaging to be handled by
Java APIs such as JAXM (Java API for XML Messaging).  SAAJ
does however supply a basic connection mechanism for request-
response messaging.

The process for sending a message using SAAJ is is simple and
elegant. First a connection is obtained, and a call is made on an
endpoint, sending the message in the process.

Following is the Factory pattern used to obtain a SOAPConnectionFactory
object which then is used to get a connection.

Formula for Getting a SOAPConnection Object

Once the endpoint URL has been encapsulated in the form of a Java URL
it and the message that was created earlier can serve as arguments to the
call( ) method, invoked on the SOAPConnection object. The SOAP response
is returned as a SOAPMessage object by the call( ) method.

Sending the SOAP Message  // need  import java.net.*; for URL class

URL endpoint =new URL("https://www-3.ibm.com/services/uddi/inquiryapi");
SOAPMessage response = connection.call(message, endpoint);

The connection should be closed when finished to release system resources.

Example     connection.close( );

We can let Sun put it all together for us after which we can build our
own

example using other techniques that SAAJ supplies.

Receiving a SOAP Message

The response that comes back from the call( )  method needs to be
unravelled in a manner similar to how the message has been put together.
The getSOAPBody( )  is called on the response message to obtain the
SOAPBody object. Child elements are returned to Iterator using
getChildElements(  ). An Iterator is a java.util class of undefined length
that can collect a variable length, set of objects. The Iterator class
supplies the hasNext( ) and next( ) methods that are used to return the
objects that are stored in the Iterator. Following is the typical form the
Iterator takes.

General Form of Taken to Access an Iterator

while(iterator.hasNext( )){
 Sometype typeObject  =  (SomeType) iterator.next( );
   // do something with typeObject
   }

Following is a sample from the Sun Java Web Service Tutorial that
shows the Iterator being used to capture SOAPBodyElements. The
Sun Java Web Services sample is built with the knowledge that
there is only one SOAPBodyElement, so they are able to omit
the while loop.

Sun Java Web Services Tutorial Sample

  Iterator iterator = soapBody.getChildElements(bodyName);
  SOAPBodyElement bodyElement =
                (SOAPBodyElement)iterator.next( );
 
           String lastPrice = bodyElement.getValue( );
            System.out.print("The last price for SUNW is ");
            System.out.println(lastPrice);

Sun's Java Web Service Tutorial's Request.java Example

Over what was discussed earlier, the code adds import statements, a main
method, and a try/catch block for exception handling. In order to run the
following code, the javax.xml.soap package has to be made available.

You can hard code the paths into your system or find the package in
your JWSDP directory using a -cp or -classpath switch at the command
line. Alternatively, just place the saaj jars into the <jdk_home>/jre/lib/ext
directory.

Sun Java Web Service Tutorial Example 

import javax.xml.soap.*;
import java.util.*;
import java.net.URL;

public class Request {
    public static void main(String[] args)  {
        try {
            SOAPConnectionFactory soapConnectionFactory =
                SOAPConnectionFactory.newInstance( );
            SOAPConnection connection =
                soapConnectionFactory.createConnection( );
            SOAPFactory soapFactory =
                SOAPFactory.newInstance( );

            MessageFactory factory =
                MessageFactory.newInstance( );
            SOAPMessage message = factory.createMessage( );

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

            Name bodyName = soapFactory.createName(
                "GetLastTradePrice", "m",
                "http://wombats.ztrade.com");
            SOAPBodyElement bodyElement =
                body.addBodyElement(bodyName);

            Name name = soapFactory.createName("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);
            SOAPBodyElement bodyElement2 =
                (SOAPBodyElement)iterator.next( );
            String lastPrice = bodyElement2.getValue( );
    // 2nd SOAPBodyElement name changed to remedy error report

            System.out.print("The last price for SUNW is ");
            System.out.println(lastPrice);

        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }
}

• getAllAttributes( )
• getAttributeValue(Name name)

• setActor(String actorURI)
• getActor( )  // returns actor URI
  
• setMustUnderstand(boolean mustUnderstand)
  
• getMustUnderstand // returns boolean

• Using Java API for XML Messaging' by Joe Attardi, Sun MicroSystems

• http://developers.sun.com/sw/building/tech_articles/api_xmlmessaging.html

<!DOCTYPE web-app PUBLIC 
 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd">

A Servlet Element Example 

A servlet-mapping Example  

 <servlet-mapping>
        <servlet-name>PassWordAgent</servlet-name>
        <url-pattern>/PassWordAgent</url-pattern>
    </servlet-mapping>

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE web-app
     	    PUBLIC "-//Sun Microsystems, Inc.//DTD
                Web Application 2.3//EN" 
    	    "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">

    <web-app>
    <servlet>
        <servlet-name>WeatherService</servlet-name>
        <servlet-class>WeatherService</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>WeatherService</servlet-name>
        <url-pattern>/weatherservice</url-pattern>
    </servlet-mapping>
    </web-app>