Using Attachments to Represent XML Documents in a Service Interface

Sean Brydon,Smitha Kangath, Sameer Tyagi

Problem Description

When designing a web service interaction where a client and service exchange an XML document, developers need to choose a type to represent the XML document in the service interface. This decision has many impacts. The type chosen will be reflected in the WSDL file describing the service and also in the code of the service implementation. In Java[TM] 2 Platform, Enterprise Edition (J2EE[TM] platform) 1.4 applications, XML documents, such as purchase orders or invoices, are exchanged  using Java API for XML-based RPC (JAX-RPC).  There many strategies to consider for choosing a type to represent an XML document when designing a service interface: This solution focuses on the design considerations when choosing to use attachments to represent  XML documents in a document-oriented service. For a description of all these strategies, see the Document-Oriented Service entry.

Solution

Let's consider some of the issues when using attachments for XML documents being exchanged between a client and service. There are several ways to make a document being exchanged using attachments. These different ways are chosen by the type used to specify the attachment.

Strategy: Using Attachments to Package the XML Document

This strategy represents the XML business document as an attachment to the SOAP message. SOAP Messages with Attachments (SwA) defines how MIME Multipart/Related packages can be used to send binary data and other attachments with XML messages. Thus a SOAP message can actually contain one or more attachments using the MIME encoding, and is often referred to as compound message. Sending information in an attachment, rather than in  the SOAP message body, is quite efficient because smaller SOAP message bodies are processed faster and because the message contains only a reference to the data and not the data itself, it reduces the translation time in mapping the data to Java objects.

JAX-RPC uses the JavaBeans[TM] activation framework for dealing with SOAP attachments. When un-marshalling this message to Java, the JAX-RPC runtime can use two mapping techniques.

  1. It can map well-known mime types to Java objects as shown in Table 1 and vice versa using in-built DataHandlers and DataContentHandlers in the runtime.
  2. It can map the attachment to a javax.activation.DataHandler using the JavaBeans Activation framework and vice versa.

In simple terms, this means that if a method in a service endpoint uses a standard data type from Table 1, the runtime will map that to a MIME attachment in the SOAP message. When using the javax.activation.DataHandler, the content of the attachment can then be extracted using a getContent() on the DataHandler. If the content type is not understood by the installed DataContentHandler, it will return a java.io.InputStream object with the raw bytes.

MIME

Type

image/gif

java.awt.Image

image/jpeg

java.awt.Image

text/plain

java.lang.String

multipart/*

javax.mail.internet.MimeMultipart

text/xml or application/xml

javax.xml.transform.Source

Table 1: MIME Types to Java Data Type Mapping

One of the issues with attachments is that there is no standard way to specify the attachments in WSDL. Additionally, there was disagreement between vendors on the use of MIME packages external to the SOAP Envelope. This has been resolved to some extent by the WS-I Attachment Profile 1.0, which now defines interoperability requirements for attachment handling and is fully supported by the J2EE 1.4 SDK (and the  JWSDP 1.4). It is possible to build interoperable, WS-I conforming, attachment-based web services when starting from WSDL using the MIME bindings. WS-I Attachment Profile 1.0 also defines a new type "swaRef" to reference attachments type that can be used to process attachments not defined in the WSDL.

The example describes a service which is capable of receiving XML documents sent to it as attachments. The WSDL extract in Code Example 1 shows the MIME bindings.

<types>
   <schema xmlns="http://www.w3.org/2001/XMLSchema"    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
    xmlns:wsi="http://ws-i.org/profiles/basic/1.1/xsd" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    targetNamespace="urn:AttachmentPurchaseOrderService">
    <import namespace="http://ws-i.org/profiles/basic/1.1/xsd" schemaLocation="WS-ISwA.xsd"/>
    <element name="statusmessage" type="wsi:swaRef"/>
    <element name="InvalidPOException" type="string"/>
   </schema>
   </types>

    ...
   
    <message name="AttachmentPurchaseOrderServiceSEI_submitPO">
          <part name="attachment_1" type="xsd:hexBinary"/>
    </message>

    <message name="AttachmentPurchaseOrderServiceSEI_submitPOResponse">
        <part name="response" element="ns1:statusmessage"/>
    </message>
       
    <message name="InvalidPOException">
        <part name="InvalidPOException" element="ns1:InvalidPOException"/>
    </message>
    ...
    <portType name="AttachmentPurchaseOrderServiceSEI">
        <operation name="submitPO">
            <input message="tns:AttachmentPurchaseOrderServiceSEI_submitPO"/>
            <output message="tns:AttachmentPurchaseOrderServiceSEI_submitPOResponse"/>
                        <fault name="InvalidPOException" message="tns:InvalidPOException"/>
        </operation>
    </portType>
   
    <binding name="AttachmentPurchaseOrderServiceSEIBinding" type="tns:AttachmentPurchaseOrderServiceSEI">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="submitPO">
            <input>
                <mime:multipartRelated>       
                                        <mime:part>
                        <soap:body use="literal"/>
                    </mime:part>
                    <mime:part>
                        <mime:content part="attachment_1" type="text/xml"/>
                    </mime:part>
                </mime:multipartRelated>
            </input>
            <output>
                <mime:multipartRelated>
                    <mime:part>
                        <soap:body parts="response"  use="literal"/>
                    </mime:part>
                </mime:multipartRelated>
            </output>
                        <fault name="InvalidPOException">
                <soap:fault name="InvalidPOException" use="literal"/>
            </fault>
        </operation>
    </binding>

Code Example 1:  Snippet From the WSDL for the Service Using Attachments to Exchange XML Documents

The submitPO method generated in the service endpoint interface in Code Example 2 shows usage of the standard mappings for the input parameter as well as the WS-I Attachment Profile 1.0 implementation use with the swaRef data type as the return value. Note that the use of the attachment profile requires that the Java implementation class of this Java service interface must have application-server-specific properties set, and for the J2EE 1.4 SDK, those properties are the com.sun.xml.rpc.attachment.SetAttachmentContext and com.sun.xml.rpc.attachment.GetAttachmentContext respectively. The design document for the example application for usage of attachments has a more detailed example.

public interface AttachmentPurchaseOrderServiceSEI extends Remote {
    public URI submitPO(Source attachment_1) throws
        InvalidPOException, RemoteException;
}
Code Example 2:  The Service Endpoint Interface

Some of the disadvantages of this strategy of using attachments are potential compromise of interoperability. Not all toolkits support the Attachment Profile 1.0. The Attachment Profile 1.0 is not part of WS-I Basic Profile 1.0 but will be included in upcoming  versions of Basic Profile. In fact, MIME attachment support is currently not available on the .NET platform. Therefore, if you are designing Web services that need to be consumed by C# clients, the use of attachments is not a good choice for passing XML documents right now.

References

For more information about this topic, refer to the following:

© Sun Microsystems 2005. All of the material in The Java BluePrints Solutions Catalog is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.