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

EclipseLink/UserGuide/MOXy/Simple Values/Special Schema Types/Binary Types

EclipseLink MOXy

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

package example;
 
import javax.xml.bind.annotation.*;
 
@XmlRootElement
public class BinaryData {
 
   @XmlSchemaType(name="hexBinary")
   public byte[] hexBytes;
 
   @XmlSchemaType(name="base64Binary")
   public byte[] base64Bytes;
 
}


EclipseLink OXM

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


BinaryData b = new BinaryData();
b.hexBytes = new byte[] {2,4,8,16,32,64};
b.base64Bytes = b.hexBytes;
 
jaxbContext.createMarshaller().marshal(b, System.out);


Output

<?xml version="1.0" encoding="UTF-8"?>
<binaryData>
   <hexBytes>020308102040</hexBytes>
   <base64Bytes>AgMIECBA</base64Bytes>
</binaryData>


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:


package example;
 
import javax.xml.bind.annotation.*;
 
@XmlRootElement
public class BinaryData {
 
   public byte[] primitiveBytes;
   public Byte[] byteObjects;
 
}


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);


Output

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


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:


MIME Type Java Type
image/gif java.awt.Image
image/jpeg java.awt.Image
text/xml
application/xml
javax.xml.transform.Source
*/* javax.activation.DataHandler


Idea.png
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.

Architecture for XML Binding (JAXB) 2.2 Specification

Back to the top