Jakarta XML Binding API 4.0.0 · jakarta.xml.bind.attachment.AttachmentMarshaller

Access	Constructor and Description
protected	AttachmentMarshaller() Do-nothing constructor for the derived classes.

Method Summary

Modifier and Type	Method and Description
public abstract 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. addMtomAttachment(DataHandler represents the data to be attached. Must be non-null. data, String the namespace URI of the element that encloses the base64Binary data. Can be empty but never null. elementNamespace, String The local name of the element. Always a non-null valid string. elementLocalName) Consider MIME content `data` for optimized binary storage as an attachment.
public abstract String	Returns: content-id URI, cid, to the attachment containing `data` or null if data should be inlined. addMtomAttachment(byte[] represents the data to be attached. Must be non-null. The actual data region is specified by `(data,offset,length)` tuple. data, int The offset within the array of the first byte to be read; must be non-negative and no larger than array.length offset, int The number of bytes to be read from the given array; must be non-negative and no larger than array.length length, String If the data has an associated MIME type known to Jakarta XML Binding, that is passed as this parameter. If none is known, "application/octet-stream". This parameter may never be null. mimeType, String the namespace URI of the element that encloses the base64Binary data. Can be empty but never null. elementNamespace, String The local name of the element. Always a non-null valid string. elementLocalName) Consider binary `data` for optimized binary storage as an attachment.
public abstract String	Returns: must be a valid URI used as cid. Must satisfy Conformance Requirement R2928 from WS-I Attachments Profile Version 1.0. addSwaRefAttachment(DataHandler represents the data to be attached. Must be non-null. data) Add MIME `data` as an attachment and return attachment's content-id, cid.
public boolean	Returns: true when MIME context is a XOP Package. isXOPPackage() Read-only property that returns true if Jakarta XML Binding marshaller should enable XOP creation.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

AttachmentMarshaller	back to summary
protected AttachmentMarshaller() Do-nothing constructor for the derived classes.

Method Detail

addMtomAttachment back to summary

addMtomAttachment	back to summary
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 Jakarta XML Binding 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 Jakarta XML Binding marshaller to marshal a XOP element that refers to that cid in place of marshalling the binary data. When the method returns null, the Jakarta XML Binding 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 Jakarta XML Binding 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:DataHandler represents the data to be attached. Must be non-null. elementNamespace:String the namespace URI of the element that encloses the base64Binary data. Can be empty but never null. elementLocalName:String The local name of the element. Always a non-null valid string. Returns:String 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

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 Jakarta XML Binding 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 Jakarta XML Binding marshaller to marshal a XOP element that refers to that cid in place of marshalling the binary data. When the method returns null, the Jakarta XML Binding 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 Jakarta XML Binding 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:DataHandler: represents the data to be attached. Must be non-null.
elementNamespace:String: the namespace URI of the element that encloses the base64Binary data. Can be empty but never null.
elementLocalName:String: The local name of the element. Always a non-null valid string.

Returns:String

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.

addMtomAttachment back to summary

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

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".

Parameters

data:byte[]: represents the data to be attached. Must be non-null. The actual data region is specified by (data,offset,length) tuple.
offset:int: The offset within the array of the first byte to be read; must be non-negative and no larger than array.length
length:int: The number of bytes to be read from the given array; must be non-negative and no larger than array.length
mimeType:String: If the data has an associated MIME type known to Jakarta XML Binding, that is passed as this parameter. If none is known, "application/octet-stream". This parameter may never be null.
elementNamespace:String: the namespace URI of the element that encloses the base64Binary data. Can be empty but never null.
elementLocalName:String: The local name of the element. Always a non-null valid string.

Returns:String

content-id URI, cid, to the attachment containing data or null if data should be inlined.

addSwaRefAttachment back to summary

addSwaRefAttachment	back to summary
public abstract String addSwaRefAttachment(DataHandler data) Add MIME `data` as an attachment and return attachment's content-id, cid. This method is called by Jakarta XML Binding 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:DataHandler represents the data to be attached. Must be non-null. Returns:String must be a valid URI used as cid. Must satisfy Conformance Requirement R2928 from WS-I Attachments Profile Version 1.0.

public abstract String addSwaRefAttachment(DataHandler data)

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

This method is called by Jakarta XML Binding 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:DataHandler: represents the data to be attached. Must be non-null.

Returns:String

must be a valid URI used as cid. Must satisfy Conformance Requirement R2928 from WS-I Attachments Profile Version 1.0.

isXOPPackage back to summary

isXOPPackage	back to summary
public boolean isXOPPackage() Read-only property that returns true if Jakarta XML Binding 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:boolean true when MIME context is a XOP Package.

public boolean isXOPPackage()

Read-only property that returns true if Jakarta XML Binding 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:boolean: true when MIME context is a XOP Package.

public abstract Class AttachmentMarshaller

Constructor Summary

Method Summary

Constructor Detail

Method Detail