|
|
(18 intermediate revisions by the same 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:
| + | |
− | | + | |
− | {|{{BMTableStyle}}
| + | |
− | |-{{BMTHStyle}}
| + | |
− | ! MIME Type
| + | |
− | ! Java Type
| + | |
− | |-
| + | |
− | | image/gif
| + | |
− | | java.awt.Image
| + | |
− | |-
| + | |
− | | image/jpeg
| + | |
− | | java.awt.Image
| + | |
− | |-
| + | |
− | | text/xml<br>application/xml
| + | |
− | | javax.xml.transform.Source
| + | |
− | |-
| + | |
− | | */*
| + | |
− | | javax.activation.DataHandler
| + | |
− | |}
| + | |
− | | + | |
− | fields of type '''java.awt.Image''', '''javax.xml.transform.Source''', and '''javax.activation.DataHandler'''
| + | |
− | | + | |
− | {{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]
| + | |