Introduction

Many document-style web services have to be able to process complex XML documents. An XML document might contain a large number of data elements that often have many nested fragments and repeating groups.

One particular situation that leads to the use of large documents is when multiple requests are bundled together and sent to a service in one shot. This scenario has not been covered in detail by respected sources in the field; however, it is not as uncommon as it might seem. In many situations, a client's system is schedule-driven and many records have to be processed within a limited amount of time, such as during the payroll processing cycle. Also, web services are often put in place to replace batch file-based interfaces (for example, legacy). In this situation, a web service that can handle batches of XML documents can provide a transition path to clients who are unable or unwilling to overhaul their systems to support a message-based approach required by proper web services.

Batching XML documents together is an effective performance booster. There is a substantial degree of overhead associated with invoking a web service. Web services clients have to create a Simple Object Access Protocol (SOAP) envelope, open a connection (many SOAP clients create a new connection for every call), and transmit the message. A server has to parse the SOAP envelope, perform message decryption, and authentication. Hypertext Transfer Protocol (HTTP) and Secure Sockets Layer (SSL) handshake overhead also adds to the invocation time. The performance improves when the overhead is spread over multiple requests, as opposed to being incurred for each individual one.

Fast processing of complex XML documents

So how can you implement a web service that can efficiently handle large and complex messages that could potentially contain multiple business requests bundled together?

The key is to divide a large message into several logical fragments and decide what fragments can be processed concurrently. This means that you want to start processing a fragment without having to wait for the parsing of the entire message to finish.

When multiple requests are bundled together in a single message, each individual request represents an independent fragment that can be processed in parallel with other requests.

The same technique also works for a single (unbundled) complex message. A complex message typically consists of several logical fragments involving repeating groups. An element, which is part of the repeating group, could be a good candidate for being processed concurrently.

Let's consider a simple XML purchase order, as shown in Listing 1 below -- this is a classic XML document used in the World Wide Web Consortium (W3C) XML Schema Primer.

				

<?xml version="1.0"?>

<orders>

    <purchaseOrder orderID="111" orderDate="1999-10-20">

       <shipTo country="US">

          <name>Alice Smith</name>

          <street>123 Maple Street</street>

          <city>Mill Valley</city>

          <state>CA</state>

          <zip>90952</zip>

       </shipTo>

       <billTo country="US">

          <name>Robert Smith</name>

          <street>8 Oak Avenue</street>

          <city>Old Town</city>

          <state>PA</state>

          <zip>95819</zip>

       </billTo>

       <comment>Hurry, my lawn is going wild</comment>



       <items>

          <item partNum="872-AA">

             <productName>Lawnmower</productName>

             <quantity>1</quantity>

             <USPrice>148.95</USPrice>

             <comment>Confirm this is electric</comment>

          </item>

          <item partNum="926-AA">

             <productName>Baby Monitor</productName>

             <quantity>1</quantity>

             <USPrice>39.98</USPrice>

             <shipDate>1999-05-21</shipDate>

          </item>

       </items>

    </purchaseOrder>



    <purchaseOrder orderID="999" orderDate="2001-10-20">

        <shipTo country="US">

          <name>John Doe</name>

          <street>123 Main Street</street>

          <city>Mill Valley</city>

          <state>CA</state>

          <zip>90952</zip>

       </shipTo>

       <items>

          <item partNum="999-BB">

             <productName>Chainsaw</productName>

             <quantity>1</quantity>

             <USPrice>250.00</USPrice>

          </item>

       </items>

    </purchaseOrder>

</orders>

The first part of the purchase order contains shipping and billing information. The web service might need to save this information in a database, for example, in the customer table.

The second part contains order line items. The web service must check the inventory when processing each line item. It can also process all the line items concurrently -- the inventory check does not depend on processing shipping and billing information, and line items do not depend on each other. The web service can start processing a line item once it's reached the closing </item> tag for each item. However, you need to make sure you can still correlate the line item with the purchase order header. This can be accomplished by adding the orderID attribute to each line item XML fragment. Listing 2 shows a complete XML line item with the added orderID attribute.

				

<?xml version="1.0"?>

<item partNum="872-AA" orderID="111">

   <productName>Lawnmower</productName>

   <quantity>1</quantity>

   <USPrice>148.95</USPrice>

   <comment>Confirm this is electric</comment>

</item>

In other words, the web service needs to be able to concurrently process the customer's shipping and billing information as well as all line items.

The easiest way to accomplish this is to leverage the Java™ Message Service (JMS) support built into the Java 2 Platform, Enterprise Edition (J2EE) specification. The added benefit of JMS is that it allows you to fully decouple message producers and consumers so that the consumers can process messages at their own pace. If you need to scale up your service, just add more message consumers -- this can be done by adding more application server instances.

The parsing logic sends each XML fragment, which will be converted into a well-formed XML document, to a JMS destination as soon as the parser reaches the end of a fragment.

You need to create JMS queues for line items and purchase order headers with shipping information. Back-end consumers pick up messages from these queues and execute the necessary business logic.

You also have to implement the getStatus operation so that the clients can poll it to find out the status of their orders. Alternatively, you can use WS-Addressing (see Resources) for notifying clients when the order is processed, assuming that your clients can support the WS-Addressing specification.

Coordinating the concurrent processing of fragments for each order requires some effort. In order to arrange for shipping, you'll need to know when all line items are processed. This requires using a persistent state for each order. For example, you can store each processed fragment ID in the database and check the order for completeness every time a new fragment is processed. Since you're using JMS, the messages can arrive out of order -- so when a line item is processed before the order header, it is handled correctly. Note that implementing this logic is beyond the scope of this article.

Back to top

Streaming XML parsing

I've already established that you have to be able to start processing XML fragments while the entire XML document is still being parsed. This approach calls for the use of a streaming parsing API. You have a choice of two different streaming APIs: Simple API for XML (SAX) and Pull. The SAX API is one of the oldest XML parsing APIs and it is part of almost any XML parser. The pull-parsing API is more recent; however, it has already been standardized into the "JSR 173: Streaming API for XML (StAX)" specification (see Resources).

Both APIs have their pros and cons (see Resources). In general, StAX is somewhat easier to use. The biggest advantage of StAX is that, unlike SAX, it is bi-directional, which means that you can use it to create XML documents. This makes StAX more suitable for XML transformation and conversion tasks.

StAX, being a simple API, should have good performance -- although this really depends on the implementation of the StAX specification. A benchmark published in the "XML Documents on the Run" article (see Resources) supports this theory, although this benchmark predates the release of the StAX specification. Another recent benchmark test also fares a particular StAX implementation above the competitors. Nevertheless, while superior StAX performance might be an important criteria, you should not choose the parsing API strictly based on the results of the performance benchmarks.

Let's look at the purchase order with line items example. In this case, StAX is a very good choice, because you need to transform the complex incoming XML document into more granular documents using straightforward transformation logic.

Listing 3 shows the code that parses the XML purchase order using StAX and converts the message's fragments into smaller XML documents.

				

//create the XMLEventReader, pass the filename for any relative resolution

XMLEventReader xmlEventReader = 

   XMLInputFactory.newInstance().createXMLEventReader( purchaseOrderInputStream );



StringWriter stringWriter = new StringWriter();

XMLEventWriter xmlEventWriter = 

    XMLOutputFactory.newInstance().createXMLEventWriter( stringWriter );



/* Create purchaseOrder closing tag ahead of time - we will need to 

 * close the purchaseOrder document before we encounter the real closing tag.

 */

XMLEventFactory xmlEventFactory = XMLEventFactory.newInstance();

EndElement endPurchaseOrder = xmlEventFactory.createEndElement( 

        new QName("purchaseOrder"), null);



Attribute orderIdAttr = null;



while(xmlEventReader.hasNext()) {



    XMLEvent e = xmlEventReader.nextEvent();

    

    /* figure out the name of the element - unfortunately,

     * there is no common Element even supertype in stax,  

     * so we need to check for start and end elements separately

     */

    String eltName = "";

    StartElement startElt = null;

    if ( e.isStartElement() ) {

       startElt = ((StartElement)e);

       eltName = startElt.getName().getLocalPart();

    }

    else if ( e.isEndElement() ) {

        eltName = ((EndElement)e).getName().getLocalPart();

    }

    

    // preserve purchase order ID so we can add it later to each item 

    if (e.isStartElement() && "purchaseOrder".equals( eltName ) ) {

       orderIdAttr = startElt.getAttributeByName( new QName("orderID") );

       if (orderIdAttr == null )

       throw new XMLStreamException( "Missing orderID attribute", e.getLocation());

    }

    

    /*"items" start tag means that the order-related information

     * has been already parsed, so we can send the order 

     * without any items for processing

     */

    if (e.isStartElement() && "items".equals( eltName ) ) {

        xmlEventWriter.add( endPurchaseOrder );         

        sendMessage( stringWriter, "jms/poQueue" );

    }

    

    /* Since we're sending each item separately, we

     * need to ignore "items" start and end tags.

     * Purchase order is sent when the first item is encountered,

     * so we have to ignore the purchase order end tag as well.

     */

    if (!eltName.equals("items") && !eltName.equals("orders") &&

          (!e.isEndElement() || !eltName.equals("purchaseOrder") )) {

        xmlEventWriter.add( e );    

    }



    // for each new item, add orderId attribute with the current orderId 

    if (e.isStartElement() && "item".equals( eltName ) ) {

        xmlEventWriter.add( orderIdAttr ); 

    }

    

    // send each item as an independent message

    if (e.isEndElement() && "item".equals( eltName ) ) {

       sendMessage( stringWriter, "jms/itemQueue" );

    }

}

Back to top

Implementing the web service using JAX-RPC

So how are you going to embed a complex, and potentially large, XML document into a SOAP message in order to parse it on a server using StAX?

Java APIs for the XML-Based Remote Procedure Call (JAX-RPC) specification does provide some support for document-style web services (services that use literal SOAP binding in a Web Services Description Language (WSDL)). When an XML document is received, JAX-RPC implementations convert the entire document into a Java object graph, such as a SOAPElement object or a generated SOAPElement wrapper. Alternatively, you can choose to use String in the SOAP body -- the entire XML document will be loaded into a String object as text, which can then be parsed using any XML API. Please refer to the "Patterns and Strategies for Building Document-Based Web Services" article (see Resources) for the detailed analysis of all of the alternatives. Unfortunately, none of these options give you a clean way of accessing the input stream of the message payload before it was fully parsed by the SOAP server (for example, the SOAP server will attempt to load the entire document into a String object before your service can get access to it). Note that the upcoming JAX-WS 2.0 specification aims to fix this issue, but the specification is still in the proposed final draft stage at the time of this writing.

The JAX-RPC specification also supports another approach. This approach involves using SOAP Messages with Attachments (SwA). SwA relies on a well-known Multipurpose Internet Mail Extensions (MIME) multipart protocol. This protocol is extremely simple. In SwA, the first part of the message contains the SOAP envelope and the subsequent parts contain binary attachments. In this example, you'll only have two parts, one for the envelope and one for the XML document. At first, a choice of SwA for passing XML documents might seem unjustified, because the main purpose of this specification is to provide a mechanism for transferring binary data as part of the SOAP message. However, upon closer analysis, SwA does appear to meet the needs for passing large and complex business XML documents.

First, SwA completely decouples the business XML document from the SOAP envelope. The business document might contain entities, use encoding other than UTF-8, or refer to Document Type Definition (DTD) -- in fact, many industry-specific information exchange standards still use DTD, such as the Mortgage Industry Standards Maintenance Organization (MISMO) standard. In other words, the business XML document might have its own prolog, which is independent of the prolog and declarations of the SOAP envelope (see the link to "Transporting Binary Data in SOAP" in the Resources section for a detailed discussion of the potential problems with XML embedding).

Secondly, JAX-RPC supports SwA in such a way that allows you to easily obtain access to the input stream of the document that is passed as an attachment. For example, you can use javax.activation.DataHandler as a parameter type in the service's method signature:

public void process(DataHandler purchaseOrder)

The javax.activation.DataHandler provides access to the java.io.InputStream by using the getInputStream()method.

JAX-RPC also supports mapping of text/XML and application/XML MIME types. These types map to javax.xml.transform.Source. Unfortunately, the javax.xml.transform.Source interface is not stream-aware. To get to the input stream, you would have to cast it to one of the classes implementing this interface, for example, javax.xml.transform.stream.StreamSource. But the JAX-RPC specification does not restrict implementers to any particular class, so this downcast might not be portable -- it did work in Apache Axis, but I did not test it with any other SOAP server.

So using javax.activation.DataHandler as a parameter type seems to be a better choice, especially since it does not restrict clients to any particular MIME type (for example, a client might decide to pass an XML document using text and / or plain type).
Listing 4 shows the code of the web service that uses DataHandler in its signature:

				

public class PurchaseOrderProcessor {



    public void process( DataHandler purchaseOrder ) 

        throws XMLStreamException, IOException {



        processPurchaseOrderXML( purchaseOrder.getInputStream());

    }

    

    void processPurchaseOrderXML( InputStream purchaseOrderInputStream ) 

       throws XMLStreamException {

       // See the code from Listing 3...

    }

}

Back to top

Drawbacks of SwA

The main downside of SwA is that it is not directly supported by .NET-based clients. Microsoft® used to favor the alternative specification called WS-Attachment, which is based on Direct Internet Message Encapsulation (DIME) instead of MIME. Later on, Microsoft decided to standardize the Message Transmission Optimization Mechanism (MTOM) specification, which is MIME-based.

As a result, the SwA approach might not be appropriate for web services where interoperability based on the WS-I Basic Profile 1.0 is required (SwA is not part of the WS-I Basic Profile; instead, it is part of a separate "Attachment profile"). However, in the majority of cases, web services today are used for integrating systems involving business and trading partners or for interdepartmental integration. In this case, all partners should agree that a single standard and SwA is a good candidate for being chosen because of its simplicity and maturity.

Partners using Microsoft technologies can interoperate with SwA-based partners by relying on add-on libraries, such as "AlotSoft SOAP extension" (see Resources), that add SwA support to the Microsoft platform.

Another problem with SwA is that it does not support an XML Information Set-based (Infoset-based) representation of a SOAP message. The SwA message consists of several parts -- some potentially containing binary data. This makes it impossible to cleanly convert the entire message into XML. The detailed analysis of this issue is beyond the scope of this article; however, you can refer to the "XML, SOAP and Binary Data" whitepaper (see Resources) for more information. I'm only going to mention that SwA makes it difficult using digital signatures and WS-Security, which is not an issue if transport-level security, such as HTTPS, is used.

The MTOM specification, which has already been approved by W3C, provides a solution to this problem. MTOM defines the Infoset inclusion mechanism, which allows for easy deserialization of the entire message into XML form. MTOM is already supported by Microsoft as part of "Web Services Enhancement (WSE 3.0)" add-on for .NET. MTOM is also currently supported by Apache Axis2 and Sun's JAX-WS RI 2.0. You can expect other vendors to add the MTOM support in the near future (see Resources). The fact that MTOM uses MIME encoding provides for an easy transition path for web services that currently rely on SwA.

Back to top

Conclusion

JAX-RPC provides a number of ways for implementing document-style web services; however, most of these options have serious tradeoffs when it comes to dealing with large and complex XML documents.

In this article, I explained one technique that you can use to implement a document-style web service using JAX-RPC. This technique relies on the use of a StAX streaming parser and SwA. From my experience, this technique has good performance characteristics and can deal with messages of any size.

I also explained the drawbacks of SwA. I think that these drawbacks are not significant unless adherence to the WS-I Basic Profile and / or support for WS-Security are required.

The technique I presented is not suitable for simple XML messages or when performance requirements are not very demanding. An approach relying on parallel processing, such as the one described in this article, always requires extra effort on the developer's side. However, I think that this effort is well justified under the right circumstances.

Resources

Learn

• Read the following specifications:
  • WS-Addressing specification
  • Streaming API for XML (StAX) Specification (JSR 173)
  • SOAP Messages with Attachments specification
  • SOAP Message Transmission Optimization Mechanism (MTOM)
  • JAX-WS 2.0
  
  
• The Java Web Services Developer Pack tutorial compares StAX with other XML parsing APIs.
  
  
• Does StAX Belong in Your Toolbox by Jeff Ryan provides another high-level XML parsing API comparison.
  
  
• XML documents on the run by Dennis M. Sosnoski contains benchmarks of various parsers, including the pull parser that predated StAX.
  
  
• Japex Report: Parsing Performance by Santiago Pericas-Geertsen benchmarks the latest Sun Microsystem's StAX parser.
  
  
• Patterns and Strategies for Building Document-Based Web Services by Sameer Tyagi details all options available in JAX-RPC for directly accessing an XML payload of a SOAP message.
  
  
• Mortgage Industry Standards Maintenance Organization (MISMO) provides an example of XML-based exchange standard that still relies on DTD.
  
  
• Read DIME: Sending Binary Data with Your SOAP Messages by Matt Powell to learn more about DIME.
  
  
• Transporting Binary Data in SOAP by Rich Salz explains the potential problems with embedding XML inside SOAP.
  
  
• XML, SOAP, and Binary Data provides detailed analysis of SwA and XML Infoset issue.
  
  
• SOA and web services -- hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop web services applications.
  
  
• The IBM developerWorks team hosts hundreds of technical briefings around the world which you can attend at no charge.
  
  

Get products and technologies

• AlotSoft SOAP extension adds SwA support to .NET platform.
  
  
• Recently released Web Services Enhancement (WSE 3.0) add-on for .NET provides MTOM support.
  
  
• Apache Axis2 is the next version of the popular Apache Axis SOAP server.
  
  
• JAX-WS RI 2.0 is the reference implementation of the JAX-WS 2.0 specification.
  
  
• Get your hands on application development tools and middleware products from DB2®, Lotus®, Rational, Tivoli®, and WebSphere®. You can download evaluation versions of the products at no charge, or select the Linux® or Windows® version of developerWorks' Software Evaluation Kit.
  
  

Discuss

• Participate in developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Fast processing of complex XML documents
• Streaming XML parsing
• Implementing the web service using JAX-RPC
• Drawbacks of SwA
• Conclusion
• Resources
• About the author
• Comments