AttachmentUnmarshaller (Java SE 10 & JDK 10 )
Keywords: javax.xml.bind.attachment.AttachmentUnmarshaller class

Module java.xml.bind
Package 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:
    1.6, JAXB 2.0
  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 | Description
    --- | ---
    `AttachmentUnmarshaller()` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | 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 declared in 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.