Attachments feature in JAXRPC 1.1.2

  by Vivek Pandey


This white paper gives an overview of attachment support in JAXRPC 1.1.2. It describes the attachment technologies used and related concepts. For details on how to use JAXRPC SI to build interoperable endpoints with attachment support refer to Building interoperable Web Services with attachment support using JAXRPC 1.1.2

Why attachments?

There are several reasons for the necessity of attachments when carrying large amount of data, either binary or other XML documents. Some of the advantages of attachments include smaller message size, smaller memory requirements, smaller processing time (no need to convert binary data to base-64), and, most importantly, streaming.

Attachments allow applications to use appropriate APIs (such as the JavaBeans Activation Framework) to process data in a streaming fashion. This makes a big difference in performance, for example, when an image, BLOB etc. are shipped inside a SOAP Envelope.

JAXRPC 1.1.2 SI

JAXRPC SI 1.1.2 is the latest release from Sun. Its available through Java Web Services Developer Pack(JWSDP) 1.4. The new feature in this release is the support for building web services with interoperable attachments support.

Highlights of this feature

Attachments as described in JAXRPC 1.1 specification

According to JAX-RPC 1.1 specification an implementation is required to use SOAP Messages with Attachments (SwA) to support MIME encoded parameters or return types in a SOAP message. To describe the attachment in a WSDL it specifies use of WSDL1.1 MIME binding.

JAXRPC 1.1 specification also defines mapping of MIME type to Java Type.

MIME Type
Java 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

JAXRPC 1.1 specification defines the case when a part is bound to a MIME type not defined in Table-1 or if it is bound to alternate MIME types, it should be mapped to javax.activation.DataHandler.

WS-I Attachment Profile 1.0

WS-I Attachment Profile 1.0  or AP 1.0  profiles SwA and WSDL 1.1 MIME binding for building interoperable endpoints with attachments. JAXRPC 1.1.2 conforms to the requirements specified in AP 1.0 and produces conformant artifacts and SOAP messages along with its conformance to WS-I Basic Profile 1.1 and WS-I Simple SOAP Binding Profile 1.0.

Attachments support in JAXRPC SI

Previous versions of JAXRPC had limited attachment support. This support used SwA at runtime but did not have support for WSDL MIME binding. It only supported rpc-encoded WSDL.

JAXRPC 1.1.2 SI enables support for building web services endpoints for conveying interoperable SwA-based attachments using MIME binding defined in the WSDL document. SwA defines a MIME Multipart/Related structure for packaging attachments with SOAP messages. JAXRPC uses Java Activation Framework (JAF) together with SOAP with Attachments API for Java (SAAJ) internally to facilitate attachments serialization and de-serialization. It adds support for literal WSDLs (document-literal and rpc-literal). It also allows attachment referencing using swaRef mechanism defined in WS-I Attachment Profile 1.0.

Its important to note that the programming model is unchanged. There is no need to do anything special to turn on this feature. For example, to define an endpoint with attachments, one needs to start from a WSDL description, compile it using wscompile tool of jaxrpc. The wscompile tool will generate the artifacts along with the remote interface. The part bound to a MIME part is mapped as method parameter. At the runtime jaxrpc automatically serializes and de-serializes the java type to the  corresponding MIME type attachment and vice-versa.
    <wsdl:operation name="addPhoto">
<wsdl:input>
<mime:multipartRelated>
<mime:part>
<soap:body use="literal"/>
</mime:part>
<mime:part>
<mime:content part="photo" type="image/jpeg"/>
</mime:part>
</mime:multipartRelated>
</wsdl:input>

<wsdl:output>
<mime:multipartRelated>
<mime:part>
<soap:body use="literal"/>
</mime:part>
<mime:part>
<mime:content part="status" type="text/plain"/>
<mime:content part="status" type="text/xml"/>
</mime:part>
</mime:multipartRelated>
</wsdl:output>
</wsdl:operation>
The above wsdl fragment, shows binding for the abstract operation addPhoto. The request binding(wsdl:input element) defines no body parts and binds wsdl part photo to MIME type image/jpeg. According to this WSDL fragment and SwA the request SOAP message will be a MIME Multipart/Related structure with the SOAP envelope in the root MIME part and an attachment under MIME boundary with Content-Type "image/jpeg".

Similarly the response binding(wsdl:output element) defines no body parts and a wsdl part status with alternate MIME type bindings. According to this WSDL fragment the response SOAP message will be a MIME Multipart/Related structure with the SOAP envelope in the root MIME part and an attachment under MIME boundary with Content-Type of either "text/plain" or "text/xml".

When this WSDL is compiled using wscompile tool of JAXRPC, it will generate the following java method signature:
public javax.activation.DataHandler addPhoto(java.awt.Image photo)
throws java.rmi.RemoteException;
JAXRPC maps MIME type to java types according to the mapping defined in Table-1.  The wsdl:part photo of MIME type image/jpeg is mapped correctly to java.awt.Image. status part is bound to alternate MIME types and so is mapped to javax.activation.DataHandler. It makes sense because the response could be either of the MIME types and its not known until runtime.

JAXRPC through SAAJ provides the DataContentHandler for all the MIME types mentioned in Table-1. Any other MIME type will be mapped to javax.activation.DataHandler and the application is responsible for providing and registering the  DataContentHandler, so that it can be used by the JAXRPC runtime to serialize and de-serialize such attachments. For details refer to JavaBeans Activation Framework.

Here is the SOAP message generated by JAXRPC on invoking this method:
Content-type: multipart/related; type="text/xml"; 
boundary="----=_Part_0_29751107.1066869601955"



------=_Part_0_29751107.1066869601955
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:ns0="http://examples.com/PhotoCatalog/types">
<env:Body/>
</env:Envelope>

------=_Part_0_16671929.1086899437615
Content-Type: image/jpeg
Content-Id: <photo=2ca4872d-58ab-42bb-b23e-e194f809d0ca@jaxrpc.sun.com>

ÿØÿà JFIF    ÿÛ C  

2!!22222222222222222222222222222222222222222222222222ÿÀ  x d" ÿÄ   
------=_Part_0_16671929.1086899437615--
The root part carries the SOAP envelope. soap:body element is empty as there is no soap message defined in the wsdl for the request. The message carries image/jpeg attachment.

The response SOAP message returned by the endpoint with text/xml attachment:
Content-type: multipart/related; type="text/xml"; boundary="----=_Part_0_29751107.1066869601866"

------=_Part_0_29751107.1066869601866

Content-Type: text/xml; charset=utf-8
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:ns0="http://examples.com/PhotoCatalog/types"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<env:Body/>
</env:Envelope>

------=_Part_3_2145913.1086899437875

Content-Type: text/xml
Content-Id: <status=c940060e-fe83-46ab-9a6d-f856849ec7a3@jaxrpc.sun.com>

<?xml version="1.0" encoding="UTF-8"?>
<order>
<customerName>Java Duke</customerName>
<photoID>1340</photoID>
</order>
------=_Part_3_2145913.1086899437875--

Attachment Referencing using swaRef mechanism

JAXRPC maps attachments defined in the WSDL using MIME binging to the corresponding java type and  resolves them at runtime. Attachment Profile 1.0 requires an endpoint to support sending and receiving attachments that are not defined in the WSDL. AP 1.0  defines an XML data type swaRef to reference such attachments. AP 1.0 defines swaRef data type in namespace "http://ws-i.org/profiles/basic/1.1/xsd".


Please note that these properties are implementation specific and may change in the future version of JAXRPC SI. For details on how to use them. Refer Building interoperable Web Services with attachment support using JAXRPC 1.1.2. It demonstrates how these properties can be used to send/receive attachments from a client or server endpoint and resolve them using swaRef.

Limitations

There is no support for attachments when starting from Java. This is because for certain Java types to MIME type mapping METADATA support is needed. It will be supported in JAXRPC 2.0.

Other SOAP based attachment technology

XMLP WG is working on SOAP Message Transmission Optimization Mechanism or MTOM with respect to attachments for SOAP 1.2. Both (SwA and MTOM)use MIME. MTOM goes a step further by including attachments as part of the Infoset (since SOAP 1.2 is built around Infoset), thus making the SOAP 1.2 processing model applicable to the attachments as well. The messages on the wire in both cases will look very similar. MTOM is an evolutionary approach to attachment technology, similar to the transition from SOAP 1.1 to SOAP 1.2. MTOM is expected to be supported by JAXRPC 2.0 with SOAP 1.2 support.

About the Author

Vivek Pandey is a Staff Engineer with the Java Web Services group at Sun Microsystems. He focuses on the design and development of JAXRPC SI and represents Sun at WS-I Basic Profile Working Group. Vivek can be reached at Vivek.Pandey@Sun.COM.

References