Jump to: navigation, search

Dali/Indigo/JAXB 2.x/AttributeAnnotations

< Dali‎ | Indigo‎ | JAXB 2.x

Functional Specification: JAXB Attribute Annotations

bug 327915 - Resource model support for JAXB 2.2 field/method annotations

Document History

Date Author Version Description & Notes
10-11-2010 Paul Fullbright Draft

Feature overview

This feature is about support for JAXB attribute annotations

Goals:

  • Support JAXB attribute level annotations and default values
    • @XmlElement/Elements
    • @XmlElementRef/Refs
    • @XmlElementWrapper
    • @XmlAnyElement
    • @XmlAttribute
    • @XmlAnyAttribute
    • @XmlTransient
    • @XmlValue
    • @XmlID
    • @XmlIDRef
    • @XmlList
    • @XmlMixed
    • @XmlMimeType
    • @XmlAttachmentRef
    • @XmlInlineBinaryData
    • @XmlJavaTypeAdapter
    • @XmlEnumValue

Concepts

Attribute annotations are supported on JAXB fields and Java bean style properties. Unless @XmlTransient is present, all fields/properties that fulfill the type's access type are considered mapped JAXB attributes.

Requirements / Functionality

@XmlElement/Elements

@XmlElement is used on an attribute to indicate that it is mapped to an XML element or element ref. If there is not another mapping annotation on a legitimate JAXB attribute, and:

- the attribute is single valued - @XmlElement is assumed

- the attribute has a collection type - @XmlElements({ @XmlElement(nillable=true) }) is assumed

- the attribute has a collection type and has the @XmlList annotation - @XmlElement is assumed

  • name - String; name of the XML element to which this attribute is mapped; default value is based on the name of the attribute
  • namespace - String; target namespace with which the element must be qualified; default value is based on the class's namespace and the package's elementFormDefault setting - a "" value indicates the element is not to be qualified
  • defaultValue - String; the default value of this attribute; no default
  • nillable - boolean; whether the element is nillable; default is false
  • required - boolean; whether the element is required; default is false
  • type - Class; specifies the type to be used for populating the element; default is determined by spec table 8-14

@XmlElements is used as a container for @XmlElement. It is used on attributes with a parameterized collection type.

@XmlElementRef/Refs

@XmlElementRef dynamically associates an XML element name with a JAXB attribute. When an attribute is annotated with @XmlElement, the XML element name is statically derived from the attribute name. However, when this annotation is used, the XML element name is derived from the instance of the type of the attribute at runtime. When the item type (the type of the attribute, or the item type if it is a collection) of the attribute is JAXBElement, then "name" and "namespace" must point at a factory (class is annotated with @XmlRegistry) method (method is annotated with @XmlDecl). When the item type is other than JAXBElement, the item type must itself be annotated with @XmlRootElement.

  • name - String; the name of the root XML element to which this attribute is mapped; default value is determined by spec table 8-18
  • namespace - String; namespace of the root XML element to which this attribute is mapped; default value is determined by spec table 8-18
  • type - Class; specifies the type to be used for populating the element; default is determined from attribute type

@XmlElementRefs is used as a container for @XmlElementRef. It is used on attributes with a parameterized collection type.

@XmlElementWrapper

@XmlElementWrapper is used to generate an XML element wrapper around values. It is used on attributes with collection types.

  • name - String; name of the XML element to use as a wrapper; default is based on the attribute name
  • namespace - String; namespace with which to qualify the XML element; default value is based on the class's namespace and the package's elementFormDefault setting - a "" value indicates the element is not to be qualified
  • nillable - boolean; specifies if the wrapper element is nillable; default is false
  • required - boolean; specifies if the wrapper element is required; default is false

@XmlAnyElement

@XmlAnyElement serves as a "catch-all" property while unmarshalling xml content into a instance of a JAXB annotated class. It typically annotates a multi-valued attribute, but it can occur on single value attribute. During unmarshalling, each xml element that does not match a static @XmlElement or @XmlElementRef annotation for the other attributes on the class, is added to this "catch-all" property.

This annotation can also be used with @XmlElementRef/Refs on a collection type attribute.

  • lax - boolean; controls the unmarshaller behavior when it sees elements known to the current JAXBContext; default is false
  • value - Class<? extends DomHandler>; specifies the DomHandler which is responsible for actually converting XML from/to a DOM-like data structure; default is W3CDomHandler.class

@XmlAttribute

@XmlAttribute maps a JAXB attribute to map of wildcard attributes. A static final attribute is mapped to an XML fixed attribute. A collection JAXB attribute is assumed to be annotated with @XmlList (although it may be specified).

  • name - String; specifies the name of the XML attribute; default is based on the name of the java attribute
  • namespace - String; specifies the namespace with which to qualify the XML attribute; default value is based on the class's namespace and the package's elementFormDefault setting - a "" value indicates the element is not to be qualified
  • required - boolean; specifies if the XML attribute is required; default is false

@XmlAnyAttribute

@XmlAnyAttribute maps a JAXB attribute to map of wildcard attributes. There is an error if the attribute type is not a Map. There is a maximum of one @XmlAttribute per class.

@XmlTransient

@XmlTransient prevents the mapping of an otherwise mappable JAXB field or property.

@XmlValue

@XmlValue enables mapping a class to a XML Schema complex type with a simpleContent or a XML Schema simple type. The item type (the type of the attribute, or the item type if it is a collection) must map to a simple schema type. There is a maximum of one @XmlValue mapping per class. @XmlValue can be used with @XmlList, however this is redundant since @XmlList maps a type to a simple schema type that derives by list just as XmlValue would.

@XmlID

@XmlID and @XmlIDREF together allow a customized mapping of a JAXB attribute's type by containment or reference. This may be used with either @XmlElement or @XmlAttribute. There is a maximum of one @XmlID mapping per class. The attribute's type must be java.lang.String.

@XmlIDREF

@XmlIDREF and @XmlID together allow a customized mapping of a JAXB attribute's type by containment or reference. This may be used with @XmlElement, @XmlElements, or @XmlAttribute, and also with @XmlList. The item type (the type of the attribute, or the item type if it is a collection) must contain a property or field annotated with @XmlID.

@XmlList

@XmlList is used to map an attribute to a list simple type. It allows allows multiple values to be represented as whitespace-separated tokens in a single element or attribute. The use of @XmlList with either @XmlValue or @XmlAttribute, while allowed, is redundant since @XmlList maps a collection type to a simple schema type that derives by list just as either of those annotations would.

@XmlMixed

@XmlMixed is used to allow mixed XML content (element and text) in a collection-typed JAXB attribute. It may be used with @XmlElementRef/Refs or @XmlAnyElement.

@XmlMimeType

@XmlMimeType associates the MIME type that controls the XML representation of the property. This annotation is used in conjunction with datatypes such as Image or Source that are bound to base64-encoded binary in XML.

  • value - The textual representation of the MIME type, such as "image/jpeg" "image/*", "text/xml; charset=iso-8859-1" and so on.

@XmlAttachmentRef

@XmlAttachmentRef marks an attribute that its XML form is a uri reference to mime content. The mime content is optimally stored out-of-line as an attachment. An attribute must always map to the DataHandler class.

@XmlInlineBinaryData

@XmlInlineBinaryData disables consideration of XOP encoding for datatypes that are bound to base64-encoded binary data in XML.

@XmlJavaTypeAdapter

@XmlJavaTypeAdapter allows an attribute mapping to define or override the java type adapter defined for the referenced type. It can be used with: XmlAttribute, XmlElement(s), XmlElementRef(s), XmlAnyElement, or XmlValue. The item type (the type of the attribute, or the item type if it is a collection) is assumed to be the "type" variable.

  • value - Class<? extends XmlAdapter>; specifies the adapter class to use; must be specified

@XmlJavaTypeAdapters is not supported on Attributes.

@XmlEnumValue

@XmlEnumValue is especially for enum constants. With it you can specify the XML value to be used for each.

  • value - String; specifies the XML value to be used for an object value of the enum constant; default is the name of the enum constant

Code Completion

Code completion should be implemented where feasible to help users with values.