Jakarta SOAP with Attachments API 3.0.0 · jakarta.xml.soap.SOAPPart

The container for the SOAP-specific portion of a SOAPMessage object. All messages are required to have a SOAP part, so when a SOAPMessage object is created, it will automatically have a SOAPPart object.

A SOAPPart object is a MIME part and has the MIME headers Content-Id, Content-Location, and Content-Type. Because the value of Content-Type must be "text/xml", a SOAPPart object automatically has a MIME header of Content-Type with its value set to "text/xml". The value must be "text/xml" because content in the SOAP part of a message must be in XML format. Content that is not of type "text/xml" must be in an AttachmentPart object rather than in the SOAPPart object.

When a message is sent, its SOAP part must have the MIME header Content-Type set to "text/xml". Or, from the other perspective, the SOAP part of any message that is received must have the MIME header Content-Type with a value of "text/xml".

A client can access the SOAPPart object of a SOAPMessage object by calling the method SOAPMessage.getSOAPPart. The following line of code, in which message is a SOAPMessage object, retrieves the SOAP part of a message.

SOAPPart soapPart = message.getSOAPPart();

A SOAPPart object contains a SOAPEnvelope object, which in turn contains a SOAPBody object and a SOAPHeader object. The SOAPPart method getEnvelope can be used to retrieve the SOAPEnvelope object.

Access	Constructor and Description
protected	SOAPPart() Default constructor.

Method Summary

Modifier and Type	Method and Description
public abstract void	addMimeHeader(String a `String` giving the header name name, String a `String` giving the value to be set or added value) Creates a `MimeHeader` object with the specified name and value and adds it to this `SOAPPart` object.
public abstract Iterator<MimeHeader>	Returns: an `Iterator` object with all of the Mime headers for this `SOAPPart` object getAllMimeHeaders() Retrieves all the headers for this `SOAPPart` object as an iterator over the `MimeHeader` objects.
public abstract Source	Returns: the content as a `javax.xml.transform.Source` object getContent() Returns the content of the SOAPEnvelope as a JAXP `Source` object.
public String	Returns: a `String` giving the value of the MIME header named "Content-Id" getContentId() Retrieves the value of the MIME header whose name is "Content-Id".
public String	Returns: a `String` giving the value of the MIME header whose name is "Content-Location" getContentLocation() Retrieves the value of the MIME header whose name is "Content-Location".
public abstract SOAPEnvelope	Returns: the `SOAPEnvelope` object for this `SOAPPart` object getEnvelope() Gets the `SOAPEnvelope` object associated with this `SOAPPart` object.
public abstract Iterator<MimeHeader>	Returns: all of the MIME headers that match one of the names in the given array, returned as an `Iterator` object getMatchingMimeHeaders(String[] a `String` array with the name(s) of the MIME headers to be returned names) Retrieves all `MimeHeader` objects that match a name in the given array.
public abstract String[]	Returns: a `String` array giving all the values for the specified header getMimeHeader(String the name of the header; example: "Content-Type" name) Gets all the values of the `MimeHeader` object in this `SOAPPart` object that is identified by the given `String`.
public abstract Iterator<MimeHeader>	Returns: all of the MIME headers in this `SOAPPart` object except those that match one of the names in the given array. The nonmatching MIME headers are returned as an `Iterator` object. getNonMatchingMimeHeaders(String[] a `String` array with the name(s) of the MIME headers not to be returned names) Retrieves all `MimeHeader` objects whose name does not match a name in the given array.
public abstract void	removeAllMimeHeaders() Removes all the `MimeHeader` objects for this `SOAPEnvelope` object.
public abstract void	removeMimeHeader(String a `String` giving the name of the MIME header(s) to be removed header) Removes all MIME headers that match the given name.
public abstract void	setContent(Source the `javax.xml.transform.Source` object with the data to be set source) Sets the content of the `SOAPEnvelope` object with the data from the given `Source` object.
public void	setContentId(String a `String` giving the value of the MIME header "Content-Id" contentId) Sets the value of the MIME header named "Content-Id" to the given `String`.
public void	setContentLocation(String a `String` giving the value of the MIME header "Content-Location" contentLocation) Sets the value of the MIME header "Content-Location" to the given `String`.
public abstract void	setMimeHeader(String a `String` giving the header name for which to search name, String a `String` giving the value to be set. This value will be substituted for the current value(s) of the first header that is a match if there is one. If there is no match, this value will be the value for a new `MimeHeader` object. value) Changes the first header entry that matches the given header name so that its value is the given value, adding a new header with the given name and value if no existing header is a match.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

SOAPPart	back to summary
protected SOAPPart() Default constructor.

Method Detail

addMimeHeader back to summary

addMimeHeader	back to summary
public abstract void addMimeHeader(String name, String value) Creates a `MimeHeader` object with the specified name and value and adds it to this `SOAPPart` object. If a `MimeHeader` with the specified name already exists, this method adds the specified value to the already existing value(s). Note that RFC822 headers can contain only US-ASCII characters. Parameters name:String a `String` giving the header name value:String a `String` giving the value to be set or added Exceptions IllegalArgumentException: if there was a problem with the specified mime header name or value

public abstract void addMimeHeader(String name, String value)

Creates a MimeHeader object with the specified name and value and adds it to this SOAPPart object. If a MimeHeader with the specified name already exists, this method adds the specified value to the already existing value(s).

Note that RFC822 headers can contain only US-ASCII characters.

Parameters

name:String: a String giving the header name
value:String: a String giving the value to be set or added

Exceptions

IllegalArgumentException:: if there was a problem with the specified mime header name or value

getAllMimeHeaders back to summary

getAllMimeHeaders	back to summary
public abstract Iterator<MimeHeader> getAllMimeHeaders() Retrieves all the headers for this `SOAPPart` object as an iterator over the `MimeHeader` objects. Returns:Iterator<MimeHeader> an `Iterator` object with all of the Mime headers for this `SOAPPart` object

public abstract Iterator<MimeHeader> getAllMimeHeaders()

Retrieves all the headers for this SOAPPart object as an iterator over the MimeHeader objects.

Returns:Iterator<MimeHeader>: an Iterator object with all of the Mime headers for this SOAPPart object

getContent back to summary

getContent	back to summary
public abstract Source getContent() throws SOAPException Returns the content of the SOAPEnvelope as a JAXP `Source` object. Returns:Source the content as a `javax.xml.transform.Source` object Exceptions SOAPException: if the implementation cannot convert the specified `Source` object See Also `setContent`

public abstract Source getContent() throws SOAPException

Returns the content of the SOAPEnvelope as a JAXP Source object.

Returns:Source

the content as a javax.xml.transform.Source object

Exceptions

SOAPException:: if the implementation cannot convert the specified Source object

See Also

setContent

getContentId back to summary

getContentId	back to summary
public String getContentId() Retrieves the value of the MIME header whose name is "Content-Id". Returns:String a `String` giving the value of the MIME header named "Content-Id" See Also `setContentId`

public String getContentId()

Retrieves the value of the MIME header whose name is "Content-Id".

Returns:String: a String giving the value of the MIME header named "Content-Id"
See Also: setContentId

getContentLocation back to summary

getContentLocation	back to summary
public String getContentLocation() Retrieves the value of the MIME header whose name is "Content-Location". Returns:String a `String` giving the value of the MIME header whose name is "Content-Location" See Also `setContentLocation`

public String getContentLocation()

Retrieves the value of the MIME header whose name is "Content-Location".

Returns:String: a String giving the value of the MIME header whose name is "Content-Location"
See Also: setContentLocation

getEnvelope back to summary

getEnvelope	back to summary
public abstract SOAPEnvelope getEnvelope() throws SOAPException Gets the `SOAPEnvelope` object associated with this `SOAPPart` object. Once the SOAP envelope is obtained, it can be used to get its contents. Returns:SOAPEnvelope the `SOAPEnvelope` object for this `SOAPPart` object Exceptions SOAPException: if there is a SOAP error

public abstract SOAPEnvelope getEnvelope() throws SOAPException

Gets the SOAPEnvelope object associated with this SOAPPart object. Once the SOAP envelope is obtained, it can be used to get its contents.

Returns:SOAPEnvelope

the SOAPEnvelope object for this SOAPPart object

Exceptions

SOAPException:: if there is a SOAP error

getMatchingMimeHeaders back to summary

getMatchingMimeHeaders	back to summary
public abstract Iterator<MimeHeader> getMatchingMimeHeaders(String[] names) Retrieves all `MimeHeader` objects that match a name in the given array. Parameters names:String[] a `String` array with the name(s) of the MIME headers to be returned Returns:Iterator<MimeHeader> all of the MIME headers that match one of the names in the given array, returned as an `Iterator` object

public abstract Iterator<MimeHeader> getMatchingMimeHeaders(String[] names)

Retrieves all MimeHeader objects that match a name in the given array.

Parameters

names:String[]: a String array with the name(s) of the MIME headers to be returned

Returns:Iterator<MimeHeader>

all of the MIME headers that match one of the names in the given array, returned as an Iterator object

getMimeHeader back to summary

getMimeHeader	back to summary
public abstract String[] getMimeHeader(String name) Gets all the values of the `MimeHeader` object in this `SOAPPart` object that is identified by the given `String`. Parameters name:String the name of the header; example: "Content-Type" Returns:String[] a `String` array giving all the values for the specified header See Also `setMimeHeader`

public abstract String[] getMimeHeader(String name)

Gets all the values of the MimeHeader object in this SOAPPart object that is identified by the given String.

Parameters

name:String: the name of the header; example: "Content-Type"

Returns:String[]

a String array giving all the values for the specified header

See Also

setMimeHeader

getNonMatchingMimeHeaders back to summary

getNonMatchingMimeHeaders	back to summary
public abstract Iterator<MimeHeader> getNonMatchingMimeHeaders(String[] names) Retrieves all `MimeHeader` objects whose name does not match a name in the given array. Parameters names:String[] a `String` array with the name(s) of the MIME headers not to be returned Returns:Iterator<MimeHeader> all of the MIME headers in this `SOAPPart` object except those that match one of the names in the given array. The nonmatching MIME headers are returned as an `Iterator` object.

public abstract Iterator<MimeHeader> getNonMatchingMimeHeaders(String[] names)

Retrieves all MimeHeader objects whose name does not match a name in the given array.

Parameters

names:String[]: a String array with the name(s) of the MIME headers not to be returned

Returns:Iterator<MimeHeader>

all of the MIME headers in this SOAPPart object except those that match one of the names in the given array. The nonmatching MIME headers are returned as an Iterator object.

removeAllMimeHeaders	back to summary
public abstract void removeAllMimeHeaders() Removes all the `MimeHeader` objects for this `SOAPEnvelope` object.

removeMimeHeader back to summary

removeMimeHeader	back to summary
public abstract void removeMimeHeader(String header) Removes all MIME headers that match the given name. Parameters header:String a `String` giving the name of the MIME header(s) to be removed

public abstract void removeMimeHeader(String header)

Removes all MIME headers that match the given name.

Parameters

header:String: a String giving the name of the MIME header(s) to be removed

setContent back to summary

setContent	back to summary
public abstract void setContent(Source source) throws SOAPException Sets the content of the `SOAPEnvelope` object with the data from the given `Source` object. This `Source` must contain a valid SOAP document. Parameters source:Source the `javax.xml.transform.Source` object with the data to be set Exceptions SOAPException: if there is a problem in setting the source See Also `getContent`

public abstract void setContent(Source source) throws SOAPException

Sets the content of the SOAPEnvelope object with the data from the given Source object. This Source must contain a valid SOAP document.

Parameters

source:Source: the javax.xml.transform.Source object with the data to be set

Exceptions

SOAPException:: if there is a problem in setting the source

See Also

getContent

setContentId back to summary

setContentId	back to summary
public void setContentId(String contentId) Sets the value of the MIME header named "Content-Id" to the given `String`. Parameters contentId:String a `String` giving the value of the MIME header "Content-Id" Exceptions IllegalArgumentException: if there is a problem in setting the content id See Also `getContentId`

public void setContentId(String contentId)

Sets the value of the MIME header named "Content-Id" to the given String.

Parameters

contentId:String: a String giving the value of the MIME header "Content-Id"

Exceptions

IllegalArgumentException:: if there is a problem in setting the content id

See Also

getContentId

setContentLocation back to summary

setContentLocation	back to summary
public void setContentLocation(String contentLocation) Sets the value of the MIME header "Content-Location" to the given `String`. Parameters contentLocation:String a `String` giving the value of the MIME header "Content-Location" Exceptions IllegalArgumentException: if there is a problem in setting the content location. See Also `getContentLocation`

public void setContentLocation(String contentLocation)

Sets the value of the MIME header "Content-Location" to the given String.

Parameters

contentLocation:String: a String giving the value of the MIME header "Content-Location"

Exceptions

IllegalArgumentException:: if there is a problem in setting the content location.

See Also

getContentLocation

setMimeHeader back to summary

setMimeHeader	back to summary
public abstract void setMimeHeader(String name, String value) Changes the first header entry that matches the given header name so that its value is the given value, adding a new header with the given name and value if no existing header is a match. If there is a match, this method clears all existing values for the first header that matches and sets the given value instead. If more than one header has the given name, this method removes all of the matching headers after the first one. Note that RFC822 headers can contain only US-ASCII characters. Parameters name:String a `String` giving the header name for which to search value:String a `String` giving the value to be set. This value will be substituted for the current value(s) of the first header that is a match if there is one. If there is no match, this value will be the value for a new `MimeHeader` object. Exceptions IllegalArgumentException: if there was a problem with the specified mime header name or value See Also `getMimeHeader`

public abstract void setMimeHeader(String name, String value)

Changes the first header entry that matches the given header name so that its value is the given value, adding a new header with the given name and value if no existing header is a match. If there is a match, this method clears all existing values for the first header that matches and sets the given value instead. If more than one header has the given name, this method removes all of the matching headers after the first one.

Note that RFC822 headers can contain only US-ASCII characters.

Parameters

name:String: a String giving the header name for which to search
value:String: a String giving the value to be set. This value will be substituted for the current value(s) of the first header that is a match if there is one. If there is no match, this value will be the value for a new MimeHeader object.

Exceptions

IllegalArgumentException:: if there was a problem with the specified mime header name or value

See Also

getMimeHeader

public abstract Class SOAPPart

Constructor Summary

Method Summary

Constructor Detail

Method Detail