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.
Highlights of this feature
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 |
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.
<wsdl:operation name="addPhoto">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".
<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>
public javax.activation.DataHandler addPhoto(java.awt.Image photo)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.
throws java.rmi.RemoteException;
Content-type: multipart/related; type="text/xml";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.
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--
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--
The client side application or SEI impl will resolve the attachment referenced by the swaRef.
Client can not see MessageContext. To enable sending/receiving attachments from client JAXRPC defines these properties:
com.sun.xml.rpc.client.StubPropertyConstants.SET_ATTACHMENT_PROPERTY
StubPropertyConstants.SET_ATTACHMENT_PROPERTY
property should be used to set a java.util.Collection of
javax.xml.soap.AttachmentPart to the outgoing SOAPMessage request from
the client. Similarly StubPropertyConstants.GET_ATTACHMENT_PROPERTY
should be used to retrieve java.util.Collection of
javax.xml.soap.AttachmentPart from the incoming SOAPMessage response to
the client.
SEI impl is required to implement
ServiceLifecycle interface to get access to ServletEndpointContext.
From ServletEndpointContext it can access the MessageContext to receive
and send the collection of attachments using