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.
Difference between revisions of "EclipseLink/Release/2.4.0/JSONBinding"
Line 92: | Line 92: | ||
<div style="width:850px"> | <div style="width:850px"> | ||
<source lang="java"> | <source lang="java"> | ||
+ | @XmlRootElement | ||
public class Address { | public class Address { | ||
+ | @XmlElement | ||
private int id; | private int id; | ||
+ | @XmlElement | ||
private city bar; | private city bar; | ||
+ | @XmlElement | ||
private boolean isMailingAddress; | private boolean isMailingAddress; | ||
Revision as of 13:54, 14 June 2012
Object-to-JSON Binding Layer
Overview
New in EclipseLink 2.4 is support for converting objects to and from JSON. This can be useful when creating RESTful services, as JAX-RS services often accept both XML (application/xml) and JSON (application/json) messages.
Same Flexibility as Object-to-XML Mapping
JSON binding is compatible with most existing MOXy extensions. This includes:
- External bindings file
- Dynamic JAXB
- Extensible models
XML and JSON Messages with One Set of Mappings
Both an XML message such as:
<foo xmlns="urn:examle" id="123"> <bar>Hello World</bar> </foo>
and a JSON message such as:
{"foo" : { "id" : 123, "bar : "Hello World" }}
can be supported by a single object model:
@XmlRootElement(namespace="urn:example") public class Foo { @XmlAttribute private int id; @XmlElement(namespace="urn:example") private String bar; }
No Additional Compile-Time Dependencies
JSON binding does not require any additional compile-time dependencies above and beyond what is required for normal JAXB usage.
Easy to Use with JAX-RS
EclipseLink JSON support makes it easy to implement MessageBodyReader and MessageBodyWriter classes for use with RESTful web services.
Marshalling and Unmarshalling with JSON
Adapting your application to produce and consume JSON is as easy as setting a property on your JAXB Marshaller or Unmarshaller:
import org.eclipse.persistence.jaxb.MarshallerProperties; import org.eclipse.persistence.oxm.MediaType; ... Marshaller m = jaxbContext.createMarshaller(); m.setProperty(MarshallerProperties.MEDIA_TYPE, MediaType.APPLICATION_JSON); Unmarshaller u = jaxbContext.createUnmarshaller(); u.setProperty(MarshallerProperties.MEDIA_TYPE, MediaType.APPLICATION_JSON); ...
JSON Data Types
XML has one datatype, text, whereas JSON differentiates between strings, numbers, and booleans. MOXy supports these datatypes automatically:
@XmlRootElement public class Address { @XmlElement private int id; @XmlElement private city bar; @XmlElement private boolean isMailingAddress; }
{"address": "id":1, "city":"Ottawa", "isMailingAddress":true }
Support for No "Root Element"
JSON supports documents with no root element:
{"area-code":"613", "number":"1234567"}
As opposed to the corresponding JSON with a root element "phone":
{"phone": {"area-code":"613", "number":"1234567"} }
Marshal
During marshal, if no @XmlRootElement annotation is present, then the marshalled JSON document will not have a root element. If @XmlRootElement is specified, the root element can be omitted from the JSON output by setting the following property on the JAXB Marshaller:
marshaller.setProperty(MarshallerProperties.JSON_INCLUDE_ROOT, false);
Unmarshal
By default it will be assumed that the document has a root element. If your documents do not contain root elements, you should set the following property on your Unmarshaller. Also note that if there is no root element, you must specify the Class being unmarshalled to.
unmarshaller.setProperty(UnmarshallerProperties.JSON_INCLUDE_ROOT, false); JAXBElement<SearchResults> jaxbElement = unmarshaller.unmarshal(source, SearchResults.class);
Unsupported MOXy/JAXB Annotations
The following annotations are not applicable to JSON:
XmlAttributeRef | XmlMimeType | XmlMixed | XmlNs |
---|---|---|---|
XmlNsForm | XmlSchema | XmlProperties | XmlProperty |
XmlVirtualAccessMethods | XmlVirtualAccessMethodsSchema | XmlIsSetNullPolicy | XmlJoinNodes |
XmlMarshalNullRepresentation | XmlNullPolicy | XmlParameter | XmlPath |
XmlPaths | XmlCDATA |