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 anAttachmentPart
object and MUST conform to [RFC2045]. The following is an example of a Content-Type header:Content-Type: application/xml
ap
is anAttachmentPart
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 contentString
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();
clearContent
removes all the content from an
AttachmentPart
object but does not affect its header information.
ap1.clearContent();
- Since:
- 1.6
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract void
addMimeHeader
(String name, String value) Adds a MIME header with the specified name and value to thisAttachmentPart
object.abstract void
Clears out the content of thisAttachmentPart
object.abstract Iterator
<MimeHeader> Retrieves all the headers for thisAttachmentPart
object as an iterator over theMimeHeader
objects.abstract InputStream
Returns anInputStream
which can be used to obtain the content ofAttachmentPart
as Base64 encoded character data, this method would base64 encode the raw bytes of the attachment and return.abstract Object
Gets the content of thisAttachmentPart
object as a Java object.Gets the value of the MIME header whose name is "Content-ID".Gets the value of the MIME header whose name is "Content-Location".Gets the value of the MIME header whose name is "Content-Type".abstract jakarta.activation.DataHandler
Gets theDataHandler
object for thisAttachmentPart
object.abstract Iterator
<MimeHeader> getMatchingMimeHeaders
(String[] names) Retrieves allMimeHeader
objects that match a name in the given array.abstract String[]
getMimeHeader
(String name) Gets all the values of the header identified by the givenString
.abstract Iterator
<MimeHeader> getNonMatchingMimeHeaders
(String[] names) Retrieves allMimeHeader
objects whose name does not match a name in the given array.abstract InputStream
Gets the content of thisAttachmentPart
object as an InputStream as if a call had been made togetContent
and noDataContentHandler
had been registered for thecontent-type
of thisAttachmentPart
.abstract byte[]
Gets the content of thisAttachmentPart
object as a byte[] array as if a call had been made togetContent
and noDataContentHandler
had been registered for thecontent-type
of thisAttachmentPart
.abstract int
getSize()
Returns the number of bytes in thisAttachmentPart
object.abstract void
Removes all the MIME header entries.abstract void
removeMimeHeader
(String header) Removes all MIME headers that match the given name.abstract void
setBase64Content
(InputStream content, String contentType) Sets the content of this attachment part from the Base64 sourceInputStream
and sets the value of theContent-Type
header to the value contained incontentType
, This method would first decode the base64 input and write the resulting raw bytes to the attachment.abstract void
setContent
(Object object, String contentType) Sets the content of this attachment part to that of the givenObject
and sets the value of theContent-Type
header to the given type.void
setContentId
(String contentId) Sets the MIME header whose name is "Content-ID" with the given value.void
setContentLocation
(String contentLocation) Sets the MIME header whose name is "Content-Location" with the given value.void
setContentType
(String contentType) Sets the MIME header whose name is "Content-Type" with the given value.abstract void
setDataHandler
(jakarta.activation.DataHandler dataHandler) Sets the givenDataHandler
object as the data handler for thisAttachmentPart
object.abstract 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.abstract void
setRawContent
(InputStream content, String contentType) Sets the content of this attachment part to that contained by theInputStream
content
and sets the value of theContent-Type
header to the value contained incontentType
.abstract void
setRawContentBytes
(byte[] content, int offset, int len, String contentType) Sets the content of this attachment part to that contained by thebyte[]
arraycontent
and sets the value of theContent-Type
header to the value contained incontentType
.
-
Constructor Details
-
AttachmentPart
protected AttachmentPart()Default constructor.
-
-
Method Details
-
getSize
Returns the number of bytes in thisAttachmentPart
object.- Returns:
- the size of this
AttachmentPart
object in bytes or -1 if the size cannot be determined - Throws:
SOAPException
- if the content of this attachment is corrupted of if there was an exception while trying to determine the size.
-
clearContent
public abstract void clearContent()Clears out the content of thisAttachmentPart
object. The MIME header portion is left untouched. -
getContent
Gets the content of thisAttachmentPart
object as a Java object. The type of the returned Java object depends on (1) theDataContentHandler
object that is used to interpret the bytes and (2) theContent-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,theDataContentHandler
object can return anInputStream
object that contains the content data as raw bytes.A SAAJ-compliant implementation must, as a minimum, return a
java.lang.String
object corresponding to any content stream with aContent-Type
value oftext/plain
, ajavax.xml.transform.stream.StreamSource
object corresponding to a content stream with aContent-Type
value oftext/xml
, ajava.awt.Image
object corresponding to a content stream with aContent-Type
value ofimage/gif
orimage/jpeg
. For those content types that an installedDataContentHandler
object does not understand, theDataContentHandler
object is required to return ajava.io.InputStream
object with the raw bytes.- Returns:
- a Java object with the content of this
AttachmentPart
object - Throws:
SOAPException
- if there is no content set into thisAttachmentPart
object or if there was a data transformation error
-
getRawContent
Gets the content of thisAttachmentPart
object as an InputStream as if a call had been made togetContent
and noDataContentHandler
had been registered for thecontent-type
of thisAttachmentPart
.Note that reading from the returned InputStream would result in consuming the data in the stream. It is the responsibility of the caller to reset the InputStream appropriately before calling a Subsequent API. If a copy of the raw attachment content is required then the
getRawContentBytes()
API should be used instead.- Returns:
- an
InputStream
from which the raw data contained by theAttachmentPart
can be accessed. - Throws:
SOAPException
- if there is no content set into thisAttachmentPart
object or if there was a data transformation error.- Since:
- 1.6, SAAJ 1.3
- See Also:
-
getRawContentBytes
Gets the content of thisAttachmentPart
object as a byte[] array as if a call had been made togetContent
and noDataContentHandler
had been registered for thecontent-type
of thisAttachmentPart
.- Returns:
- a
byte[]
array containing the raw data of theAttachmentPart
. - Throws:
SOAPException
- if there is no content set into thisAttachmentPart
object or if there was a data transformation error.- Since:
- 1.6, SAAJ 1.3
-
getBase64Content
Returns anInputStream
which can be used to obtain the content ofAttachmentPart
as Base64 encoded character data, this method would base64 encode the raw bytes of the attachment and return.- Returns:
- an
InputStream
from which the Base64 encodedAttachmentPart
can be read. - Throws:
SOAPException
- if there is no content set into thisAttachmentPart
object or if there was a data transformation error.- Since:
- 1.6, SAAJ 1.3
-
setContent
Sets the content of this attachment part to that of the givenObject
and sets the value of theContent-Type
header to the given type. The type of theObject
should correspond to the value given for theContent-Type
. This depends on the particular set ofDataContentHandler
objects in use.- Parameters:
object
- the Java object that makes up the content for this attachment partcontentType
- the MIME string that specifies the type of the content- Throws:
IllegalArgumentException
- may be thrown if the contentType does not match the type of the content object, or if there was noDataContentHandler
object for this content object- See Also:
-
setRawContent
Sets the content of this attachment part to that contained by theInputStream
content
and sets the value of theContent-Type
header to the value contained incontentType
.A subsequent call to getSize() may not be an exact measure of the content size.
- Parameters:
content
- the raw data to add to the attachment partcontentType
- the value to set into theContent-Type
header- Throws:
SOAPException
- if there is an error in setting the contentNullPointerException
- ifcontent
is null- Since:
- 1.6, SAAJ 1.3
-
setRawContentBytes
public abstract void setRawContentBytes(byte[] content, int offset, int len, String contentType) throws SOAPException Sets the content of this attachment part to that contained by thebyte[]
arraycontent
and sets the value of theContent-Type
header to the value contained incontentType
.- Parameters:
content
- the raw data to add to the attachment partoffset
- the offset in the byte array of the contentlen
- the number of bytes that form the contentcontentType
- the value to set into theContent-Type
header- Throws:
SOAPException
- if there is an error in setting the content or content is null- Since:
- 1.6, SAAJ 1.3
-
setBase64Content
Sets the content of this attachment part from the Base64 sourceInputStream
and sets the value of theContent-Type
header to the value contained incontentType
, This method would first decode the base64 input and write the resulting raw bytes to the attachment.A subsequent call to getSize() may not be an exact measure of the content size.
- Parameters:
content
- the base64 encoded data to add to the attachment partcontentType
- the value to set into theContent-Type
header- Throws:
SOAPException
- if there is an error in setting the contentNullPointerException
- ifcontent
is null- Since:
- 1.6, SAAJ 1.3
-
getDataHandler
Gets theDataHandler
object for thisAttachmentPart
object.- Returns:
- the
DataHandler
object associated with thisAttachmentPart
object - Throws:
SOAPException
- if there is no data in thisAttachmentPart
object
-
setDataHandler
public abstract void setDataHandler(jakarta.activation.DataHandler dataHandler) Sets the givenDataHandler
object as the data handler for thisAttachmentPart
object. Typically, on an incoming message, the data handler is automatically set. When a message is being created and populated with content, thesetDataHandler
method can be used to get data from various data sources into the message.- Parameters:
dataHandler
- theDataHandler
object to be set- Throws:
IllegalArgumentException
- if there was a problem with the specifiedDataHandler
object
-
getContentId
Gets the value of the MIME header whose name is "Content-ID".- Returns:
- a
String
giving the value of the "Content-ID" header ornull
if there is none - See Also:
-
getContentLocation
Gets the value of the MIME header whose name is "Content-Location".- Returns:
- a
String
giving the value of the "Content-Location" header ornull
if there is none
-
getContentType
Gets the value of the MIME header whose name is "Content-Type".- Returns:
- a
String
giving the value of the "Content-Type" header ornull
if there is none
-
setContentId
Sets the MIME header whose name is "Content-ID" with the given value.- Parameters:
contentId
- aString
giving the value of the "Content-ID" header- Throws:
IllegalArgumentException
- if there was a problem with the specifiedcontentId
value- See Also:
-
setContentLocation
Sets the MIME header whose name is "Content-Location" with the given value.- Parameters:
contentLocation
- aString
giving the value of the "Content-Location" header- Throws:
IllegalArgumentException
- if there was a problem with the specified content location
-
setContentType
Sets the MIME header whose name is "Content-Type" with the given value.- Parameters:
contentType
- aString
giving the value of the "Content-Type" header- Throws:
IllegalArgumentException
- if there was a problem with the specified content type
-
removeMimeHeader
Removes all MIME headers that match the given name.- Parameters:
header
- the string name of the MIME header/s to be removed
-
removeAllMimeHeaders
public abstract void removeAllMimeHeaders()Removes all the MIME header entries. -
getMimeHeader
Gets all the values of the header identified by the givenString
.- Parameters:
name
- the name of the header; example: "Content-Type"- Returns:
- a
String
array giving the value for the specified header - See Also:
-
setMimeHeader
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.
- Parameters:
name
- aString
giving the name of the header for which to searchvalue
- aString
giving the value to be set for the header whose name matches the given name- Throws:
IllegalArgumentException
- if there was a problem with the specified mime header name or value
-
addMimeHeader
Adds a MIME header with the specified name and value to thisAttachmentPart
object.Note that RFC822 headers can contain only US-ASCII characters.
- Parameters:
name
- aString
giving the name of the header to be addedvalue
- aString
giving the value of the header to be added- Throws:
IllegalArgumentException
- if there was a problem with the specified mime header name or value
-
getAllMimeHeaders
Retrieves all the headers for thisAttachmentPart
object as an iterator over theMimeHeader
objects.- Returns:
- an
Iterator
object with all the Mime headers for thisAttachmentPart
object
-
getMatchingMimeHeaders
Retrieves allMimeHeader
objects that match a name in the given array.- Parameters:
names
- aString
array with the name(s) of the MIME headers to be returned- Returns:
- all the MIME headers that match one of the names in the
given array as an
Iterator
object
-
getNonMatchingMimeHeaders
Retrieves allMimeHeader
objects whose name does not match a name in the given array.- Parameters:
names
- aString
array with the name(s) of the MIME headers not to be returned- Returns:
- all 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 anIterator
object.
-