SOAP, the Simple Object Access Protocol, is an evolving W3C standard. Developed by IBM, Microsoft, DevelopMentor, and UserLand Software for the exchange of information over a network, SOAP stands at the point where three technologies -- Remote Procedure Call (RPC), XML, and Web applications -- are converging. The combination is new so developers are still learning how to deploy it most effectively. In most first-generation applications, SOAP is a replacement for another RPC standard such as RMI or CORBA. But as this tip illustrates, SOAP can offer more.

Intranet and Internet services

Who develops the clients and the servers is determined by whether they're being deployed on an intranet or on the Internet. On an intranet, the developers for the client and server are either on the same team or are on teams that are closely related. This translates into very strong ties between the client and server.

When it comes to the Internet, things are different. The client and server are often developed by different companies altogether. As a result, they won't have as many opportunities to synchronize their work. To make things worse, if the service is successful, multiple clients and servers will implement it.

As an example, consider the Google search engine (see Resources), a service that benefits many applications interfacing with it. For instance, I use an XML editor to write my articles. When I research a topic, I find it convenient to run searches directly from the editor. Likewise for e-mail -- it's common to search for a contact address on a corporate Web site. The search often starts with Google, so my address book also benefits from implementing the service. And what about a photo editor? It's common to search for background information on a subject or to search for new techniques, so the photo editor could interface with Google. That's three possible clients for the service already -- and Google is not the only search engine, so you could have more than one server implementation as well.

Since the client and server are developed independently, the definition of the service interface is very important. The service interface (not unlike an API) is the basis for cooperation between the two teams. It specifies the roles of the client and the server -- the methods and their parameters. The interface must be flexible, modular, and extensible.

To encourage modularity and extensibility, SOAP organizes its requests into two parts: the header and the body. The header is typically used for technical parameters of the request such as session management, authentication, and transaction, while the body contains the actual request.

Back to top

Header elements in AXIS

To illustrate how to implement header extensions, I'll use AXIS, the Apache SOAP toolkit. The sample service is trivial: It adds up two integers. The service interface has only one method, add(), which takes two integers as parameters.

Imagine that the server can prioritize requests: High priority requests will get a faster answer than low priority ones. How do you extend the service interface? While you could extend the add() method with a third priority parameter, it's not a good idea, primarily because doing so breaks existing clients and servers. In addition, it pollutes the interface with a technical parameter. Not every server is able to honour the priority, and not every client has a notion of priority. A better solution is to move the technical parameter to the header, where it belongs.

Listing 1 is a SOAP server that recognizes a priority header element. The service uses the MessageContext object to retrieve an instance of a Message object that represents the request. Next, it searches for a priority element in the header. The service sleeps for more or less time, depending on the priority (sleeping emulates low priority requests in this example). Note that the service accepts requests with no priority. Finally it sets the processed flag so AXIS knows the element has been dealt with (this flag is essential if the element has a mustUnderstand attribute). The server is compatible with those clients that do not implement the priority mechanism.

                
import java.util.*;
import org.apache.axis.*;
import org.apache.axis.message.*;

public class HeaderService
{
   public int add(int op1, int op2)
      throws Exception
   {
      MessageContext context = MessageContext.getCurrentContext();
      Message message = context.getRequestMessage();
      SOAPEnvelope envelope = message.getSOAPEnvelope();
      SOAPHeaderElement element =
         envelope.getHeaderByName("http://psol.com/2003/tips/header",
                                  "priority");
      if(element != null)
      {
         Integer priority =
            (Integer)element.getValueAsType(Constants.XSD_INT);
         // lower priority requests are delayed to simulate priorities
         switch(priority.intValue())
         {
            case 0:
               Thread.sleep(40000);
               break;
            case 1:
               Thread.sleep(30000);
               break;
            case 2:
               Thread.sleep(20000);
               break;
            case 3:
               Thread.sleep(10000);
               break;
            case 4:
               Thread.sleep(5000);
               break;
            default:
               // top speed, no sleeping
               break;
         }
         element.setProcessed(true);
      }
      else
         // unless the service requests a priority, it runs very low
         Thread.sleep(50000);
      return op1 + op2;
   }
}

Listing 2 is the client. If a priority argument is in the command line, it creates a SOAPHeaderElement object and passes it to the Call object. Again, this client is compatible with servers that do not implement the priority mechanism.

                
import java.net.*;
import org.apache.axis.client.*;
import org.apache.axis.message.*;
import org.apache.axis.encoding.*;
import javax.xml.rpc.ParameterMode;

public class HeaderClient
{
   public static void main(String [] args)
   {
      if(args.length < 2)
      {
         System.out.println("HeaderClient op1 op2 [-priority:0-5]");
         return;
      }
      try
      {
         Integer op1 = new Integer(args[0]),
                 op2 = new Integer(args[1]);
         URL endpoint =
            new URL("http://localhost:8080/axis/HeaderService.jws");
         Service service = new Service();
         Call call = (Call)service.createCall();
         call.setTargetEndpointAddress(endpoint);
         call.setOperationName("add");
         call.addParameter("op1",XMLType.XSD_INT,ParameterMode.IN);
         call.addParameter("op2",XMLType.XSD_INT,ParameterMode.IN);
         call.setReturnType(XMLType.XSD_INT);
         if(args.length > 2 && args[2].startsWith("-priority:"))
         {
            Integer priority = new Integer(args[2].substring(10));
            if(priority.intValue() < 0 || priority.intValue() > 5)
               priority = new Integer(3);
            SOAPHeaderElement element =
               new SOAPHeaderElement("http://psol.com/2003/tips/header",
                                     "priority");
            element.setObjectValue(priority);
            call.addHeader(element);
            System.out.println("Request priority = " + priority);
         }
         else
            System.out.println("No priority set for request");
         Integer result = (Integer)call.invoke(new Object[] { op1, op2 });
         System.out.println(op1 + " + " + op2 + " = " + result);
      }
      catch (Exception x)
      {
         System.err.println(x.toString());
      }
   }
}

Back to top

Conclusion

SOAP promotes the design of modular and extensible service interfaces through the header element. While this tip demonstrates how to build premium services (faster response) on top of a regular service interface, the technique also applies to other technical parameters.

Resources

• Participate in the discussion forum for Benoit Marchal's Working XML column.
  
  
• Download the source code used in this article.
  
  
• Read "A lightweight XML client," in which Benoit Marchal presents a lightweight client to interface with SOAP services (developerWorks, September 2003).
  
  
• Learn the basic concepts behind SOAP in Dan Gisolfi's article "Web services architect" (developerWorks, April 2001).
  
  
• Catch "Myths and misunderstandings surrounding SOAP" as Frank Cohen debunks some of the myths surrounding SOAP (developerWorks, September 2001).
  
  
• Use SOAP to access the popular Google search engine with the Google Web API. It's one example of a Web service that many applications can use.
  
  
• Check out the directory of publicly available SOAP services on XMethods.
  
  
• Download the AXIS toolkit used in this article from ws.apache.org/axis. It is based on work initially done by IBM.
  
  
• SOAP 1.2 is now an official W3C Recommendation.
  
  
• Find more XML and Web services resources on the developerWorks XML and Web services zones. For a complete list of XML tips to date, check out the tips summary page.
  
  
• Find out how you can become an IBM Certified Developer in XML and related technologies.
  
  

About the author

Benoit Marchal is a Belgian consultant. He is the author of XML by Example, Second Edition and other XML books. Benoit is available to help you with XML projects. You can contact him at bmarchal@pineapplesoft.com or through his personal site at marchal.com.

Rate this article

Comments

Back to top

Table of contents

• Intranet and Internet services
• Header elements in AXIS
• Conclusion
• Resources
• About the author
• Comments