public abstract class AttachmentMarshaller
extends java.lang.Object
Enable Jakarta XML Binding marshalling to optimize storage of binary data.
This API enables an efficient cooperative creation of optimized binary data formats between a Jakarta XML Binding marshalling process and a MIME-based package processor. A Jakarta XML Binding 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 Jakarta XML Binding property related to
{http://ws-i.org/profiles/basic/1.1/xsd}swaRef.
Marshaller.setAttachmentMarshaller(AttachmentMarshaller)
,
XML-binary Optimized Packaging,
WS-I Attachments Profile Version 1.0.Constructor and Description |
---|
AttachmentMarshaller() |
Modifier and Type | Method and Description |
---|---|
abstract java.lang.String |
addMtomAttachment(byte[] data,
int offset,
int length,
java.lang.String mimeType,
java.lang.String elementNamespace,
java.lang.String elementLocalName)
Consider binary
data for optimized binary storage as an attachment. |
abstract java.lang.String |
addMtomAttachment(DataHandler data,
java.lang.String elementNamespace,
java.lang.String elementLocalName)
Consider MIME content
data for optimized binary storage as an attachment. |
abstract java.lang.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 Jakarta XML Binding marshaller should enable XOP creation.
|
public abstract java.lang.String addMtomAttachment(DataHandler data, java.lang.String elementNamespace, java.lang.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.
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.data
.
Otherwise, null if the attachment was not added and should instead be inlined in the message.public abstract java.lang.String addMtomAttachment(byte[] data, int offset, int length, java.lang.String mimeType, java.lang.String elementNamespace, java.lang.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.
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.lengthlength
- The number of bytes to be read from the given array;
must be non-negative and no larger than array.lengthmimeType
- 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
- 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.data
or null if data should be inlined.addMtomAttachment(DataHandler, String, String)
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.
public abstract java.lang.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.
data
- represents the data to be attached. Must be non-null.