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.
DataHandlers
and DataContentHandlers
in the runtime.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>
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.