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

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

 [appendix]
 == [[a5110]]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, link:jaxb.html#a5149[See
 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 JAXB 2.0 unmarshal/marshal
 processes. An enhanced binding of MIME content to Java representation is
 specified in link:jaxb.html#a5113[See Binding MIME Binary
 Data]“.

 === [[a5113]]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 x _s:hexBinary_ .

 JAXB 2.0 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
 JAXB 2.0 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
 link:jaxb.html#a5119[See Default Binding for Known Media Type].

 === [[a5119]]Default Binding for Known Media Type

 [width="100%",cols="50%,50%",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_
 |javax.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

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

 === JAXB 2.0 binding of Example 9-1

  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 JAXB 2.0 Marshaller to specify the mime type
 to set _DataHandler.setContentType(String)_ .

 === [[a5140]]Schema for local element declaration annotated with known media type

  <?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 link:jaxb.html#a5140[See Schema for local element declaration annotated with known media type]“

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

 === [[a5147]]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
 _javax.activation.DataHandler_ and annotated with _@XmlAttachmentRef_ .

 === [[a5149]]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
 JAX-WS 2.0 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
 JAXB 2.0 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.

 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. link:jaxb.html#a5165[See JAXB
 marshal/unmarshalling of optimized binary content.] 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.

 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
 link:jaxb.html#a2193[See <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
 link:jaxb.html#a1786[See Usage]“.

 === [[a5165]]JAXB marshal/unmarshalling of optimized binary content.

 image:images/xmlb-23.png[image]
	//
	// Copyright (c) 2020 Contributors to the Eclipse Foundation
	//

	[appendix]
	== [[a5110]]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, link:jaxb.html#a5149[See
	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 JAXB 2.0 unmarshal/marshal
	processes. An enhanced binding of MIME content to Java representation is
	specified in link:jaxb.html#a5113[See Binding MIME Binary
	Data]“.

	=== [[a5113]]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 x _s:hexBinary_ .

	JAXB 2.0 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
	JAXB 2.0 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
	link:jaxb.html#a5119[See Default Binding for Known Media Type].

	=== [[a5119]]Default Binding for Known Media Type

	[width="100%",cols="50%,50%",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_
	\|javax.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

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

	=== JAXB 2.0 binding of Example 9-1

	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 JAXB 2.0 Marshaller to specify the mime type
	to set _DataHandler.setContentType(String)_ .

	=== [[a5140]]Schema for local element declaration annotated with known media type

	<?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 link:jaxb.html#a5140[See Schema for local element declaration annotated with known media type]“

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

	=== [[a5147]]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
	_javax.activation.DataHandler_ and annotated with _@XmlAttachmentRef_ .

	=== [[a5149]]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
	JAX-WS 2.0 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
	JAXB 2.0 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.

	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. link:jaxb.html#a5165[See JAXB
	marshal/unmarshalling of optimized binary content.] 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.

	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
	link:jaxb.html#a2193[See <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
	link:jaxb.html#a1786[See Usage]“.

	=== [[a5165]]JAXB marshal/unmarshalling of optimized binary content.

	image:images/xmlb-23.png[image]