spec/src/main/asciidoc/appH-binary_data.adoc - jaxb-api - Git at Google

 //
 // Copyright (c) 2020, 2021 Contributors to the Eclipse Foundation
 //

 [appendix]
 == Enhanced Binary Data Handling

 === Overview

 Optimized transmission of binary data as
 attachments is described by standards such as Soap [MTOM]/Xml-binary
 Optimized Packaging[XOP] and WS-I Attachment Profile 1.0 [WSIAP]. To
 optimally support these standards when JAXB databinding is used within a
 message passing environment, <<jakarta-xml-bind-attachments>>
 specifies an API that allows for an
 integrated, cooperative implementation of these standards between a
 MIME-based package processor and the Jakarta XML Binding unmarshal/marshal
 processes. An enhanced binding of MIME content to Java representation is
 specified in <<Binding MIME Binary Data>>.

 === Binding MIME Binary Data

 ==== Binary Data Schema Annotation

 As specified in [MIME], the XML Schema
 annotation attribute, `xmime:expectedContentTypes`, lists the expected
 MIME content-type(s) for element content whose type derives from the xsd
 binary datatypes, `xs:base64Binary` or `xs:hexBinary`.

 Jakarta XML Binding databinding recognizes this schema
 constraint to improve the binding of MIME type constrained binary data
 to Java representation. The `xmime:expectedContentType` attribute is
 allowed on type definitions deriving from binary datatypes and on
 element declarations with types that derive from binary datatypes. For
 Jakarta XML Binding binding purposes, the schema annotation,
 `xmime:expectedContentTypes` is evaluated for binding purposes for all
 cases EXCEPT when the annotation is on an element declaration with a
 named complex type definition. For that case, the
 `xmime:expectedContentTypes` annotation must be located directly within
 the scope of the complex type definition in order to impact the binding
 of the complex type definition’s simple binary content.

 ===== Binding Known Media Type

 When `@xmime:expectedContentTypes` schema
 annotation only refers to one MIME type, it is considered a known media
 type for the binary data. [MIME] does not require an `xmime:contentType`
 attribute to hold the dynamic mime type for the binary data for this
 case. JAXB binding can achieve an optimal binding for this case. The
 default MIME type to Java datatype are in <<a5119>>.

 .Default Binding for Known Media Type
 [[a5119]]
 [cols=",",options="header",]
 |===
 | MIME Type | Java Type
 | `image/gif` | `java.awt.Image`
 | `image/jpeg` | `java.awt.Image`
 | `text/xml` or `application/xml` | `javax.xml.transform.Source`
 | `_any other MIME types_` | `jakarta.activation.DataHandler`
 |===

 A JAXB program annotation element,
 `@XmlMimeType`, is generated to preserve the known media type for use
 at marshal time.

 .schema with a known media type
 [source,xml,indent="2"]
 ----
 <?xml version="1.0" ?>
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:tns="http://example.com/know-type"
            xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
            targetNamespace="http://example.com/know-type">
   <xs:import namespace="http://www.w3.org/2005/05/xmlmime"
              schemaLocation="http://www.w3.org/2005/05/xmlmime"/>
   <xs:element name="JPEGPicture"
               type="xs:base64binary"
               xmime:expectedContentTypes="image/jpeg"/>
 </xs:schema>
 ----

 .Jakarta XML Binding binding of Example 8-1
 [source,java,indent="4"]
 ----
 import java.awt.Image;
 @XmlRegistry
 class ObjectFactory {
     @XmlElementDecl(...)
     @XmlMimeType("image/jpeg")
     JAXBELement<Image> createJPEGPicture(Image value);
 }
 ----

 The `@XmlMimeType` annotation provides the
 MIME content type needed by Jakarta XML Binding Marshaller to specify the mime type
 to set `DataHandler.setContentType(String)`.

 .Schema for local element declaration annotated with known media type
 [[a5140]]
 [source,xml,indent="2"]
 ----
 <?xml version="1.0" ?>
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:tns="http://example.com/know-type"
            xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
            targetNamespace="http://example.com/know-type">
   <xs:import namespace="http://www.w3.org/2005/05/xmlmime"
              schemaLocation="http://www.w3.org/2005/05/xmlmime"/>
   <xs:complexType name="Item">
     <xs:sequence>
       <xs:element name="JPEGPicture"
                   type="xs:base64Binary"
                   xmime:expectedContentTypes="image/jpeg"/>
     </xs:sequence>
   </xs:complexType>
 </xs:schema>
 ----

 .Java Binding of <<a5140>>
 [source,java,indent="4"]
 ----
 import java.awt.Image;
 public class Item {
     @XmlMimeType("image/jpeg")
     Image getJPEGPicture();
     void setJPEGPicture(Image value);
 }
 ----

 ===== Binding Preferred Media Types

 If there are more than one mime type listed
 in `xmime:expectedContentTypes` or if there is one with a wildcard in
 it, the annotation specifies the Preferred Media Types and recommends
 that the binary data be simple content that has an attribute
 `xmime:contentType` that specifies which of the
 `xmime:expectedContentTypes` the binary data represents.

 Given that the exact media type is not known
 for this case, a Preferred Media Type binds to
 `jakarta.activation.DataHandler`. `DataHandler` has a property
 `get/setContentType` that should be kept synchronized with the value of
 the JAXB binding for the `xmime:contentType` attribute.

 ==== Binding WS-I Attachment Profile `ref:swaRef`

 An XML element or attribute with a type
 definition of `ref:swaRef` is bound to a JAXB property with base type of
 `jakarta.activation.DataHandler` and annotated with `@XmlAttachmentRef`.

 === jakarta.xml.bind.attachments

 The abstract classes `AttachmentUnmarshaller`
 and `AttachmentMarshaller` in package `jakarta.xml.bind.attachments` are
 intended to be implemented by a MIME-based package processor, such as
 Jakarta XML Web Services implementation, and are called during JAXB unmarshal/marshal.
 The JAXB unmarshal/marshal processes the root part of a MIME-based
 package, delegating knowledge of the overall package and its other parts
 to the `Attachment*` class implementations.

 ==== AttachmentUnmarshaller

 An implementation of this abstract class by a
 MIME-based package processor provides access to package-level
 information that is outside the scope of the JAXB unmarshal process. A
 MIME-based package processor registers its processing context with a
 Jakarta XML Binding processor using the method
 `setAttachmentUnmarshaller(AttachmentUnmarshaller)` of
 `jakarta.xml.bind.Unmarshaller`.

 Interactions between the Unmarshaller and the
 abstract class are summarized below. The javadoc specifies the details.

 [source,java,indent="4"]
 ----
 public abstract class AttachmentUnmarshaller {
 public boolean isXOPPackage();
 public abstract DataHandler getAttachmentAsDataHandler(String cid);
 public abstract byte[] getAttachmentAsByteArray(String cid);
 }
 ----

 The JAXB unmarshal process communicates with
 a MIME-based package processor via an instance of AttachmentUnmarshaller
 registered with the unmarshaller.
 <<opbin>> summarizes this
 processing.

 * MTOM/XOP processing during unmarshal: +
 When `isXOPPackage()` returns true, the unmarshaller replaces each XOP
 include element it encounters with MIME content returned by the
 appropriate `getAttachment*()` method.
 * WS-I AP processing: +
 Each element or attribute of type definition `ref:swaRef`, a content-id
 uri reference to binary data, is resolved by the unmarshal process by a
 call to the appropriate `getAttachment*()` method.

 ==== AttachmentMarshaller

 An `AttachmentMarshaller` instance is
 registered with a `jakarta.xml.bind.Marshaller` instance using the method
 `Marshaller.setAttachmentMarshaller()`.

 Interactions between the Marshaller and the
 abstract class is summarized below. See the javadoc for details.

 [source,java,indent="4"]
 ----
 public abstract class AttachmentMarshaller {
 public boolean isXOPPackage();
 public abstract String addMtomAttachment(
                     DataHandler data,
                     String elementNamespace,
                     String elementLocalName);
 public abstract String addMtomAttachment(
                     byte[] data,
                     String elementNamespace,
                     String elementLocalName);
 public abstract String addSwaRefAttachment(DataHandler data);
 }
 ----

 When an AttachmentMarshaller instance is
 registered with the Marshaller, the following processing takes place.

 * MTOM/XOP processing: +
 When `isXOPPackage()` is true and a JAXB property representing binary
 data is being marshalled, the method `addMtomAttachment(..)` is called
 to provide the MIME-based package processor the opportunity to decide to
 optimize or inline the binary data.
 +
 Note that the schema customization specified in
 <<inlinebinarydata-declaration>> can be
 used to declaratively disable XOP processing for binary data.
 * WS-I AP processing: +
 The `addSwaRefAttachment` method is called when marshalling content
 represented by a `ref:swaRef` type definition.
  +
 One can declaratively customize swaRef processing within a schema using
 schema customization @attachmentRef of <jaxb:property>, specified in
 <<usage-4>>.

 .JAXB marshal/unmarshalling of optimized binary content.
 [[opbin]]
 image::images/xmlb-23.svg[image]
	//
	// Copyright (c) 2020, 2021 Contributors to the Eclipse Foundation
	//

	[appendix]
	== Enhanced Binary Data Handling

	=== Overview

	Optimized transmission of binary data as
	attachments is described by standards such as Soap [MTOM]/Xml-binary
	Optimized Packaging[XOP] and WS-I Attachment Profile 1.0 [WSIAP]. To
	optimally support these standards when JAXB databinding is used within a
	message passing environment, <<jakarta-xml-bind-attachments>>
	specifies an API that allows for an
	integrated, cooperative implementation of these standards between a
	MIME-based package processor and the Jakarta XML Binding unmarshal/marshal
	processes. An enhanced binding of MIME content to Java representation is
	specified in <<Binding MIME Binary Data>>.

	=== Binding MIME Binary Data

	==== Binary Data Schema Annotation

	As specified in [MIME], the XML Schema
	annotation attribute, `xmime:expectedContentTypes`, lists the expected
	MIME content-type(s) for element content whose type derives from the xsd
	binary datatypes, `xs:base64Binary` or `xs:hexBinary`.

	Jakarta XML Binding databinding recognizes this schema
	constraint to improve the binding of MIME type constrained binary data
	to Java representation. The `xmime:expectedContentType` attribute is
	allowed on type definitions deriving from binary datatypes and on
	element declarations with types that derive from binary datatypes. For
	Jakarta XML Binding binding purposes, the schema annotation,
	`xmime:expectedContentTypes` is evaluated for binding purposes for all
	cases EXCEPT when the annotation is on an element declaration with a
	named complex type definition. For that case, the
	`xmime:expectedContentTypes` annotation must be located directly within
	the scope of the complex type definition in order to impact the binding
	of the complex type definition’s simple binary content.

	===== Binding Known Media Type

	When `@xmime:expectedContentTypes` schema
	annotation only refers to one MIME type, it is considered a known media
	type for the binary data. [MIME] does not require an `xmime:contentType`
	attribute to hold the dynamic mime type for the binary data for this
	case. JAXB binding can achieve an optimal binding for this case. The
	default MIME type to Java datatype are in <<a5119>>.

	.Default Binding for Known Media Type
	[[a5119]]
	[cols=",",options="header",]
	\|===
	\| MIME Type \| Java Type
	\| `image/gif` \| `java.awt.Image`
	\| `image/jpeg` \| `java.awt.Image`
	\| `text/xml` or `application/xml` \| `javax.xml.transform.Source`
	\| `_any other MIME types_` \| `jakarta.activation.DataHandler`
	\|===

	A JAXB program annotation element,
	`@XmlMimeType`, is generated to preserve the known media type for use
	at marshal time.

	.schema with a known media type
	[source,xml,indent="2"]
	----
	<?xml version="1.0" ?>
	<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
	xmlns:tns="http://example.com/know-type"
	xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
	targetNamespace="http://example.com/know-type">
	<xs:import namespace="http://www.w3.org/2005/05/xmlmime"
	schemaLocation="http://www.w3.org/2005/05/xmlmime"/>
	<xs:element name="JPEGPicture"
	type="xs:base64binary"
	xmime:expectedContentTypes="image/jpeg"/>
	</xs:schema>
	----

	.Jakarta XML Binding binding of Example 8-1
	[source,java,indent="4"]
	----
	import java.awt.Image;
	@XmlRegistry
	class ObjectFactory {
	@XmlElementDecl(...)
	@XmlMimeType("image/jpeg")
	JAXBELement<Image> createJPEGPicture(Image value);
	}
	----

	The `@XmlMimeType` annotation provides the
	MIME content type needed by Jakarta XML Binding Marshaller to specify the mime type
	to set `DataHandler.setContentType(String)`.

	.Schema for local element declaration annotated with known media type
	[[a5140]]
	[source,xml,indent="2"]
	----
	<?xml version="1.0" ?>
	<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
	xmlns:tns="http://example.com/know-type"
	xmlns:xmime="http://www.w3.org/2005/05/xmlmime"
	targetNamespace="http://example.com/know-type">
	<xs:import namespace="http://www.w3.org/2005/05/xmlmime"
	schemaLocation="http://www.w3.org/2005/05/xmlmime"/>
	<xs:complexType name="Item">
	<xs:sequence>
	<xs:element name="JPEGPicture"
	type="xs:base64Binary"
	xmime:expectedContentTypes="image/jpeg"/>
	</xs:sequence>
	</xs:complexType>
	</xs:schema>
	----

	.Java Binding of <<a5140>>
	[source,java,indent="4"]
	----
	import java.awt.Image;
	public class Item {
	@XmlMimeType("image/jpeg")
	Image getJPEGPicture();
	void setJPEGPicture(Image value);
	}
	----

	===== Binding Preferred Media Types

	If there are more than one mime type listed
	in `xmime:expectedContentTypes` or if there is one with a wildcard in
	it, the annotation specifies the Preferred Media Types and recommends
	that the binary data be simple content that has an attribute
	`xmime:contentType` that specifies which of the
	`xmime:expectedContentTypes` the binary data represents.

	Given that the exact media type is not known
	for this case, a Preferred Media Type binds to
	`jakarta.activation.DataHandler`. `DataHandler` has a property
	`get/setContentType` that should be kept synchronized with the value of
	the JAXB binding for the `xmime:contentType` attribute.

	==== Binding WS-I Attachment Profile `ref:swaRef`

	An XML element or attribute with a type
	definition of `ref:swaRef` is bound to a JAXB property with base type of
	`jakarta.activation.DataHandler` and annotated with `@XmlAttachmentRef`.

	=== jakarta.xml.bind.attachments

	The abstract classes `AttachmentUnmarshaller`
	and `AttachmentMarshaller` in package `jakarta.xml.bind.attachments` are
	intended to be implemented by a MIME-based package processor, such as
	Jakarta XML Web Services implementation, and are called during JAXB unmarshal/marshal.
	The JAXB unmarshal/marshal processes the root part of a MIME-based
	package, delegating knowledge of the overall package and its other parts
	to the `Attachment*` class implementations.

	==== AttachmentUnmarshaller

	An implementation of this abstract class by a
	MIME-based package processor provides access to package-level
	information that is outside the scope of the JAXB unmarshal process. A
	MIME-based package processor registers its processing context with a
	Jakarta XML Binding processor using the method
	`setAttachmentUnmarshaller(AttachmentUnmarshaller)` of
	`jakarta.xml.bind.Unmarshaller`.

	Interactions between the Unmarshaller and the
	abstract class are summarized below. The javadoc specifies the details.

	[source,java,indent="4"]
	----
	public abstract class AttachmentUnmarshaller {
	public boolean isXOPPackage();
	public abstract DataHandler getAttachmentAsDataHandler(String cid);
	public abstract byte[] getAttachmentAsByteArray(String cid);
	}
	----

	The JAXB unmarshal process communicates with
	a MIME-based package processor via an instance of AttachmentUnmarshaller
	registered with the unmarshaller.
	<<opbin>> summarizes this
	processing.

	* MTOM/XOP processing during unmarshal: +
	When `isXOPPackage()` returns true, the unmarshaller replaces each XOP
	include element it encounters with MIME content returned by the
	appropriate `getAttachment*()` method.
	* WS-I AP processing: +
	Each element or attribute of type definition `ref:swaRef`, a content-id
	uri reference to binary data, is resolved by the unmarshal process by a
	call to the appropriate `getAttachment*()` method.

	==== AttachmentMarshaller

	An `AttachmentMarshaller` instance is
	registered with a `jakarta.xml.bind.Marshaller` instance using the method
	`Marshaller.setAttachmentMarshaller()`.

	Interactions between the Marshaller and the
	abstract class is summarized below. See the javadoc for details.

	[source,java,indent="4"]
	----
	public abstract class AttachmentMarshaller {
	public boolean isXOPPackage();
	public abstract String addMtomAttachment(
	DataHandler data,
	String elementNamespace,
	String elementLocalName);
	public abstract String addMtomAttachment(
	byte[] data,
	String elementNamespace,
	String elementLocalName);
	public abstract String addSwaRefAttachment(DataHandler data);
	}
	----

	When an AttachmentMarshaller instance is
	registered with the Marshaller, the following processing takes place.

	* MTOM/XOP processing: +
	When `isXOPPackage()` is true and a JAXB property representing binary
	data is being marshalled, the method `addMtomAttachment(..)` is called
	to provide the MIME-based package processor the opportunity to decide to
	optimize or inline the binary data.
	+
	Note that the schema customization specified in
	<<inlinebinarydata-declaration>> can be
	used to declaratively disable XOP processing for binary data.
	* WS-I AP processing: +
	The `addSwaRefAttachment` method is called when marshalling content
	represented by a `ref:swaRef` type definition.
	+
	One can declaratively customize swaRef processing within a schema using
	schema customization @attachmentRef of <jaxb:property>, specified in
	<<usage-4>>.

	.JAXB marshal/unmarshalling of optimized binary content.
	[[opbin]]
	image::images/xmlb-23.svg[image]