Jump to: navigation, search

Dali/Indigo/JAXB 2.x/TypeAnnotations

< Dali‎ | Indigo‎ | JAXB 2.x

Functional Specification: JAXB Type Annotations

bug 327914 - Resource model support for JAXB 2.2 type annotations and enums

Document History

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

Feature overview

This feature is about support for JAXB type annotations

Goals:

  • Support JAXB type level annotations and default values
    • @XmlType
    • @XmlRootElement
    • @XmlEnum
    • @XmlTransient
    • @XmlSeeAlso
    • @XmlAccessorType
    • @XmlAccessorOrder
    • @XmlJavaTypeAdapter
    • @XmlInlineBinaryData
    • @XmlRegistry
  • Support JAXB package level enums
    • XmlAccessType
    • XmlAccessOrder

Concepts

Type annotations are supported on classes (in the case of @XmlType, or defaults thereof) and enums (in the case of @XmlType and @XmlEnum, or default thereof). (In MOXy, interfaces are also supported.)

Unless @XmlTransient is present, all classes that have a public or protected no-arg constructor (and that are connected to the JAXB context) are considered mapped JAXB classes. All enums (that are connected to the JAXB context) are considered mapped JAXB enums. The rest of the metadata are settings on the mapped type.

Requirements / Functionality

@XmlType

@XmlType is used on a class to declare it as a JAXB persistent class, but really that part is unimportant, because ANY class is pretty much a JAXB persistent class if it has a public or protected zero-arg constructor and has been attached to the JAXB context. So this pretty much just becomes a container for all the variables it provides.

  • name - String; specifies the schema type to which this class is mapped; default is based on an algorithm mapping java class names to schema type names; "" indicates the type is anonymous
  • namespace - String; specifies namespace of type; default value is complicated (see spec)
  • propOrder - String[]; specifies the order of XML elements when mapped to a complex type; default is to use access order from type or package
  • factoryClass - Class; specifies a factory class to use instead of a zero-arg constructor; default is none
  • factoryMethod - String; specifies the method on the factory class; default is none

propOrder, factoryClass and factoryMethod are ignored on enums.

@XmlRootElement

@XmlRootElement is used on a class or enum to specify that it is mapped to a top level document element.

  • name - String; specifies the name of the global element; default is a value derived from the class name
  • namespace - String; specifies the target namespace of the global element; default is the target namespace of the package

@XmlEnum

@XmlEnum is used on a an enum to specify that it is mapped to an enum-type simple schema type. An @XmlEnum annotation is default on any enum connected to a JAXB context.

  • value - Class; specifies the java type to which the schema type (specified or defaulted using @XmlType) is mapped; default is java.lang.String

@XmlTransient

@XmlTransient is used on a a class to indicate that it should not be mapped to XML by itself. It can still have JAXB mapped fields/properties, it may be referred to by other JAXB classes, and it may be extended. A class annotated with @XmlTransient should have no other class-targetted JAXB annotations.

@XmlSeeAlso

@XmlSeeAlso is used on a a class to indicate that the classes listed are to be bound when the class is bound. It effectively statically references all listed classes.

  • value - Class[]; default is none

@XmlAccessorType

@XmlAccessorType is used on a type to indicate the access type for mappings within the class.

  • value - XmlAccessType; default value is the default for the package

@XmlAccessorOrder

@XmlAccessorOrder is used on a type to indicate the XML instance order of properties and fields that are mapped to XML elements (XML attributes are unordered by nature).

  • value - XmlAccessOrder; default value is the default for the package

@XmlJavaTypeAdapter

@XmlJavaTypeAdapter is used on a type to allow an "unmappable" class to be mapped by proxy. If you have a class "Foo" that doesn't fit the JAXB paradigm, you can declare an @XmlJavaTypeAdapter(value=FooAdapter.class) on the class to indicate that when JAXB classes refer to instances of Foo, then FooAdapter should be used to map the XML.

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

@XmlJavaTypeAdapters is not supported on Types.

@XmlInlineBinaryData

@XmlInlineBinaryData is used on a type to enable declarative control over the optimization for binary data. (See spec, Appendix H)

@XmlRegistry

@XmlRegistry is a special type-level annotation used to specify a class that is used as an object factory. It is not a JAXB class, per se, but it is used to connect other classes to the JAXB context when a package is specified, and it may be used in validation in conjunction with @XmlElementRef(s) and @XmlElementDecl annotations. see ObjectFactory

Code Completion

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