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')
 
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/latest/javax/xml/bind/annotation/XmlInlineBinaryData.html XmlInlineBinaryData]
+
* [http://www.eclipse.org/eclipselink/api/latest/javax/xml/bind/annotation/XmlMimeType.html XmlMimeType]
+
* [http://www.eclipse.org/eclipselink/api/latest/javax/xml/bind/attachment/AttachmentMarshaller.html AttachmentMarshaller]
+
* [http://www.eclipse.org/eclipselink/api/latest/javax/xml/bind/attachment/AttachmentUnarshaller.html AttachmentUnarshaller]
+
}}
+
 
+
= Binary Types=
+
 
+
There are a few extra things to consider when mapping to binary type fields, such as '''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 a single element or attribute, 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}}
+
! 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;
+
! 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;
+
|-
+
| <tt>java.awt.Image</tt>
+
| <tt>image/gif</tt>
+
|-
+
| <tt>java.awt.Image</tt>
+
| <tt>image/jpeg</tt>
+
|-
+
| <tt>javax.xml.transform.Source</tt>
+
| <tt>text/xml<br>application/xml</tt>
+
|-
+
| <tt>javax.activation.DataHandler</tt>
+
| <tt>*/*</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]
+
 
+
 
+
=== Example ===
+
 
+
The following Java class contains two binary fields: a simple '''byte[]''', and a '''java.awt.Image'''.  In a Web Services environment, the '''Image''' data will automatically be created as an attachment.
+
 
+
<div style="width:700px">
+
<source lang="java">
+
package example;
+
 
+
import java.awt.Image;
+
 
+
import javax.xml.bind.annotation.*;
+
 
+
@XmlRootElement
+
public class BinaryData {
+
 
+
  public byte[] bytes;
+
 
+
  public Image photo;
+
 
+
}
+
</source>
+
</div>
+
 
+
Marshalling this object in a Web Services environment would look something like this (the actual appearance will depend on your application server's implementation of '''AttachmentMarshaller'''):
+
 
+
<div style="width:700px">
+
<source lang="xml">
+
<?xml version="1.0" encoding="UTF-8"?>
+
<binaryData>
+
  <bytes>Ii04Q05ZWSIXDAwLAg==</bytes>
+
  <photo>
+
      <xop:Include href="cid:1" xmlns:xop="http://www.w3.org/2004/08/xop/include"/>
+
  </photo>
+
</binaryData>
+
</source>
+
</div>
+
 
+
 
+
=== @XmlInlineBinaryData ===
+
 
+
If you would like to force your binary data to be written as an inline string in your XML, you can annotate the field with the '''@XmlInlineBinaryData''' annotation:
+
 
+
<div style="width:700px">
+
<source lang="java">
+
package example;
+
 
+
import java.awt.Image;
+
 
+
import javax.xml.bind.annotation.*;
+
 
+
@XmlRootElement
+
public class BinaryData {
+
 
+
  public byte[] bytes;
+
 
+
  @XmlInlineBinaryData
+
  public Image photo;
+
 
+
}
+
</source>
+
</div>
+
 
+
This will result in an XML document like this:
+
 
+
<div style="width:700px">
+
<source lang="xml">
+
<?xml version="1.0" encoding="UTF-8"?>
+
<binaryData>
+
  <bytes>Ii04Q05ZWSIXDAwLAg==</bytes>
+
  <photo>/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHB ... Af/2Q==</photo>
+
</binaryData>
+
</source>
+
</div>
+
 
+
 
+
=== @XmlMimeType ===
+
 
+
You can explicitly set the MIME Type for an binary field using the '''@XmlMimeType''' annotation.  Your application's  '''AttachmentMarshaller''' and '''AttachmentUnmarshaller''' will be responsible for processing this information.
+
 
+
<div style="width:700px">
+
<source lang="java">
+
package example;
+
 
+
import java.awt.Image;
+
 
+
import javax.xml.bind.annotation.*;
+
 
+
@XmlRootElement
+
public class BinaryData {
+
 
+
  public byte[] bytes;
+
 
+
  @XmlMimeType("image/gif")
+
  public Image photo;
+
 
+
}
+
</source>
+
</div>
+

Latest revision as of 09:41, 8 November 2012

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