MIME attachment proposal

[Wouter Cloetens <wc...@raleigh.ibm.com>]

Some time ago, I've implemented support for MIME attachments. I have
now found some 
time to bring my patches up to date with the current level of the
Apache-SOAP code, and 
finally resolve the final imcompatibility with the proposal by John
Barton and Sathish Thatte
(http://static.userland.com/weblogsCom/gems/soapweblogscom/soapMessagesW
ithAttachments.html).

This note describes the changes to the Apache-SOAP code. I'd like to
get this committed as part of the base code. I have some other changes
pending too (JSDK 2.1 support, performance enhancements, a WebSphere
3.5 install guide sent to me by someone) too, so I'd appreciate it if
someone could propose me as a committer. I'm already certifiable,
having me committed is a small step. <g>

Description:
The proposal documents the format. The SOAP envelope becomes a part of
a multipart 
document. The SOAP part still has content-type text/xml, the
content-type of the overall MIME document is multipart/related with a
boundary specifier. Transport-level headers remain outside of the
content.

Design:
This is a picture of what a SOAP message, embedded in a MIME multipart
envelope, roughly looks like:
+--------------------------------------------------
|transport headers
|Content-Type: multipart/related; boundary=....; start="<cid>"
|SOAPAction: "..."
| +---SOAP part------------------------------------
| |Content-Type: text/xml; charset=UTF-8
| |Content-ID: <cid>
| |Content-Length: xxx
| |other headers
| | +---SOAP envelope------------------------------
| | |<SOAP-ENV:Envelope...>
| | | +--SOAP header-------------------------------
| | | | ...
| | | +--------------------------------------------
| | | 
| | | +--SOAP body---------------------------------
| | | |... <elemname href="cid:attchcid"/> ...
| | | +--------------------------------------------
| | +----------------------------------------------
| +------------------------------------------------
|
| +---attachment-----------------------------------
| |Content-Type: something/something
| |Content-ID: <attchcid>
| |Content-Length: xxx
| |other headers
| | +---attachment content-------------------------
| | |...
| | +----------------------------------------------
| +------------------------------------------------
+--------------------------------------------------

So we find that, in the graph/tree representation of how things are
encapsulated, we no longer just have the message (call/response)
enveloping the SOAP envelope with the header and body below it, but
there's (optionally) an additional MIME multipart envelope, containing
body parts, of which the SOAP part is one.

This additional MIME envelope prompts for an additional object, holding
references to all the MIME parts. I've made it so that lnputStream
(java.io), DataSource, DataHandler (Java activation framework) or
MimeBodyPart (JavaMail) parameters or return types are transparently
added as parts, and serialised/deserialised by a MimePartSerializer. At
deserialisation, the DataHandler type is always chosen. There are
additional explicit hooks in the deserialisation process to intercept
elements with only a name and an href attribute. This will have to be
enhanced when we implement value references.

It should, however, also be possible for the client to add parts to the
request and read parts from the response, and the server-invoked
service should be able to add parts to the response and read parts from
the request. E.g. you might want to attach a digital signature or a
public key or something to a message, to which there is no reference
from the SOAP envelope.

This is very close to the functionality required by the SOAPContext
idea, where some meta-information about the request needs to be passed
to the service, and it needs to be able to set meta-information about
the response. So I decided to combine the two and have a SOAPContext
object embedded in the RPCMessage class (superclass of both Call and
Response). It's now ready for a future enhancement where request and
response SOAPContexts (note that there are two, like in a servlet's
service() method - a single SOAPContext won't do the trick) are passed
to an implementing service, if it is detected to support that (e.g.
method signature or interface implementation detection). For ease of
use, I also have methods to interact with the MIME attachments directly
in RPCMessage (and thus Call and Response), not only in SOAPContext.

I currently have two versions. The first tries to minimise the changes,
the second has very pervasive modifications. This is mostly due to the
need to propagate the SOAPContext through the marshall and unmarshall
process.
The first version has a kludge implemented to avoid changing so many
method signatures. It associates the SOAPContext with the running
thread (assuming the SOAP message will only be handled in a single
thread on the client and server side).

Additional requirements:
The current version requires mail.jar
(http://java.sun.com/products/javamail/, 220KB) and activation.jar
(http://java.sun.com/products/beans/glasgow/jaf.html, 44KB). It has
been pointed out that people aren't too happy with the need to include
mail.jar, but it would be very hard to eliminate that dependency.

I'm still working on the last changes to my code. I will post diffs and
jar files for both implementations on the web page at the URL in my
signature over the next couple of days, but I though I'd post this
document in advance so I can get some feedback.

bfn, Wouter
--
http://www.workspot.net/~zombie/soap/
My opinions are irrelevant. They will be assimilated by my employer.