javax.xml.soap

## Class AttachmentPart

- java.lang.Object
- - javax.xml.soap.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.

  1. It must conform to MIME [RFC2045] standards
  2. It MUST contain content
  3. The header portion MUST include the following header:
     - `Content-Type`
       This header identifies the type of data in the content of an `AttachmentPart` 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 Summary

    Constructors
    Constructor and Description
    `AttachmentPart()`

  - ### Method Summary

    Methods
    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`.

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

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

- - ### Constructor Detail

    - #### AttachmentPart

          public AttachmentPart()

  - ### Method Detail

    - #### getSize

          public abstract int getSize()
                               throws SOAPException

      Returns the number of bytes in this `AttachmentPart` 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 this `AttachmentPart` object. The MIME header portion is left untouched.

    - #### getContent

          public abstract Object getContent()
                                     throws SOAPException

      Gets the content of this `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.

      Returns:
        a Java object with the content of this `AttachmentPart` object
      Throws:
        `SOAPException` - if there is no content set into this `AttachmentPart` object or if there was a data transformation error

    - #### getRawContent

          public abstract InputStream getRawContent()
                                             throws SOAPException

      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`.

      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 the `AttachmentPart` can be accessed.
      Throws:
        `SOAPException` - if there is no content set into this `AttachmentPart` object or if there was a data transformation error.
      Since:
        SAAJ 1.3
      See Also:
        `getRawContentBytes()`

    - #### getRawContentBytes

          public abstract byte[] getRawContentBytes()
                                             throws SOAPException

      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`.
      Returns:
        a `byte[]` array containing the raw data of the `AttachmentPart`.
      Throws:
        `SOAPException` - if there is no content set into this `AttachmentPart` object or if there was a data transformation error.
      Since:
        SAAJ 1.3

    - #### getBase64Content

          public abstract InputStream getBase64Content()
                                                throws SOAPException

      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.
      Returns:
        an `InputStream` from which the Base64 encoded `AttachmentPart` can be read.
      Throws:
        `SOAPException` - if there is no content set into this `AttachmentPart` object or if there was a data transformation error.
      Since:
        SAAJ 1.3

    - #### setContent

          public 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. 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.
      Parameters:
        `object` - the Java object that makes up the content for this attachment part
        `contentType` - 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 no `DataContentHandler` object for this content object
      See Also:
        `getContent()`

    - #### setRawContent

          public abstract void setRawContent(InputStream content,
                           String contentType)
                                      throws SOAPException

      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`.

      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 part
        `contentType` - the value to set into the `Content-Type` header
      Throws:
        `SOAPException` - if an there is an error in setting the content
        `NullPointerException` - if `content` is null
      Since:
        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 the `byte[]` array `content` and sets the value of the `Content-Type` header to the value contained in `contentType`.
      Parameters:
        `content` - the raw data to add to the attachment part
        `contentType` - the value to set into the `Content-Type` header
        `offset` - the offset in the byte array of the content
        `len` - the number of bytes that form the content
      Throws:
        `SOAPException` - if an there is an error in setting the content or content is null
      Since:
        SAAJ 1.3

    - #### setBase64Content

          public abstract void setBase64Content(InputStream content,
                              String contentType)
                                         throws SOAPException

      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.

      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 part
        `contentType` - the value to set into the `Content-Type` header
      Throws:
        `SOAPException` - if an there is an error in setting the content
        `NullPointerException` - if `content` is null
      Since:
        SAAJ 1.3

    - #### getDataHandler

          public abstract DataHandler getDataHandler()
                                              throws SOAPException

      Gets the `DataHandler` object for this `AttachmentPart` object.
      Returns:
        the `DataHandler` object associated with this `AttachmentPart` object
      Throws:
        `SOAPException` - if there is no data in this `AttachmentPart` object

    - #### setDataHandler

          public abstract void setDataHandler(DataHandler dataHandler)

      Sets the given `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.
      Parameters:
        `dataHandler` - the `DataHandler` object to be set
      Throws:
        `IllegalArgumentException` - if there was a problem with the specified `DataHandler` object

    - #### getContentId

          public String getContentId()

      Gets the value of the MIME header whose name is "Content-ID".
      Returns:
        a `String` giving the value of the "Content-ID" header or `null` if there is none
      See Also:
        `setContentId(java.lang.String)`

    - #### getContentLocation

          public String getContentLocation()

      Gets the value of the MIME header whose name is "Content-Location".
      Returns:
        a `String` giving the value of the "Content-Location" header or `null` if there is none

    - #### getContentType

          public String getContentType()

      Gets the value of the MIME header whose name is "Content-Type".
      Returns:
        a `String` giving the value of the "Content-Type" header or `null` if there is none

    - #### setContentId

          public void setContentId(String contentId)

      Sets the MIME header whose name is "Content-ID" with the given value.
      Parameters:
        `contentId` - a `String` giving the value of the "Content-ID" header
      Throws:
        `IllegalArgumentException` - if there was a problem with the specified `contentId` value
      See Also:
        `getContentId()`

    - #### setContentLocation

          public void setContentLocation(String contentLocation)

      Sets the MIME header whose name is "Content-Location" with the given value.
      Parameters:
        `contentLocation` - a `String` giving the value of the "Content-Location" header
      Throws:
        `IllegalArgumentException` - if there was a problem with the specified content location

    - #### setContentType

          public void setContentType(String contentType)

      Sets the MIME header whose name is "Content-Type" with the given value.
      Parameters:
        `contentType` - a `String` giving the value of the "Content-Type" header
      Throws:
        `IllegalArgumentException` - if there was a problem with the specified content type

    - #### removeMimeHeader

          public abstract void removeMimeHeader(String header)

      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

          public abstract String[] getMimeHeader(String name)

      Gets all the values of the header identified by the given `String`.
      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

          public 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. This method also removes all matching headers but the first.

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

      Parameters:
        `name` - a `String` giving the name of the header for which to search
        `value` - a `String` 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

          public abstract void addMimeHeader(String name,
                           String value)

      Adds a MIME header with the specified name and value to this `AttachmentPart` object.

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

      Parameters:
        `name` - a `String` giving the name of the header to be added
        `value` - a `String` 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

          public abstract Iterator getAllMimeHeaders()

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

    - #### getMatchingMimeHeaders

          public abstract Iterator 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 as an `Iterator` object

    - #### getNonMatchingMimeHeaders

          public abstract Iterator 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 `AttachmentPart` object except those that match one of the names in the given array. The nonmatching MIME headers are returned as an `Iterator` object.

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.