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:

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:

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'''):

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.