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
`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(javax.activation.DataHandler data, String elementNamespace, String elementLocalName)` Consider MIME content `data` for optimized binary storage as an attachment.
`abstract String` `addSwaRefAttachment(javax.activation.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(javax.activation.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(javax.activation.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 © 2004-2011 Oracle