## javax.xml.soap
Class AttachmentPart

    java.lang.Object
      |
      +--javax.xml.soap.AttachmentPart

Direct Known Subclasses:
  AttachmentPart

public abstract class AttachmentPart
extends java.lang.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
`AttachmentPart()`

Method Summary
`abstract void` `addMimeHeader(java.lang.String name, java.lang.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 java.util.Iterator` `getAllMimeHeaders()` Retrieves all the headers for this `AttachmentPart` object as an iterator over the `MimeHeader` objects.
`abstract java.lang.Object` `getContent()` Gets the content of this `AttachmentPart` object as a Java object.
`java.lang.String` `getContentId()` Gets the value of the MIME header whose name is "Content-Id".
`java.lang.String` `getContentLocation()` Gets the value of the MIME header "Content-Location".
`java.lang.String` `getContentType()` Gets the value of the MIME header "Content-Type".
`abstract javax.activation.DataHandler` `getDataHandler()` Gets the `DataHandler` object for this `AttachmentPart` object.
`abstract java.util.Iterator` `getMatchingMimeHeaders(java.lang.String[] names)` Retrieves all `MimeHeader` objects that match a name in the given array.
`abstract java.lang.String[]` `getMimeHeader(java.lang.String name)` Gets all the values of the header identified by the given `String`.
`abstract java.util.Iterator` `getNonMatchingMimeHeaders(java.lang.String[] names)` Retrieves all `MimeHeader` objects whose name does not match a name in the given array.
`abstract int` `getSize()` Returns the number of bytes in this `AttachmentPart` object.
`abstract void` `removeAllMimeHeaders()` Removes all the MIME header entries.
`abstract void` `removeMimeHeader(java.lang.String header)` Removes all MIME headers that match the given name.
`abstract void` `setContent(java.lang.Object object, java.lang.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(java.lang.String contentId)` Sets the MIME header "Content-Id" with the given value.
`void` `setContentLocation(java.lang.String contentLocation)` Sets the MIME header "Content-Location" with the given value.
`void` `setContentType(java.lang.String contentType)` Sets the MIME header "Content-Type" with the given value.
`abstract void` `setDataHandler(javax.activation.DataHandler datahandler)` Sets the given `DataHandler` object as the data handler for this `AttachmentPart` object.
`abstract void` `setMimeHeader(java.lang.String name, java.lang.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.

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 java.lang.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 JAXM-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.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

### setContent

    public abstract void setContent(java.lang.Object object,
                                    java.lang.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:
    `java.lang.IllegalArgumentException` - 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()`

### getDataHandler

    public abstract javax.activation.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(javax.activation.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` - `DataHandler` object to be set
  Throws:
    `java.lang.IllegalArgumentException` - if there was a problem with the specified `DataHandler` object

### getContentId

    public java.lang.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 java.lang.String getContentLocation()

  Gets the value of the MIME header "Content-Location".

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

### getContentType

    public java.lang.String getContentType()

  Gets the value of the MIME header "Content-Type".

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

### setContentId

    public void setContentId(java.lang.String contentId)

  Sets the MIME header "Content-Id" with the given value.

  Parameters:
    `contentId` - a `String` giving the value of the "Content-Id" header
  Throws:
    `java.lang.IllegalArgumentException` - if there was a problem with the specified `contentId` value
  See Also:
    `getContentId()`

### setContentLocation

    public void setContentLocation(java.lang.String contentLocation)

  Sets the MIME header "Content-Location" with the given value.

  Parameters:
    `contentLocation` - a `String` giving the value of the "Content-Location" header
  Throws:
    `java.lang.IllegalArgumentException` - if there was a problem with the specified content location

### setContentType

    public void setContentType(java.lang.String contentType)

  Sets the MIME header "Content-Type" with the given value.

  Parameters:
    `contentType` - a `String` giving the value of the "Content-Type" header
  Throws:
    `java.lang.IllegalArgumentException` - if there was a problem with the specified content type

### removeMimeHeader

    public abstract void removeMimeHeader(java.lang.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 java.lang.String[] getMimeHeader(java.lang.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(java.lang.String name,
                                       java.lang.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:
    `java.lang.IllegalArgumentException` - if there was a problem with the specified mime header name or value

### addMimeHeader

    public abstract void addMimeHeader(java.lang.String name,
                                       java.lang.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:
    `java.lang.IllegalArgumentException` - if there was a problem with the specified mime header name or value

### getAllMimeHeaders

    public abstract java.util.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 java.util.Iterator getMatchingMimeHeaders(java.lang.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 java.util.Iterator getNonMatchingMimeHeaders(java.lang.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 © 2003 Apache Web Services Project. All Rights Reserved.