New in EclipseLink 2.4 is support for converting objects directly 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.

−

+

−

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.

+

+

=Overview=

'''Same Flexibility as Object-to-XML Mapping'''

'''Same Flexibility as Object-to-XML Mapping'''

−

JSON binding is compatible with most existing MOXy extensions. This includes:

+

Everything from MOXy's object-to-XML mapping technology is available to you to read and write JSON. This includes:

The '''MEDIA_TYPE''' property can also be specified in the Map of properties used during creation of the '''JAXBContext'''. In this case, Marshallers and Unmarshallers created from that context will automatically use the specified media type:

The '''eclipselink.media-type''' property can also be specified in the Map of properties used during creation of the '''JAXBContext'''. In this case, Marshallers and Unmarshallers created from that context will automatically use the specified media type:

Below is an example of a JSON binding that does not require any additional compile time dependencies above and beyond what is required for normal JAXB usage. It unmarshals JSON from a '''StreamSource''' into a user-object '''SearchResults''', adds a new '''Result''' to the collection, and marshals the new collection to System.out:

JSON doesn't have the concept of attributes, so by default anything mapped as an '''@XmlAttribute''' will be marshalled as an element. During unmarshal, elements will trigger both the attribute and element events, to allow either the mapped attribute or element to handle the value. If there is an element and attribute with the same name, this will cause problems.

JSON doesn't have the concept of attributes, so by default anything mapped as an '''@XmlAttribute''' will be marshalled as an element. During unmarshal, elements will trigger both the attribute and element events, to allow either the mapped attribute or element to handle the value. If there is an element and attribute with the same name, this will cause problems.

Line 174:

Line 305:

−

==Support for No "Root Element"==

+

=Support for No "Root Element"=

JSON supports documents with no root element:

JSON supports documents with no root element:

Line 224:

Line 355:

−

==Namespaces==

+

=Namespaces=

JSON doesn't have the concept of namespaces, and by default namespaces/prefixes will be ignored during marshal and unmarshal operations. This default behavior could be a problem if there are multiple mappings with the same local name in different namespaces as there would be no way to distinguish between those mappings.

JSON doesn't have the concept of namespaces, and by default namespaces/prefixes will be ignored during marshal and unmarshal operations. This default behavior could be a problem if there are multiple mappings with the same local name in different namespaces as there would be no way to distinguish between those mappings.

The namespaces will be given the prefix from the Map separated by a dot:

+

Note that '''MarshallerProperties.NAMESPACE_PREFIX_MAPPER''' applies to both XML and JSON, whereas '''UnmarshallerProperties.JSON_NAMESPACE_PREFIX_MAPPER''' is a JSON-only property; XML unmarshalling can obtain the namespace information from the document itself.

+

+

When JSON is marshalled, the namespaces will be given the prefix from the Map separated by a dot:

<div style="width:850px">

<div style="width:850px">

Line 252:

Line 385:

</div>

</div>

−

Note that '''NAMESPACE_PREFIX_MAPPER''' only comes into play during unmarshal if the media type is set to JSON; XML unmarshalling can obtain the namespace information from the document itself.

+

The dot separator can be set to a custom Character using the '''JSON_NAMESPACE_SEPARATOR''' property:

Inheritance is supported when marshalling to JSON. The following example shows a marshalled XML document using inheritance, as well as the equivalent JSON document:

Inheritance is supported when marshalling to JSON. The following example shows a marshalled XML document using inheritance, as well as the equivalent JSON document:

Line 280:

Line 420:

−

==Null Handling==

+

=Null Handling=

−

Behaviour when marshalling null values can be configured using the '''@XmlNullPolicy''' annotation. By default, null values will not be marshalled to JSON ('''XmlMarshalNullRepresentation.ABSENT_NODE'''):

+

Behaviour when marshalling null values can be configured using the '''nillable''' attribute of the '''@XmlElement''' annotation. By default, null values will not be marshalled to JSON:

<div style="width:850px">

<div style="width:850px">

Line 289:

Line 429:

public class Employee {

public class Employee {

−

@XmlElement

private String name = "Bob Smith";

private String name = "Bob Smith";

−

@XmlElement

private Address address = null;

private Address address = null;

Line 308:

Line 446:

</div>

</div>

−

Using '''XmlMarshalNullRepresentation.EMPTY_NODE''' will produce an empty element:

+

Using '''@XmlElement(nillable = true)''' will produce an empty element:

The '''JSON_VALUE_WRAPPER''' property can also be specified in the Map of properties used during creation of the '''JAXBContext'''. In this case, Marshallers and Unmarshallers created from that context will automatically use the specified value wrapper:

Object-to-JSON Binding

New in EclipseLink 2.4 is support for converting objects directly 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.

Overview

Same Flexibility as Object-to-XML Mapping

Everything from MOXy's object-to-XML mapping technology is available to you to read and write JSON. This includes:

The eclipselink.media-type property can also be specified in the Map of properties used during creation of the JAXBContext. In this case, Marshallers and Unmarshallers created from that context will automatically use the specified media type:

Example: Basic JSON Binding

Below is an example of a JSON binding that does not require any additional compile time dependencies above and beyond what is required for normal JAXB usage. It unmarshals JSON from a StreamSource into a user-object SearchResults, adds a new Result to the collection, and marshals the new collection to System.out:

Attributes

JSON doesn't have the concept of attributes, so by default anything mapped as an @XmlAttribute will be marshalled as an element. During unmarshal, elements will trigger both the attribute and element events, to allow either the mapped attribute or element to handle the value. If there is an element and attribute with the same name, this will cause problems.

Users will be able to override the default behavior by providing an attribute prefix, which will be prepended to the attribute name during marshal, and recognized during unmarshal. In the example below the number field is mapped as an attribute.

The JSON_ATTRIBUTE_PREFIX property can also be specified in the Map of properties used during creation of the JAXBContext. In this case, Marshallers and Unmarshallers created from that context will automatically use the specified prefix:

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:

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.

Namespaces

JSON doesn't have the concept of namespaces, and by default namespaces/prefixes will be ignored during marshal and unmarshal operations. This default behavior could be a problem if there are multiple mappings with the same local name in different namespaces as there would be no way to distinguish between those mappings.

In this case, the user can supply Map of namespace->prefix (or an instance of NamespacePrefixMapper) to the Marshaller and Unmarshaller, and namespace prefixes will appear in the marshalled document, prepended to the element name. This prefix will be recognized during unmarshal, and the resulting Java objects will be placed in the proper namespaces.

Note that MarshallerProperties.NAMESPACE_PREFIX_MAPPER applies to both XML and JSON, whereas UnmarshallerProperties.JSON_NAMESPACE_PREFIX_MAPPER is a JSON-only property; XML unmarshalling can obtain the namespace information from the document itself.

When JSON is marshalled, the namespaces will be given the prefix from the Map separated by a dot:

{
"ns1.employee : {
"ns2.id" : 123
}
}

The dot separator can be set to a custom Character using the JSON_NAMESPACE_SEPARATOR property:

The JSON_VALUE_WRAPPER property can also be specified in the Map of properties used during creation of the JAXBContext. In this case, Marshallers and Unmarshallers created from that context will automatically use the specified value wrapper: