javax.xml.bind.attachment

## Class AttachmentUnmarshaller

- java.lang.Object
- - javax.xml.bind.attachment.AttachmentUnmarshaller

-     public abstract class AttachmentUnmarshaller
      extends Object

  Enables JAXB unmarshalling of a root document containing optimized binary data formats.

  This API enables an efficient cooperative processing of optimized binary data formats between a JAXB 2.0 implementation and MIME-based package processor (MTOM/XOP and WS-I AP 1.0). JAXB unmarshals the body of a package, delegating the understanding of the packaging format being used to a MIME-based package processor that implements this abstract class.

  This abstract class identifies if a package requires XOP processing, `isXOPPackage()` and provides retrieval of binary content stored as attachments by content-id.

  ## Identifying the content-id, cid, to pass to `getAttachment*(String cid)`

  - For XOP processing, the infoset representation of the cid is described in step 2a in Section 3.2 Interpreting XOP Packages
  - For WS-I AP 1.0, the cid is identified as an element or attribute of type `ref:swaRef` specified in Section 4.4 Referencing Attachments from the SOAP Envelope
  Since:
    JAXB 2.0
  Author:
    Marc Hadley, Kohsuke Kawaguchi, Joseph Fialli
  See Also:
    `Unmarshaller.setAttachmentUnmarshaller(AttachmentUnmarshaller)`, XML-binary Optimized Packaging, WS-I Attachments Profile Version 1.0., Describing Media Content of Binary Data in XML

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `AttachmentUnmarshaller()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract byte[]` | `getAttachmentAsByteArray(String cid)` Retrieve the attachment identified by content-id, `cid`, as a `byte[]`
    `abstract DataHandler` | `getAttachmentAsDataHandler(String cid)` Lookup MIME content by content-id, `cid`, and return as a `DataHandler`.
    `boolean` | `isXOPPackage()` Read-only property that returns true if JAXB unmarshaller needs to perform XOP processing.

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

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

- - ### Constructor Detail

    - #### AttachmentUnmarshaller

          public AttachmentUnmarshaller()

  - ### Method Detail

    - #### getAttachmentAsDataHandler

          public abstract DataHandler getAttachmentAsDataHandler(String cid)

      Lookup MIME content by content-id, `cid`, and return as a `DataHandler`.

      The returned `DataHandler` instance must be configured to meet the following required mapping constaint.

      Required Mappings between MIME and Java Types
      MIME Type | Java Type
      --- | ---
      `DataHandler.getContentType()` | `instanceof DataHandler.getContent()`
      image/gif | java.awt.Image
      image/jpeg | java.awt.Image
      text/xml or application/xml | javax.xml.transform.Source

      Note that it is allowable to support additional mappings.
      Parameters:
        `cid` - It is expected to be a valid lexical form of the XML Schema `xs:anyURI` datatype. If ``isXOPPackage()` ==true`, it must be a valid URI per the `cid:` URI scheme (see RFC 2387)
      Returns:
        a `DataHandler` that represents the MIME attachment.
      Throws:
        `IllegalArgumentException` - if the attachment for the given cid is not found.

    - #### getAttachmentAsByteArray

          public abstract byte[] getAttachmentAsByteArray(String cid)

      Retrieve the attachment identified by content-id, `cid`, as a `byte[]`

      .
      Parameters:
        `cid` - It is expected to be a valid lexical form of the XML Schema `xs:anyURI` datatype. If ``isXOPPackage()` ==true`, it must be a valid URI per the `cid:` URI scheme (see RFC 2387)
      Returns:
        byte[] representation of attachment identified by cid.
      Throws:
        `IllegalArgumentException` - if the attachment for the given cid is not found.

    - #### isXOPPackage

          public boolean isXOPPackage()

      Read-only property that returns true if JAXB unmarshaller needs to perform XOP processing.

      This method returns `true` when the constraints specified in Identifying XOP Documents are met. This value must not change during the unmarshalling process.

      Returns:
        true when MIME context is a XOP Document.

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