public abstract class AttachmentPart extends Object
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.
Content-TypeAttachmentPart 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();
| Constructor and Description |
|---|
AttachmentPart() |
| Modifier and Type | Method and Description |
|---|---|
abstract void |
addMimeHeader(String name,
String value)
Adds a MIME header with the specified name and value to this
AttachmentPart object. |
abstract void |
clearContent()
Clears out the content of this
AttachmentPart object. |
abstract Iterator |
getAllMimeHeaders()
Retrieves all the headers for this
AttachmentPart object
as an iterator over the MimeHeader objects. |
abstract InputStream |
getBase64Content()
Returns an
InputStream which can be used to obtain the
content of AttachmentPart as Base64 encoded
character data, this method would base64 encode the raw bytes
of the attachment and return. |
abstract Object |
getContent()
Gets the content of this
AttachmentPart object as a Java
object. |
String |
getContentId()
Gets the value of the MIME header whose name is "Content-ID".
|
String |
getContentLocation()
Gets the value of the MIME header whose name is "Content-Location".
|
String |
getContentType()
Gets the value of the MIME header whose name is "Content-Type".
|
abstract DataHandler |
getDataHandler()
Gets the
DataHandler object for this AttachmentPart
object. |
abstract Iterator |
getMatchingMimeHeaders(String[] names)
Retrieves all
MimeHeader objects that match a name in
the given array. |
abstract String[] |
getMimeHeader(String name)
Gets all the values of the header identified by the given
String. |
abstract Iterator |
getNonMatchingMimeHeaders(String[] names)
Retrieves all
MimeHeader objects whose name does
not match a name in the given array. |
abstract InputStream |
getRawContent()
Gets the content of this
AttachmentPart object as an
InputStream as if a call had been made to getContent and no
DataContentHandler had been registered for the
content-type of this AttachmentPart. |
abstract byte[] |
getRawContentBytes()
Gets the content of this
AttachmentPart object as a
byte[] array as if a call had been made to getContent and no
DataContentHandler had been registered for the
content-type of this AttachmentPart. |
abstract int |
getSize()
Returns the number of bytes in this
AttachmentPart
object. |
abstract void |
removeAllMimeHeaders()
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 source
InputStream and sets the value of the
Content-Type header to the value contained in
contentType, 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 given
Object and sets the value of the Content-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(DataHandler dataHandler)
Sets the given
DataHandler object as the data handler
for this AttachmentPart 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 the
InputStream content and sets the value of the
Content-Type header to the value contained in
contentType. |
abstract void |
setRawContentBytes(byte[] content,
int offset,
int len,
String contentType)
Sets the content of this attachment part to that contained by the
byte[] array content and sets the value of the
Content-Type header to the value contained in
contentType. |
public abstract int getSize()
throws SOAPException
AttachmentPart
object.AttachmentPart object in bytes
or -1 if the size cannot be determinedSOAPException - if the content of this attachment is
corrupted of if there was an exception while trying
to determine the size.public abstract void clearContent()
AttachmentPart object.
The MIME header portion is left untouched.public abstract Object getContent() throws SOAPException
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 SAAJ-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.stream.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.
AttachmentPart
objectSOAPException - if there is no content set into this
AttachmentPart object or if there was a data
transformation errorpublic abstract InputStream getRawContent() throws SOAPException
AttachmentPart object as an
InputStream as if a call had been made to getContent and no
DataContentHandler had been registered for the
content-type of this AttachmentPart.
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.
InputStream from which the raw data contained by
the AttachmentPart can be accessed.SOAPException - if there is no content set into this
AttachmentPart object or if there was a data
transformation error.getRawContentBytes()public abstract byte[] getRawContentBytes()
throws SOAPException
AttachmentPart object as a
byte[] array as if a call had been made to getContent and no
DataContentHandler had been registered for the
content-type of this AttachmentPart.byte[] array containing the raw data of the
AttachmentPart.SOAPException - if there is no content set into this
AttachmentPart object or if there was a data
transformation error.public abstract InputStream getBase64Content() throws SOAPException
InputStream which can be used to obtain the
content of AttachmentPart as Base64 encoded
character data, this method would base64 encode the raw bytes
of the attachment and return.InputStream from which the Base64 encoded
AttachmentPart can be read.SOAPException - if there is no content set into this
AttachmentPart object or if there was a data
transformation error.public abstract void setContent(Object object, String contentType)
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 contentIllegalArgumentException - may be thrown if the contentType
does not match the type of the content object, or if there
was no DataContentHandler object for this
content objectgetContent()public abstract void setRawContent(InputStream content, String contentType) throws SOAPException
InputStream content and sets the value of the
Content-Type header to the value contained in
contentType.
A subsequent call to getSize() may not be an exact measure of the content size.
content - the raw data to add to the attachment partcontentType - the value to set into the Content-Type
headerSOAPException - if an there is an error in setting the contentNullPointerException - if content is nullpublic abstract void setRawContentBytes(byte[] content,
int offset,
int len,
String contentType)
throws SOAPException
byte[] array content and sets the value of the
Content-Type header to the value contained in
contentType.content - the raw data to add to the attachment partcontentType - the value to set into the Content-Type
headeroffset - the offset in the byte array of the contentlen - the number of bytes that form the contentSOAPException - if an there is an error in setting the content
or content is nullpublic abstract void setBase64Content(InputStream content, String contentType) throws SOAPException
InputStream and sets the value of the
Content-Type header to the value contained in
contentType, 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.
content - the base64 encoded data to add to the attachment partcontentType - the value to set into the Content-Type
headerSOAPException - if an there is an error in setting the contentNullPointerException - if content is nullpublic abstract DataHandler getDataHandler() throws SOAPException
DataHandler object for this AttachmentPart
object.DataHandler object associated with this
AttachmentPart objectSOAPException - if there is no data in
this AttachmentPart objectpublic abstract void setDataHandler(DataHandler dataHandler)
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 - the DataHandler object to be setIllegalArgumentException - if there was a problem with
the specified DataHandler objectpublic String getContentId()
String giving the value of the
"Content-ID" header or null if there
is nonesetContentId(java.lang.String)public String getContentLocation()
String giving the value of the
"Content-Location" header or null if there
is nonepublic String getContentType()
String giving the value of the
"Content-Type" header or null if there
is nonepublic void setContentId(String contentId)
contentId - a String giving the value of the
"Content-ID" headerIllegalArgumentException - if there was a problem with
the specified contentId valuegetContentId()public void setContentLocation(String contentLocation)
contentLocation - a String giving the value of the
"Content-Location" headerIllegalArgumentException - if there was a problem with
the specified content locationpublic void setContentType(String contentType)
contentType - a String giving the value of the
"Content-Type" headerIllegalArgumentException - if there was a problem with
the specified content typepublic abstract void removeMimeHeader(String header)
header - the string name of the MIME header/s to
be removedpublic abstract void removeAllMimeHeaders()
public abstract String[] getMimeHeader(String name)
String.name - the name of the header; example: "Content-Type"String array giving the value for the
specified headersetMimeHeader(java.lang.String, java.lang.String)public abstract void setMimeHeader(String name, String value)
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 nameIllegalArgumentException - if there was a problem with
the specified mime header name or valuepublic abstract void addMimeHeader(String name, String value)
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 addedIllegalArgumentException - if there was a problem with
the specified mime header name or valuepublic abstract Iterator getAllMimeHeaders()
AttachmentPart object
as an iterator over the MimeHeader objects.Iterator object with all of the Mime
headers for this AttachmentPart objectpublic abstract Iterator getMatchingMimeHeaders(String[] names)
MimeHeader objects that match a name in
the given array.names - a String array with the name(s) of the
MIME headers to be returnedIterator objectpublic abstract Iterator getNonMatchingMimeHeaders(String[] names)
MimeHeader objects whose name does
not match a name in the given array.names - a String array with the name(s) of the
MIME headers not to be returnedAttachmentPart object
except those that match one of the names in the
given array. The nonmatching MIME headers are returned as an
Iterator object. Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2020, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.