Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/MOXy/Simple Values/Special Schema Types/Binary Types"

m (Replacing page with 'See http://www.eclipse.org/eclipselink/documentation/2.4/moxy/special_schema_types003.htm')
 
(13 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{EclipseLink_UserGuide
+
See http://www.eclipse.org/eclipselink/documentation/2.4/moxy/special_schema_types003.htm
|info=y
+
|toc=y
+
|eclipselink=y
+
|eclipselinktype=MOXy
+
|api=y
+
|apis= * [http://www.eclipse.org/eclipselink/api/latest/javax/xml/bind/annotation/XmlSchemaType.html XmlSchemaType]
+
* [http://www.eclipse.org/eclipselink/api/2.3/javax/xml/bind/annotation/XmlInlineBinaryData.html XmlInlineBinaryData]
+
* [http://www.eclipse.org/eclipselink/api/2.3/javax/xml/bind/annotation/XmlMimeType.html XmlMimeType]
+
}}
+
 
+
= Binary Types=
+
 
+
There are a few extra things to consider when mapping to fields of type '''byte[]''' or '''Byte[]'''.
+
 
+
 
+
== Binary Formats - Base64 and Hex ==
+
 
+
EclipseLink supports marshalling and unmarshalling binary data in two different representation formats: '''base64Binary''' (default) and '''hexBinary'''.  You can specify the desired binary format using the '''@XmlSchemaType''' annotation, or '''<xml-schema-type>''' element in EclipseLink OXM.  The example below shows the result of marshalling the same '''byte[]''' to each of these formats.
+
 
+
 
+
'''Annotations'''
+
<div style="width:700px">
+
<source lang="java">
+
package example;
+
 
+
import javax.xml.bind.annotation.*;
+
 
+
@XmlRootElement
+
public class BinaryData {
+
 
+
  @XmlSchemaType(name="hexBinary")
+
  public byte[] hexBytes;
+
 
+
  @XmlSchemaType(name="base64Binary")
+
  public byte[] base64Bytes;
+
 
+
}
+
</source>
+
</div>
+
 
+
 
+
'''EclipseLink OXM'''
+
<div style="width:700px">
+
<source lang="xml">
+
...
+
<java-type name="example.BinaryData">
+
    <xml-root-element/>
+
    <java-attributes>
+
        <xml-element java-attribute="hexBytes">
+
            <xml-schema-type name="hexBinary"/>
+
        </xml-element>
+
        <xml-element java-attribute="base64Bytes">
+
            <xml-schema-type name="base64Binary"/>
+
        </xml-element>
+
    </java-attributes>
+
</java-type>
+
...
+
</source>
+
</div>
+
 
+
 
+
<div style="width:700px">
+
<source lang="java">
+
BinaryData b = new BinaryData();
+
b.hexBytes = new byte[] {2,4,8,16,32,64};
+
b.base64Bytes = b.hexBytes;
+
 
+
jaxbContext.createMarshaller().marshal(b, System.out);
+
</source>
+
</div>
+
 
+
 
+
'''Output'''
+
<div style="width:700px">
+
<source lang="xml">
+
<?xml version="1.0" encoding="UTF-8"?>
+
<binaryData>
+
  <hexBytes>020308102040</hexBytes>
+
  <base64Bytes>AgMIECBA</base64Bytes>
+
</binaryData>
+
</source>
+
</div>
+
 
+
 
+
== byte[] versus Byte[] ==
+
 
+
Unlike other Java primitive/wrapper types, Eclipselink differentiates between '''byte[]''' (primitive) and '''Byte[]''' (wrapper) data types.  By default, '''byte[]''' will marshal to an element or attribute of type '''base64Binary''', whereas '''Byte[]''' will marshal each byte as its own element, as illustrated by the following example:
+
 
+
 
+
<div style="width:700px">
+
<source lang="java">
+
package example;
+
 
+
import javax.xml.bind.annotation.*;
+
 
+
@XmlRootElement
+
public class BinaryData {
+
 
+
  public byte[] primitiveBytes;
+
  public Byte[] byteObjects;
+
 
+
}
+
</source>
+
</div>
+
 
+
 
+
<div style="width:700px">
+
<source lang="java">
+
BinaryData b = new BinaryData();
+
b.primitiveBytes = new byte[] {34,45,56,67,78,89,89,34,23,12,12,11,2};
+
b.byteObjects = new Byte[] {23,1,112,12,1,64,1,14,3,2};
+
 
+
jaxbContext.createMarshaller().marshal(b, System.out);
+
</source>
+
</div>
+
 
+
 
+
'''Output'''
+
<div style="width:700px">
+
<source lang="xml">
+
<?xml version="1.0" encoding="UTF-8"?>
+
<binaryData>
+
  <primitiveBytes>Ii04Q05ZWSIXDAwLAg==</primitiveBytes>
+
  <byteObjects>23</byteObjects>
+
  <byteObjects>1</byteObjects>
+
  <byteObjects>112</byteObjects>
+
  <byteObjects>12</byteObjects>
+
  <byteObjects>1</byteObjects>
+
  <byteObjects>64</byteObjects>
+
  <byteObjects>1</byteObjects>
+
  <byteObjects>14</byteObjects>
+
  <byteObjects>3</byteObjects>
+
  <byteObjects>2</byteObjects>
+
</binaryData>
+
</source>
+
</div>
+
 
+
 
+
== Working with SOAP Attachments ==
+
 
+
If you are using EclipseLink MOXy in a Web Services environment, certain types of binary data may be created as an MTOM/XOP Attachment, instead of written directly into an XML element or attribute.  This is done as an optimization for large amounts of binary data. 
+
 
+
 
+
The following table shows the Java types that are automatically treated as Attachments, along with their corresponding MIME type:
+
 
+
<div style="width:500px">
+
{|{{BMTableStyle}}
+
|-{{BMTHStyle}}
+
! MIME Type&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+
! Java Type&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+
|-
+
| <tt>image/gif</tt>
+
| <tt>java.awt.Image</tt>
+
|-
+
| <tt>image/jpeg</tt>
+
| <tt>java.awt.Image</tt>
+
|-
+
| <tt>text/xml<br>application/xml</tt>
+
| <tt>javax.xml.transform.Source</tt>
+
|-
+
| <tt>*/*</tt>
+
| <tt>javax.activation.DataHandler</tt>
+
|}
+
</div>
+
 
+
 
+
{{tip||For more information on the basics of SOAP Attachments, see "Appendix H: Enhanced Binary Data Handling" of the ''Java Architecture for XML Binding (JAXB) 2.2 Specification''.}}
+
[http://jcp.org/en/jsr/detail?id=222| Java Architecture for XML Binding (JAXB) 2.2 Specification]
+

Latest revision as of 10:41, 8 November 2012

See http://www.eclipse.org/eclipselink/documentation/2.4/moxy/special_schema_types003.htm

Back to the top