SOAPPart | Java Web Services in a Nutshell

SOAPMessage

javax.xml.soap

SAAJ 1.1; JWSDP 1.0, J2EE 1.4

 public abstract class SOAPMessage {  // Public Constructors  public SOAPMessage(  );  // Property Accessor Methods (by property name)  public abstract Iterator getAttachments(  );      public abstract Iterator getAttachments MimeHeaders   headers   );      public abstract String getContentDescription(  );      public abstract void setContentDescription(String   description   );      public abstract MimeHeaders getMimeHeaders(  );      public abstract SOAPPart getSOAPPart(  );  // Public Instance Methods  public abstract void addAttachmentPart(AttachmentPart   AttachmentPart   );      public abstract int countAttachments(  );      public abstract AttachmentPart createAttachmentPart(  );      public AttachmentPart createAttachmentPart(javax.activation.DataHandler   dataHandler   );      public AttachmentPart createAttachmentPart(Object   content   , String   contentType   );      public abstract void removeAllAttachments(  );      public abstract void saveChanges(  ) throws SOAPException;      public abstract boolean saveRequired(  );      public abstract void writeTo( java.io.OutputStream out)         throws SOAPExceptionjava.io.IOException;  }

SOAPMessage is an abstract class that represents a complete SOAP message. A SOAPMessage object can be obtained from the createMessage( ) method of the MessageFactory class, and consists of several parts :

MIME headers: When a SOAP message is transmitted using a protocol such as HTTP or SMTP, it requires a set of MIME headers that specify, at a minimum, the type of the protocol payload and its length. In the case of a SOAP message with no attachments, the content type is always text/xml . A message with attachments has content type multipart/ related as well as additional MIME headers associated with the SOAPPart and with each attachment.
A SOAPPart: SOAPPart is a wrapper for the XML part of the SOAP message. Nested inside the SOAPPart is a SOAPEnvelope object that itself wraps an empty SOAPHeader and an empty SOAPBody . In the case of a SOAP message with attachments, the SOAPPart has MIME headers, one of which specifies the content type of text/xml . The getSOAPPart( ) method returns a reference to the SOAPPart element of a SOAP message.
AttachmentPart s: When a message has attachments, each is represented by an AttachmentPart . This object contains not only the data embedded within the attachment, but also the MIME headers that specify its type, length, and other attributes. The SOAPMessage created by the default MessageFactory implementation does not have any attachments.

The methods of the SOAPMessage class can be divided into three groups:

Methods that deal with the MIME headers
Methods that manage attachments
Miscellaneous methods that handle the message itself

The getMimeHeaders( ) method can be used to get a reference to the MimeHeaders object that contains the message-level MIME headers. You can use the methods of this object to add or remove headers as required. The setContentDescription( ) and getContentDescription( ) methods are wrappers that allow you to quickly access or set the Content-Description header, although it is not obvious why this header deserves special treatment. In general, application code does not attempt to set either the Content-Type or Content-Length headers, since these are set appropriately by the saveChanges( ) method (discussed shortly) before the message is transmitted.

The addAttachmentPart( ) method allows you to add an attachment given as an AttachmentPart object to a SOAP message. There are three methods that you can use to create attachments. The zero-argument createAttachment( ) method creates an attachment that has no associated data and returns an AttachmentPart object. The content and MIME headers for an attachment created in this way can be set using methods of the AttachmentPart class, described earlier in this chapter. The two-argument variant of this method creates an attachment whose content is supplied by the first argument and whose MIME type is given by the second argument. The MIME type must be compatible with the type of the object itself, and SAAJ implementations may place restrictions on the data types that are handled properly by this method. Refer to the discussion of attachments in Chapter 6 for further information. The final version of this method specifies both the data content and its MIME type using a DataHandler object. This method allows you to include almost any type of data in the attachment, and also lets you determine the way in which it is represented.

The countAttachments( ) method returns the number of attachments in the message. There are two methods that allow you to get access to these attachments. The zero-argument getAttachments( ) method returns an Iterator over the AttachmentPart object for all of the attachments. The other variant of getAttachments( ) returns an Iterator over all of the attachments that have MIME headers that include all of those in the given MimeHeaders object. The removeAllAttachments( ) method removes all of the attachments from the message. Note that there is no way to remove individual attachments.

The final group of SOAPMessage methods deals with the message itself. A SOAPMessage is constructed by building a tree made up of SOAPElement s and other node types. This tree is then serialized into XML for transmission, and the appropriate MIME headers are added. The serialization process can be performed by calling the saveChanges( ) method, which stores a copy of the generated XML as part of the SOAPMessage object. Subsequent changes to the node tree or to attachment data or MIME headers invalidates the XML representation and necessitates another call to the saveChanges( ) method. Since serialization is expensive, unnecessary calls to this method should be avoided by first calling saveRequired( ) , which returns true only if the XML representation and the node tree are not synchronized.

The writeTo( ) method creates an XML representation of a SOAPMessage and writes it to a given output stream. writeTo( ) uses the saveRequired( ) and saveChanges( ) methods to create the XML if necessary. This method can be useful as a debugging aid, and is also used internally by the SOAPConnection call() method to generate the XML that is actually sent to a remote system.

Passed To

javax.xml.messaging.OnewayListener.onMessage( ) , javax.xml.messaging.ProviderConnection.send( ) , javax.xml.messaging.ReqRespListener.onMessage( ) , javax.xml.rpc.handler.soap.SOAPMessageContext.setMessage( ) , SOAPConnection.call( )

Returned By

javax.xml.messaging.ReqRespListener.onMessage( ) , javax.xml.rpc.handler.soap.SOAPMessageContext.getMessage( ) , MessageFactory.createMessage( ) , SOAPConnection.call( )