javax.xml.bind.attachment

## Class AttachmentMarshaller

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

-     public abstract class AttachmentMarshaller
      extends Object

  Enable JAXB marshalling to optimize storage of binary data.

  This API enables an efficient cooperative creation of optimized binary data formats between a JAXB marshalling process and a MIME-based package processor. A JAXB implementation marshals the root body of a MIME-based package, delegating the creation of referenceable MIME parts to the MIME-based package processor that implements this abstraction.

  XOP processing is enabled when `isXOPPackage()` is true. See `addMtomAttachment(DataHandler, String, String)` for details.

  WS-I Attachment Profile 1.0 is supported by `addSwaRefAttachment(DataHandler)` being called by the marshaller for each JAXB property related to {http://ws-i.org/profiles/basic/1.1/xsd}swaRef.

  Since:
    JAXB 2.0
  Author:
    Marc Hadley, Kohsuke Kawaguchi, Joseph Fialli
  See Also:
    `Marshaller.setAttachmentMarshaller(AttachmentMarshaller)`, XML-binary Optimized Packaging, WS-I Attachments Profile Version 1.0.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `AttachmentMarshaller()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract String` | `addMtomAttachment(byte[] data, int offset, int length, String mimeType, String elementNamespace, String elementLocalName)` Consider binary `data` for optimized binary storage as an attachment.
    `abstract String` | `addMtomAttachment(DataHandler data, String elementNamespace, String elementLocalName)` Consider MIME content `data` for optimized binary storage as an attachment.
    `abstract String` | `addSwaRefAttachment(DataHandler data)` Add MIME `data` as an attachment and return attachment's content-id, cid.
    `boolean` | `isXOPPackage()` Read-only property that returns true if JAXB marshaller should enable XOP creation.

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

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

- - ### Constructor Detail

    - #### AttachmentMarshaller

          public AttachmentMarshaller()

  - ### Method Detail

    - #### addMtomAttachment

          public abstract String addMtomAttachment(DataHandler data,
                                 String elementNamespace,
                                 String elementLocalName)

      Consider MIME content `data` for optimized binary storage as an attachment.

      This method is called by JAXB marshal process when `isXOPPackage()` is `true`, for each element whose datatype is "base64Binary", as described in Step 3 in Creating XOP Packages.

      The method implementor determines whether `data` shall be attached separately or inlined as base64Binary data. If the implementation chooses to optimize the storage of the binary data as a MIME part, it is responsible for attaching `data` to the MIME-based package, and then assigning an unique content-id, cid, that identifies the MIME part within the MIME message. This method returns the cid, which enables the JAXB marshaller to marshal a XOP element that refers to that cid in place of marshalling the binary data. When the method returns null, the JAXB marshaller inlines `data` as base64binary data.

      The caller of this method is required to meet the following constraint. If the element infoset item containing `data` has the attribute `xmime:contentType` or if the JAXB property/field representing `data`is annotated with a known MIME type, `data.getContentType()` should be set to that MIME type.

      The `elementNamespace` and `elementLocalName` parameters provide the context that contains the binary data. This information could be used by the MIME-based package processor to determine if the binary data should be inlined or optimized as an attachment.

      Parameters:
        `data` - represents the data to be attached. Must be non-null.
        `elementNamespace` - the namespace URI of the element that encloses the base64Binary data. Can be empty but never null.
        `elementLocalName` - The local name of the element. Always a non-null valid string.
      Returns:
        a valid content-id URI (see RFC 2387) that identifies the attachment containing `data`. Otherwise, null if the attachment was not added and should instead be inlined in the message.
      See Also:
        XML-binary Optimized Packaging, Describing Media Content of Binary Data in XML

    - #### addMtomAttachment

          public abstract String addMtomAttachment(byte[] data,
                                 int offset,
                                 int length,
                                 String mimeType,
                                 String elementNamespace,
                                 String elementLocalName)

      Consider binary `data` for optimized binary storage as an attachment.

      Since content type is not known, the attachment's MIME content type must be set to "application/octet-stream".

      The `elementNamespace` and `elementLocalName` parameters provide the context that contains the binary data. This information could be used by the MIME-based package processor to determine if the binary data should be inlined or optimized as an attachment.

      Parameters:
        `data` - represents the data to be attached. Must be non-null. The actual data region is specified by `(data,offset,length)` tuple.
        `offset` - The offset within the array of the first byte to be read; must be non-negative and no larger than array.length
        `length` - The number of bytes to be read from the given array; must be non-negative and no larger than array.length
        `mimeType` - If the data has an associated MIME type known to JAXB, that is passed as this parameter. If none is known, "application/octet-stream". This parameter may never be null.
        `elementNamespace` - the namespace URI of the element that encloses the base64Binary data. Can be empty but never null.
        `elementLocalName` - The local name of the element. Always a non-null valid string.
      Returns:
        content-id URI, cid, to the attachment containing `data` or null if data should be inlined.
      See Also:
        `addMtomAttachment(DataHandler, String, String)`

    - #### isXOPPackage

          public boolean isXOPPackage()

      Read-only property that returns true if JAXB marshaller should enable XOP creation.

      This value must not change during the marshalling process. When this value is true, the `addMtomAttachment(...)` method is invoked when the appropriate binary datatypes are encountered by the marshal process.

      Marshaller.marshal() must throw IllegalStateException if this value is `true` and the XML content to be marshalled violates Step 1 in Creating XOP Pacakges http://www.w3.org/TR/2005/REC-xop10-20050125/#creating_xop_packages. "Ensure the Original XML Infoset contains no element information item with a [namespace name] of "http://www.w3.org/2004/08/xop/include" and a [local name] of Include"

      When this method returns true and during the marshal process at least one call to `addMtomAttachment(...)` returns a content-id, the MIME-based package processor must label the root part with the application/xop+xml media type as described in Step 5 of Creating XOP Pacakges.

      Returns:
        true when MIME context is a XOP Package.

    - #### addSwaRefAttachment

          public abstract String addSwaRefAttachment(DataHandler data)

      Add MIME `data` as an attachment and return attachment's content-id, cid.

      This method is called by JAXB marshal process for each element/attribute typed as {http://ws-i.org/profiles/basic/1.1/xsd}swaRef. The MIME-based package processor implementing this method is responsible for attaching the specified data to a MIME attachment, and generating a content-id, cid, that uniquely identifies the attachment within the MIME-based package.

      Caller inserts the returned content-id, cid, into the XML content being marshalled.

      Parameters:
        `data` - represents the data to be attached. Must be non-null.
      Returns:
        must be a valid URI used as cid. Must satisfy Conformance Requirement R2928 from WS-I Attachments Profile Version 1.0.

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