Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
`AttachmentPart()`

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Java™ Platform Standard Ed. 6
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2008 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.