javax.xml.bind.attachment
类 AttachmentMarshaller

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

public abstract class AttachmentMarshaller
     

      extends 
      Object
     

启用 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 属性调用该方法。

从以下版本开始：

JAXB 2.0

另请参见：

Marshaller.setAttachmentMarshaller(AttachmentMarshaller), XML-binary Optimized Packaging, WS-I Attachments Profile Version 1.0.

AttachmentMarshaller

public AttachmentMarshaller()

addMtomAttachment

public abstract 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 的有效字符串。

返回：

一个有效的内容 id URI（参见 RFC 2387），它标识包含 data 的附件。如果没有添加附件，而是应该内嵌在消息中，则返回 null。

另请参见：

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)

将用于优化二进制存储的二进制 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 的有效字符串。

返回：

包含 data 的附件的内容 id URI（即 cid）；如果数据应该内嵌，则返回 null。

另请参见：

addMtomAttachment(DataHandler, String, String)

isXOPPackage

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 媒体类型来标记根部分。

返回：

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

addSwaRefAttachment

public abstract 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。

返回：

必须为用作 cid 的有效 URI。必须满足 WS-I Attachments Profile Version 1.0 的一致性要求 R2928。