AttachmentMarshaller (Java EE 5)

启用 JAXB 编组来优化二进制数据存储。

此 API 支持 JAXB 编组过程与基于 MIME 的包处理器之间的协作，有效地创建优化的二进制数据格式。JAXB 实现对基于 MIME 的包的根正文进行编组，将可引用 MIME 部分的创建委托给实现此抽象的基于 MIME 的包处理器。

当 #isXOPPackage() 为 true 时启用 XOP 处理。有关详细信息，请参阅 #addMtomAttachment(DataHandler, String, String)。

#addSwaRefAttachment(DataHandler) 支持 WS-I Attachment Profile 1.0，编组程序针对每个与 {http://ws-i.org/profiles/basic/1.1/xsd}swaRef 相关的 JAXB 属性调用该方法。

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.

public AttachmentMarshaller()

英文文档：

AttachmentMarshaller

public AttachmentMarshaller()

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

将用于优化二进制存储的 MIME 内容 data 作为附件。

正如 Creating XOP Packages 中的步骤 3 所述，当 #isXOPPackage() 为 true 时，JAXB 编组过程针对每个数据类型为 "base64Binary" 的元素调用此方法。

方法实现程序决定是将 data 单独附加还是作为 base64Binary 数据内嵌。如果实现选择将二进制数据存储作为 MIME 的一部分进行优化，则实现负责将 data 附加到基于 MIME 的包中，然后分配一个唯一的内容 id（即 cid），用来标识 MIME 消息中的 MIME 部分。此方法返回 cid，cid 使 JAXB 编组程序能够编组一个引用该 cid 的 XOP 元素，而不是编组二进制数据。当该方法返回 null 时，JAXB 编组程序将 data 作为 base64binary 数据内嵌。

此方法的调用程序要求满足以下约束条件。如果包含 data 的元素 infoset 项具有属性 xmime:contentType，或者代表 data 的 JAXB 属性/字段使用已知的 MIME 类型进行注解，则 data.getContentType() 应该被设置为 MIME 类型。

elementNamespace 和 elementLocalName 参数提供包含二进制数据的上下文。基于 MIME 的包处理器可以使用此信息，以确定二进制数据应该被内嵌还是作为附件优化。

data	表示将被附加的数据。必须为非 null。
elementNamespace	封装 base64Binary 数据的元素名称空间 URI。可以为空但不能为 null。
elementLocalName	元素的本地名称。始终是非 null 的有效字符串。
return	一个有效的内容 id URI（参见 RFC 2387），它标识包含 data 的附件。如果没有添加附件，而是应该内嵌在消息中，则返回 null。
See also	XML-binary Optimized Packaging, Describing Media Content of Binary Data in XML

英文文档：

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 datais 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

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

将用于优化二进制存储的二进制 data 作为附件。

由于内容类型未知，所以附件的 MIME 内容类型必须设置为“application/octet-stream”。

elementNamespace 和 elementLocalName 参数提供包含二进制数据的上下文。基于 MIME 的包处理器可以使用此信息，以确定二进制数据应该被内嵌，还是作为附件优化。

data	表示将被附加的数据。必须为非 null。实际数据区域由 (data,offset,length) 元组指定。
offset	要读取的第一个字节在数组中的偏移量；必须为非负且不大于 array.length。
length	要从给定数组读取的字节数；必须为非负且不大于 array.length。
mimeType	如果数据具有 JAXB 已知的关联 MIME 类型，则使用此参数传递。如果所有类型未知，则使用“application/octet-stream”。此参数不可以为 null。
elementNamespace	封装 base64Binary 数据的元素名称空间 URI。可以为空但不能为 null。
elementLocalName	元素的本地名称。始终是非 null 的有效字符串。
return	包含 data 的附件的内容 id URI（即 cid）；如果数据应该内嵌，则返回 null。
See also	addMtomAttachment(DataHandler, String, String)

英文文档：

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)

public boolean isXOPPackage()

只读属性，如果 JAXB 编组器应该启用 XOP 创建，则返回 true。

编组过程中此值不得更改。如果此值为 true，则当编组过程遇到适当的二进制数据类型时，将调用 addMtomAttachment(...) 方法。

如果此值为 true 且要编组的 XML 内容违反 Creating XOP Pacakgeshttp://www.w3.org/TR/2005/REC-xop10-20050125/#creating_xop_packages 中的步骤 1，则 Marshaller.marshal() 必须抛出 IllegalStateException。步骤 1 中写道：“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”。

若此方法返回 true，并且在编组过程中至少有一次调用 addMtomAttachment(...) 返回内容 id，则根据 Creating XOP Pacakges 中步骤 5 的描述，基于 MIME 的包处理器必须使用 application/xop+xml 媒体类型来标记根部分。

return

当 MIME 上下文是一个 XOP 包时，返回 true。

英文文档：

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.

abstract public String addSwaRefAttachment(DataHandler data)

将 MIME data 作为附件添加，并返回附件的内容 id（即 cid）。

JAXB 编组过程针对每个归类为 {http://ws-i.org/profiles/basic/1.1/xsd}swaRef 的元素/属性调用此方法。实现此方法的基于 MIME 的包处理器负责将指定的数据附加到 MIME 附件中，并生成一个内容 id（即 cid），用来唯一地标识基于 MIME 的包内的附件。

调用程序将返回内容 id（即 cid）插入正在编组的 XML 内容中。

data	表示将被附加的数据。必须为非 null。
return	必须为用作 cid 的有效 URI。必须满足 WS-I Attachments Profile Version 1.0 的一致性要求 R2928。

英文文档：

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 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.