Using JAXB annotations with Jackson
Although JSON is not XML and XML is not JSON, but the process for (de)serializing Java objects to/from JSON has many similarities to the process of (de)serializing Java objects to/from XML. So a significant part of the JAXB metadata is applicable to (de)serializing JSON data.
As a result, with Jackson 1.1 (and later) it is possible to use annotations defined by JAXB API. These annotations are found from JDK package javax.xml.bind.annotation
Changes with Jackson 2.0
With Jackson 2.0, functionality has been moved to a separate Github project, jackson-module-jaxb-annotations. Functionality has not been changed, and instructions below should work as well. In future some of the documentation will be moving to the project pages as well.
Enabling JAXB annotation support
By default, only core Jackson annotations are used for configuring data binding aspects. To enable JAXB annotation support, you need to:
Include jackson-xc jar, which contains org.codehaus.jackson.xc.JaxbAnnotationIntrospector (Jackson 1.x)
or, com.fasterxml.jackson.module.jaxb.JaxbAnnotationIntrospector (Jackson 2.x)
- Register this annotation introspector
Registering JAXB annotation introspector
Annotation introspector to use for serialization process is configured separately for serialization and deserialization purposes; for example:
ObjectMapper mapper = new ObjectMapper();
AnnotationIntrospector introspector = new JaxbAnnotationIntrospector();
// make deserializer use JAXB annotations (only)
mapper.getDeserializationConfig().setAnnotationIntrospector(introspector);
// make serializer use JAXB annotations (only)
mapper.getSerializationConfig().setAnnotationIntrospector(introspector);But you do not have to choose between Jackson and JAXB annotations: it is possible and easy to use both. You just have to decide which should have precedence, in case both would define a configuration property. With that, you can construct an annotation introspector. For example: to use JAXB introspector as a fallback, you would do:
AnnotationIntrospector primary = new JacksonAnnotationIntrospector();
AnnotationIntrospector secondary = new JaxbAnnotationIntrospector();
AnnotationIntrospector pair = new AnnotationIntrospector.Pair(primaryIntrospector, secondaryIntropsector);and then configure ObjectMapper as shown above.
Supported JAXB annotations
The following JAXB annotations are honored:
@javax.xml.bind.annotation.XmlAccessorType
- Used on a class/package to set whether fields, properties, or both are serializable
@javax.xml.bind.annotation.XmlAttribute
- Used to name a field/property.
Also, with http://wiki.fasterxml.com/JacksonFeatureMiniJAXB, used to indicate that value should be serialized as XML Attribute (like with real JAXB)
@javax.xml.bind.annotation.XmlElement
Used to name a field/property; "type" property also supported for use with Polymorphic Type Handling
Also, with http://wiki.fasterxml.com/JacksonFeatureMiniJAXB, used to indicate that value should be serialized as XML Element (like with real JAXB)
@javax.xml.bind.annotation.XmlElementRef
Applied to a field/property. The name of the attribute will be determined using the @XmlRootElement annotation applied to the class of the field/property type.
@javax.xml.bind.annotation.XmlEnumValue
- Used to set the serialized value of an enum value, so you can change how enum values are serialized.
@javax.xml.bind.annotation.XmlID,@javax.xml.bind.annotation.XmlIDREF (since 2.0)
Used to indicate property used for identity references, similar to @JsonIdentityInfo
@javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter
Used to specify an instance of javax.xml.bind.annotation.adapters.XmlAdapter that will be used to adapt the (non-serializable) object to which this annotation is applicable to a different (serializable) object.
See the example in the JAXB JavaDocs for more information.
@link javax.xml.bind.annotation.XmlRootElement Jackson 1.7 allows this to be recognized when root-value wrapping is enabled, and JAXB annotation introspector is used.
@javax.xml.bind.annotation.XmlTransient
Used to mark a class, field, or property as _transient_ (i.e. will not be serialized); that is, same as what @JsonIgnore would indicate.
@javax.xml.bin.annotation.XmlType
property "propOrder" used to work like @JsonPropertyOrder (see JACKSON-90, part of release 1.4)
@javax.xml.bind.annotation.XmlValue
- The field/property to which this annotation is applied will be named "value".
(with Jackson 2.0: @javax.xml.bind.annotation.XmlID, @javax.xml.bind.annotation.XmlIDREF: used to indicate JacksonFeatureObjectIdentity
- although Jackson will try to tackle Object identity in future, it is quite likely to work different from JAXB/XML; so it is not known if this could be useful.
Annotations that may be supported for XML generation
Many annotations that have no JSON counterpart can be useful when dealing with XML (using Jackson XML dataformat module).
These annotations include:
@javax.xml.bind.annotation.XmlElementWrapper: used to define wrapper to use for List/Map values
@javax.xml.bind.annotation.XmlNs: used to define namespace to use
@javax.xml.bind.annotation.XmlValue: used to indicate that a single property will be serialized as "raw" XML text, instead of being wrapped in an element
Not(-yet)-Supported JAXB annotations
Following annotations are not currently supported:
@javax.xml.bind.annotation.XmlAnyAttribute
@javax.xml.bind.annotation.XmlAnyElement (but may be in future, see JACKSON-253)
@javax.xml.bind.annotation.XmlElementDec
@link javax.xml.bind.annotation.XmlSeeAlso: Could use to auto-detect sub-type information?
JAXB annotations very unlikely to ever be supported
Following annotations refer to concepts that do not exist with JSON, and thus are highly unlikely to be supported for JSON production. They could theoretically be supported if Jackson was to produce XML
@javax.xml.bind.annotation.XmlAttachmentRef
@link javax.xml.bind.annotation.XmlInlineBinaryData
@link javax.xml.bind.annotation.XmlMimeType
@link javax.xml.bind.annotation.XmlMixed (since JSON has no concept of mixed content)
@link javax.xml.bind.annotation.XmlRegistry
@link javax.xml.bind.annotation.XmlSchema
@link javax.xml.bind.annotation.XmlSchemaType
@link javax.xml.bind.annotation.XmlSchemaTypes