A single attachment to a
SOAPMessage
object. A
SOAPMessage
object may contain zero, one, or many
AttachmentPart
objects. Each
AttachmentPart
object consists of two parts,
application-specific content and associated MIME headers. The
MIME headers consists of name/value pairs that can be used to
identify and describe the content.
An
AttachmentPart
object must conform to
certain standards.
- It must conform to MIME [RFC2045]
standards
- It MUST contain content
-
The header portion MUST include the following header:
-
Content-Type
This header identifies the type of data in the content
of an AttachmentPart
object and MUST
conform to [RFC2045]. The following is an example of a
Content-Type header:
Content-Type: application/xml
The following line of code, in which ap
is
an AttachmentPart
object, sets the header
shown in the previous example.
ap.setMimeHeader("Content-Type", "application/xml");
There are no restrictions on the content portion of an
AttachmentPart
object. The content may be anything
from a simple plain text object to a complex XML document or
image file.
An
AttachmentPart
object is created with the
method
SOAPMessage.createAttachmentPart
. After
setting its MIME headers, the
AttachmentPart
object is added to the message that created it with the method
SOAPMessage.addAttachmentPart
.
The following code fragment, in which
m
is a
SOAPMessage
object and
contentStringl
is a
String
, creates an instance of
AttachmentPart
, sets the
AttachmentPart
object with some content and header information, and adds the
AttachmentPart
object to the
SOAPMessage
object.
AttachmentPart ap1 = m.createAttachmentPart();
ap1.setContent(contentString1, "text/plain");
m.addAttachmentPart(ap1);
The following code fragment creates and adds a second
AttachmentPart
instance to the same message.
jpegData
is a binary byte buffer representing the jpeg
file.
AttachmentPart ap2 = m.createAttachmentPart();
byte[] jpegData = ...;
ap2.setContent(new ByteArrayInputStream(jpegData), "image/jpeg");
m.addAttachmentPart(ap2);
The
getContent
method retrieves the contents
and header from an
AttachmentPart
object.
Depending on the
DataContentHandler
objects
present, the returned
Object
can either be a typed
Java object corresponding to the MIME type or an
InputStream
object that contains the content as
bytes.
String content1 = ap1.getContent();
java.io.InputStream content2 = ap2.getContent();
The method
clearContent
removes all the content
from an
AttachmentPart
object but does not affect
its header information.
ap1.clearContent();
addMimeHeader
public void addMimeHeader(String name,
String value)
Adds a MIME header with the specified name and value to
this
AttachmentPart
object.
Note that RFC822 headers can contain only US-ASCII
characters.
name
- a String
giving the
name of the header to be addedvalue
- a String
giving the
value of the header to be added
clearContent
public void clearContent()
Clears out the content of this
AttachmentPart
object. The MIME header portion is left
untouched.
getAllMimeHeaders
public Iterator getAllMimeHeaders()
Retrieves all the headers for this
AttachmentPart
object as an iterator over the
MimeHeader
objects.
- an
Iterator
object with all of the Mime
headers for this AttachmentPart
object
getContent
public Object getContent()
throws SOAPException
Gets the content of this
AttachmentPart
object as a Java
object. The type of the returned Java object depends on (1) the
DataContentHandler
object that is used to interpret the bytes
and (2) the
Content-Type
given in the header.
For the MIME content types "text/plain", "text/html" and "text/xml", the
DataContentHandler
object does the conversions to and
from the Java types corresponding to the MIME types.
For other MIME types,the
DataContentHandler
object
can return an
InputStream
object that contains the content data
as raw bytes.
A JAXM-compliant implementation must, as a minimum, return a
java.lang.String
object corresponding to any content
stream with a
Content-Type
value of
text/plain
, a
javax.xml.transform.StreamSource
object corresponding to a
content stream with a
Content-Type
value of
text/xml
, a
java.awt.Image
object
corresponding to a content stream with a
Content-Type
value of
image/gif
or
image/jpeg
. For those content types that an
installed
DataContentHandler
object does not understand, the
DataContentHandler
object is required to return a
java.io.InputStream
object with the raw bytes.
- a Java object with the content of this
AttachmentPart
object
SOAPException
- if there is no content set
into this AttachmentPart
object or if there
was a data transformation error
getContentId
public String getContentId()
Gets the value of the MIME header whose name is
"Content-Id".
- a
String
giving the value of the
"Content-Id" header or null
if there is
none
setContentId(java.lang.String)
getContentLocation
public String getContentLocation()
Gets the value of the MIME header
"Content-Location".
- a
String
giving the value of the
"Content-Location" header or null
if there
is none
getContentType
public String getContentType()
Gets the value of the MIME header "Content-Type".
- a
String
giving the value of the
"Content-Type" header or null
if there is
none
getDataHandler
public DataHandler getDataHandler()
throws SOAPException
Gets the DataHandler
object for this
AttachmentPart
object.
- the
DataHandler
object associated with
this AttachmentPart
object
SOAPException
- if there is
no data in this AttachmentPart
object
getMatchingMimeHeaders
public Iterator getMatchingMimeHeaders(names[] )
Retrieves all MimeHeader
objects that match
a name in the given array.
- all of the MIME headers that match one of the names
in the given array as an
Iterator
object
getMimeHeader
public String[] getMimeHeader(String name)
Gets all the values of the header identified by the given
String
.
name
- the name of the header; example:
"Content-Type"
- a
String
array giving the value for the
specified header
setMimeHeader(java.lang.String, java.lang.String)
getNonMatchingMimeHeaders
public Iterator getNonMatchingMimeHeaders(names[] )
Retrieves all MimeHeader
objects whose name
does not match a name in the given array.
- all of the MIME headers in this
AttachmentPart
object except those that match one
of the names in the given array. The nonmatching MIME
headers are returned as an Iterator
object.
getSize
public int getSize()
throws SOAPException
Returns the number of bytes in this
AttachmentPart
object.
- the size of this
AttachmentPart
object
in bytes or -1 if the size cannot be determined
SOAPException
- if the content of this
attachment is corrupted of if there was an exception
while trying to determine the size.
removeAllMimeHeaders
public void removeAllMimeHeaders()
Removes all the MIME header entries.
removeMimeHeader
public void removeMimeHeader(String header)
Removes all MIME headers that match the given name.
header
- - the string name of the MIME
header/s to be removed
setContent
public void setContent(Object object,
String contentType)
Sets the content of this attachment part to that of the
given Object
and sets the value of the
Content-Type
header to the given type. The type of the
Object
should correspond to the value given for
the Content-Type
. This depends on the particular
set of DataContentHandler
objects in use.
object
- the Java object that makes up
the content for this attachment partcontentType
- the MIME string that
specifies the type of the content
getContent()
setContentId
public void setContentId(String contentId)
Sets the MIME header "Content-Id" with the given
value.
contentId
- a String
giving
the value of the "Content-Id" header
getContentId()
setContentLocation
public void setContentLocation(String contentLocation)
Sets the MIME header "Content-Location" with the given
value.
contentLocation
- a String
giving the value of the "Content-Location" header
setContentType
public void setContentType(String contentType)
Sets the MIME header "Content-Type" with the given
value.
contentType
- a String
giving the value of the "Content-Type" header
setDataHandler
public void setDataHandler(DataHandler datahandler)
Sets the given DataHandler
object as the
data handler for this AttachmentPart
object.
Typically, on an incoming message, the data handler is
automatically set. When a message is being created and
populated with content, the setDataHandler
method can be used to get data from various data sources into
the message.
datahandler
- DataHandler
object to
be set
setMimeHeader
public void setMimeHeader(String name,
String value)
Changes the first header entry that matches the given name
to the given value, adding a new header if no existing
header matches. This method also removes all matching
headers but the first.
Note that RFC822 headers can only contain US-ASCII
characters.
name
- a String
giving the
name of the header for which to searchvalue
- a String
giving the
value to be set for the header whose name matches the
given name