Java Web Services in a Nutshell

Using Attachments

In Chapter 3, you saw that SOAP messages can carry information either in the body part or in separate attachments. Typically, you would use an attachment when you need to include data of a type that cannot be placed in the SOAP body, which is restricted to valid XML. You might also use an attachment to carry plain text or an XML document or document fragment in cases where it would be difficult or inconvenient to embed it within the body part itself. Whereas SAAJ requires the use of a specific API to create SOAP messages with attachments, JAX-RPC transparently places the values of method arguments and return values with any of the following Java types into SOAP attachments:

• java.awt.Image

• javax.activation.DataHandler

• javax.mail.internet.MimeMultipart

• javax.xml.transform.Source

Arguments and return types that are arrays of these data types are handled by creating one attachment for each array entry.

Since JAX-RPC handles the creation of attachments transparently, neither the client nor the service implementation needs to be aware that some of the data they are exchanging may be carried in an attachment. This is far more convenient than the lower-level API provided by SAAJ, which requires the programmer to explicitly manage each attachment and to create references from the message body to any associated data in an attachment if necessary.

Warning

At the time of this writing, the reference implementation’s handling of attachments is such that it generates nonstandard ...