Class AttachmentPart
public abstract class AttachmentPart extends Object
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 anAttachmentPart
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 whichap
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 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 Summary
Constructors Constructor Description AttachmentPart()
Create a new AttachmentPart. -
Method Summary
Modifier and Type Method Description abstract void
addMimeHeader(String name, String value)
Adds a MIME header with the specified name and value to thisAttachmentPart
object.abstract void
clearContent()
Clears out the content of thisAttachmentPart
object.abstract Iterator
getAllMimeHeaders()
Retrieves all the headers for thisAttachmentPart
object as an iterator over theMimeHeader
objects.abstract Object
getContent()
Gets the content of thisAttachmentPart
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 "Content-Location".String
getContentType()
Gets the value of the MIME header "Content-Type".abstract Iterator
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
getNonMatchingMimeHeaders(String[] names)
Retrieves allMimeHeader
objects whose name does not match a name in the given array.abstract int
getSize()
Returns the number of bytes in thisAttachmentPart
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
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 "Content-Id" with the given value.void
setContentLocation(String contentLocation)
Sets the MIME header "Content-Location" with the given value.void
setContentType(String contentType)
Sets the MIME header "Content-Type" with the given value.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.
-
Constructor Details
-
AttachmentPart
public AttachmentPart()Create a new AttachmentPart.
-
-
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 JAXM-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.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
-
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
- if the contentType does not match the type of the content object, or if there was noDataContentHandler
object for this content object- See Also:
getContent()
-
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:
setContentId(java.lang.String)
-
getContentLocation
Gets the value of the MIME header "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 "Content-Type".- Returns:
- a
String
giving the value of the "Content-Type" header ornull
if there is none
-
setContentId
Sets the MIME header "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:
getContentId()
-
setContentLocation
Sets the MIME header "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 "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(java.lang.String, java.lang.String)
-
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 of 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 of 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 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 anIterator
object.
-