Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Open sidebar
Raptor Engineering Public Development
Jitsi
jaxb-api
Commits
be694e8a
Commit
be694e8a
authored
4 years ago
by
Lukas Jungmann
Browse files
Options
Download
Email Patches
Plain Diff
Update appendix H
Signed-off-by:
Lukas Jungmann
<
lukas.jungmann@oracle.com
>
parent
b7580fd8
Changes
1
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
131 additions
and
138 deletions
+131
-138
spec/src/main/asciidoc/appH-binary_data.adoc
spec/src/main/asciidoc/appH-binary_data.adoc
+131
-138
No files found.
spec/src/main/asciidoc/appH-binary_data.adoc
View file @
be694e8a
...
...
@@ -3,7 +3,7 @@
//
[appendix]
==
[[a5110]]
Enhanced Binary Data Handling
== Enhanced Binary Data Handling
=== Overview
...
...
@@ -17,177 +17,169 @@ 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]
“
.
Data].
===
[[a5113]]
Binding MIME Binary Data
=== Binding MIME Binary Data
=== Binary Data Schema Annotation
===
=
Binary Data Schema Annotation
As specified in [MIME], the XML Schema
annotation attribute,
_
xmime:expectedContentTypes
_
, lists the expected
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
_
.
binary datatypes,
`
xs:base64Binary
`
or
`
xs: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
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
`
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
`
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
===
==
Binding Known Media Type
When
_
@xmime:expectedContentTypes
_
schema
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
_
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",]
.Default Binding for Known Media Type
[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_
|javax.activation.DataHandler
| 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
`
@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"/> +
.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>
=== JAXB 2.0 binding of Example 9-1
import java.awt.Image; +
@XmlRegistry +
class ObjectFactory \{ +
@Xml
ElementDecl(...) +
@XmlMimeType("image/jpeg")
JAXBELement<Image> createJPEGPicture(Image
value);
+
----
.JAXB 2.0 binding of Example 8-1
[source,java,indent="4"]
----
import java.awt.Image;
@Xml
Registry
class ObjectFactory {
@XmlElementDecl(...)
@XmlMimeType("image/jpeg")
JAXBELement<Image> createJPEGPicture(Image
value);
}
----
The
_
@XmlMimeType
_
annotation provides the
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> +
to set `DataHandler.setContentType(String)`.
.Schema for local element declaration annotated with 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: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); +
----
.Java Binding of link:jaxb.html#a5140[See Schema for local element declaration annotated with known media type]“
[source,java,indent="4"]
----
import java.awt.Image;
public class Item {
@XmlMimeType("image/jpeg")
Image getJPEGPicture();
void setJPEGPicture(Image value);
}
----
=== Binding Preferred Media Types
===
==
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
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.
`
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
_
ja
vax
.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.
`
ja
karta
.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
_
===
=
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
_
ja
vax
.activation.DataHandler
_
and annotated with
_
@XmlAttachmentRef
_
.
definition of
`
ref:swaRef
`
is bound to a JAXB property with base type of
`
ja
karta
.activation.DataHandler
`
and annotated with
`
@XmlAttachmentRef
`
.
===
[[a5149]]
jakarta.xml.bind.attachments
=== jakarta.xml.bind.attachments
The abstract classes
_
AttachmentUnmarshaller
_
and
_
AttachmentMarshaller
_
in package
_
jakarta.xml.bind.attachments
_
are
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.
to the
`
Attachment*
`
class implementations.
=== AttachmentUnmarshaller
===
=
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
_
.
`
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); +
[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
...
...
@@ -196,58 +188,59 @@ marshal/unmarshalling of optimized binary content.] summarizes this
processing.
* MTOM/XOP processing during unmarshal: +
When
_
isXOPPackage()
_
returns true, the unmarshaller replaces each XOP
When
`
isXOPPackage()
`
returns true, the unmarshaller replaces each XOP
include element it encounters with MIME content returned by the
appropriate
_
getAttachment*()
_
method.
appropriate
`
getAttachment*()
`
method.
* WS-I AP processing: +
Each element or attribute of type definition
_
ref:swaRef
_
, a content-id
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.
call to the appropriate
`
getAttachment*()
`
method.
=== AttachmentMarshaller
===
=
AttachmentMarshaller
An
_
AttachmentMarshaller
_
instance is
registered with a
_
jakarta.xml.bind.Marshaller
_
instance using the method
_
Marshaller.setAttachmentMarshaller()
_
.
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); +
[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
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.
+
+
optimize or inline the binary data.
+
Note that the schema customization specified in
link:jaxb.html#a2193[See <inlineBinaryData> Declaration]
“
can be
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.
+
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]
.JAXB marshal/unmarshalling of optimized binary content.
image::images/xmlb-23.png[image]
This diff is collapsed.
Click to expand it.
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment