org.apache.xmlbeans.impl.soap

## Class SOAPPart

- java.lang.Object
- - org.apache.xmlbeans.impl.soap.SOAPPart

- All Implemented Interfaces:
    Document, Node

      public abstract class SOAPPart
      extends Object
      implements Document

  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.

- - ### Field Summary

    - ### Fields inherited from interface org.w3c.dom.Node

      `ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SOAPPart()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `addMimeHeader(String name, String value)` Creates a `MimeHeader` object with the specified name and value and adds it to this `SOAPPart` object.
    `abstract Iterator<MimeHeader>` | `getAllMimeHeaders()` Retrieves all the headers for this `SOAPPart` object as an iterator over the `MimeHeader` objects.
    `abstract Source` | `getContent()` Returns the content of the SOAPEnvelope as a JAXP `Source` object.
    `String` | `getContentId()` Retrieves the value of the MIME header whose name is "Content-Id".
    `String` | `getContentLocation()` Retrieves the value of the MIME header whose name is "Content-Location".
    `abstract SOAPEnvelope` | `getEnvelope()` Gets the `SOAPEnvelope` object associated with this `SOAPPart` object.
    `abstract Iterator<MimeHeader>` | `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 `MimeHeader` object in this `SOAPPart` object that is identified by the given `String`.
    `abstract Iterator<MimeHeader>` | `getNonMatchingMimeHeaders(String[] names)` Retrieves all `MimeHeader` objects whose name does not match a name in the given array.
    `abstract void` | `removeAllMimeHeaders()` Removes all the `MimeHeader` objects for this `SOAPEnvelope` object.
    `abstract void` | `removeMimeHeader(String header)` Removes all MIME headers that match the given name.
    `abstract void` | `setContent(Source source)` Sets the content of the `SOAPEnvelope` object with the data from the given `Source` object.
    `void` | `setContentId(String contentId)` Sets the value of the MIME header named "Content-Id" to the given `String`.
    `void` | `setContentLocation(String contentLocation)` Sets the value of the MIME header "Content-Location" to the given `String`.
    `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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.w3c.dom.Document

      `adoptNode, createAttribute, createAttributeNS, createCDATASection, createComment, createDocumentFragment, createElement, createElementNS, createEntityReference, createProcessingInstruction, createTextNode, getDoctype, getDocumentElement, getDocumentURI, getDomConfig, getElementById, getElementsByTagName, getElementsByTagNameNS, getImplementation, getInputEncoding, getStrictErrorChecking, getXmlEncoding, getXmlStandalone, getXmlVersion, importNode, normalizeDocument, renameNode, setDocumentURI, setStrictErrorChecking, setXmlStandalone, setXmlVersion`

    - ### Methods inherited from interface org.w3c.dom.Node

      `appendChild, cloneNode, compareDocumentPosition, getAttributes, getBaseURI, getChildNodes, getFeature, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getTextContent, getUserData, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, removeChild, replaceChild, setNodeValue, setPrefix, setTextContent, setUserData`

- - ### Constructor Detail

    - #### SOAPPart

          public SOAPPart()

  - ### Method Detail

    - #### getEnvelope

          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:
        the `SOAPEnvelope` object for this `SOAPPart` object
      Throws:
        `SOAPException` - if there is a SOAP error

    - #### getContentId

          public String getContentId()

      Retrieves the value of the MIME header whose name is "Content-Id".
      Returns:
        a `String` giving the value of the MIME header named "Content-Id"
      See Also:
        `setContentId(java.lang.String)`

    - #### getContentLocation

          public String getContentLocation()

      Retrieves the value of the MIME header whose name is "Content-Location".
      Returns:
        a `String` giving the value of the MIME header whose name is "Content-Location"
      See Also:
        `setContentLocation(java.lang.String)`

    - #### setContentId

          public void setContentId(String contentId)

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

    - #### setContentLocation

          public void setContentLocation(String contentLocation)

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

    - #### removeMimeHeader

          public abstract void removeMimeHeader(String header)

      Removes all MIME headers that match the given name.
      Parameters:
        `header` - a `String` giving the name of the MIME header(s) to be removed

    - #### removeAllMimeHeaders

          public abstract void removeAllMimeHeaders()

      Removes all the `MimeHeader` objects for this `SOAPEnvelope` object.

    - #### getMimeHeader

          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` - the name of the header; example: "Content-Type"
      Returns:
        a `String` array giving all the values for the specified header
      See Also:
        `setMimeHeader(java.lang.String, java.lang.String)`

    - #### setMimeHeader

          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` - a `String` giving the header name for which to search
        `value` - 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.
      Throws:
        `IllegalArgumentException` - if there was a problem with the specified mime header name or value
        `IllegalArgumentException` - if there was a problem with the specified mime header name or value
      See Also:
        `getMimeHeader(java.lang.String)`

    - #### addMimeHeader

          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` - a `String` giving the header name
        `value` - a `String` giving the value to be set or added
      Throws:
        `IllegalArgumentException` - if there was a problem with the specified mime header name or value

    - #### getAllMimeHeaders

          public abstract Iterator<MimeHeader> getAllMimeHeaders()

      Retrieves all the headers for this `SOAPPart` object as an iterator over the `MimeHeader` objects.
      Returns:
        an `Iterator` object with all of the Mime headers for this `SOAPPart` object

    - #### getMatchingMimeHeaders

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

      Retrieves all `MimeHeader` objects that match a name in the given array.
      Parameters:
        `names` - a `String` 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, returned as an `Iterator` object

    - #### getNonMatchingMimeHeaders

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

      Retrieves all `MimeHeader` objects whose name does not match a name in the given array.
      Parameters:
        `names` - a `String` array with the name(s) of the MIME headers not to be returned
      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.

    - #### setContent

          public abstract void setContent(Source source)
                                   throws SOAPException

      Sets the content of the `SOAPEnvelope` object with the data from the given `Source` object.
      Parameters:
        `source` - `javax.xml.transform.Source` object with the data to be set
      Throws:
        `SOAPException` - if there is a problem in setting the source
      See Also:
        `getContent()`

    - #### getContent

          public abstract Source getContent()
                                     throws SOAPException

      Returns the content of the SOAPEnvelope as a JAXP `Source` object.
      Returns:
        the content as a `javax.xml.transform.Source` object
      Throws:
        `SOAPException` - if the implementation cannot convert the specified `Source` object
      See Also:
        `setContent(javax.xml.transform.Source)`