• JacksonJAXBAnnotations

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

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

• 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.

• @javax.xml.bind.annotation.XmlElement

  • Used to name a field/property; "type" property also supported for use with Polymorphic Type Handling

• @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.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.

• @javax.xml.bind.annotation.XmlTransient

  • Used to mark a class, field, or property as _transient_ (i.e. will not be serialized).

• @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".

Annotations that may be supported for XML generation

Many annotations that have no JSON counterpart could be useful if Jackson was to produce XML. These annotations include:

• @javax.xml.bind.annotation.XmlElementWrapper

• @link javax.xml.bind.annotation.XmlList

• @javax.xml.bind.annotation.XmlNs

• @link javax.xml.bind.annotation.XmlRootElement is not currently used, but it may be used in future for XML compatibility features

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

• @javax.xml.bind.annotation.XmlID, @javax.xml.bind.annotation.XmlIDREF: no concept in JSON similar to XML ID, IDREF

  • 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.

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

• @link javax.xml.bind.annotation.XmlSeeAlso: mostly not needed as Jackson is more dynamic, does not require pre-registering root types.

CategoryJackson