Even though SOAP is an XML-based protocol, it's not always convenient to force all data which is passed as part of a SOAP message to be encoded in a way which can be embedded inside of an XML document. Sometimes it would be nicer just to allow data, such as JPEG images, WAV files, etc., to be passed along with the SOAP message, instead of inside of it. To address this issue, the SOAP Messages with Attachments specification was created. The SOAP Messages with Attachments specification allows for the embedding of a SOAP message inside of a MIME document, in a manner in which does not alter the processing rules of the message. The specification also describes how one refers to the attachments from inside the body of the SOAP message. Apache SOAP contains an implementation of this specification.
If you are interacting with an RPC-based service, you may not need to do anything special to transmit an attachment. Pre-defined serializers/deserializers exist for interacting with javax.activation.DataSource objects and javax.activation.DataHandler objects. If your objects can be passed through one of these mechanisms, then the RPC-code will handle creating and/or removing the attachment for you.
If you are using a message-oriented service, or need finer-grain control over the attachments, then you can use methods in the org.apache.soap.messaging.Message, org.apache.soap.rpc.Call, or org.apache.soap.rpc.Response classes. The addBodyPart(...) methods will allow you to add a javax.mail.internet.MimeBodyPart object to your messages, while the findBodyPart(...) and getBodyPart(...) methods will allow you to retrieve them via the Content-URI and location within the message, respectively.
As in the client case, if you are implementing an RPC-based service you may be able to take advantage of the built-in serializers/deserializers for the DataSource and DataHandler objects.
If you are implementing a message-oriented service, or need finer-grain control over the attachments, then you can use methods on the org.apache.soap.rpc.SOAPContext class to add or retrieve MimeBodyParts.
To make attachments really useful, you need to be able to refer to them from within the contents of a SOAP message body. To refer to an attachment from within a message, you simply add an element like the following:
<elemName href="cid:cid-uri">
where elemName is the name of some element within the message, and cid-uri is the URL-encoded name of the Content-ID for the attachment which you are referring to, or alternatively, an absolute or relative URI referring to the Content-Location of the attachment. (The Content-ID is set as part of the javax.mail.internet.MimeBodyPart.)
Last updated 5/23/2001 by Bill Nagy <nagy@watson.ibm.com>.