public abstract class AttachmentPart {
// Public Constructors
public AttachmentPart( );
// Property Accessor Methods (by property name)
public abstract Iterator getAllMimeHeaders( );
public abstract Object getContent( ) throws SOAPException;
public String getContentId( );
public void setContentId( String contentId);
public String getContentLocation( );
public void setContentLocation( String contentLocation);
public String getContentType( );
public void setContentType( String contentType);
public abstract javax.activation.DataHandler getDataHandler( )
throws SOAPException;
public abstract void setDataHandler( javax.activation.DataHandler dataHandler);
public abstract int getSize( ) throws SOAPException;
// Public Instance Methods
public abstract void addMimeHeader(String name, String value);
public abstract void clearContent( );
public abstract Iterator getMatchingMimeHeaders(String[ ] names);
public abstract String[ ] getMimeHeader(String name);
public abstract Iterator getNonMatchingMimeHeaders(String[ ] names);
public abstract void removeAllMimeHeaders( );
public abstract void removeMimeHeader( String header);
public abstract void setContent(Object object, String contentType);
public abstract void setMimeHeader(String name, String value);
}
The AttachmentPart class represents an
attachment
to a SOAP message. Attachments are created using the
createAttachment( ) method of the
SOAPMessage class and are composed of MIME-encoded
content and a set of MIME headers. The content can be associated with
the attachment either when it is constructed or when subsequently
using the setContent( ) or
setDataHandler( ) methods.
The content of an attachment can be added using either the
setContent( ) or the setDataHandler(
) method, both of which automatically set the
Content-Type MIME header to match the type of data
provided. The setContent( ) method supplies the
content as a Java object together with a string that indicates its
MIME type. When the SOAPMessage is serialized to
XML, the content of the attachment is converted to a byte stream
using a DataHandler that is specialized for that
object's MIME type. The SAAJ reference
implementation provides handlers that work for a small number of MIME
types, including plain text and XML and JPEG images. However, these
handlers require the source object to be of a specific type, which is
not always convenient. For example, if you want to include a JPEG
image as an attachment, you need to supply it in the form of a
java.awt.Image object. This is inconvenient if you
already have it in the form of a byte array. The
setDataHandler( ) method lets you supply the
attachment data in the form of a DataHandler
object that encapsulates both the MIME type and the data, and also
allows you to provide the code required to handle the conversion into
byte stream form, which is, of course, trivial if you already have a
byte stream. Except for a small number of special cases, the
setDataHandler( ) method is the better choice. For
a more complete discussion of this topic, refer to Chapter 3.
You can discover the size of the data in an attachment by calling the
getSize( ) method. The actual content can be
retrieved using either the getContent( ) or the
getDataHandler( ) method. The getContent(
) method returns the data in the form of an object that is
determined by its MIME type and the data content handlers that are
installed. The getDataHandler( ) method returns
the content in the form of a DataHandler object
instead, which potentially allows you to retrieve it in various
different forms or as a raw byte stream. The clearContent(
) method removes the data content of the attachment, but
does not affect any of the MIME headers.
Each attachment has its own set of MIME headers that are distinct
from those associated with the SOAPMessage of
which it forms a part. The AttachmentPart class
provides a group of methods that allow you to access or set the MIME
headers. The addMimeHeader( ),
setMimeHeader( ), removeMimeHeader(
), and removeAllMimeHeaders( ) methods
all change the set of headers, whereas getMimeHeader(
), getAllMimeHeaders( ),
getMatchingMimeHeaders( ), and
getNonMatchingMimeHeaders( ) return some or all of
the existing headers. These methods are the same as the similarly
named methods of the MimeHeaders class, which is
described later in this section, apart from the fact that the
MimeHeaders method does not include
Mime in the method name (e.g.,
getAllMimeHeaders( ) corresponds to the
MimeHeaders getAllHeaders( )
method). AttachmentPart also provides a small
number of convenience methods, such as getContentType(
) and setContentType( ), that provide
access to commonly used MIME headers without requiring the use of the
header name. As noted earlier, the appropriate
Content-Type is set automatically when the
attachment data is installed, and should not usually be changed.
