Revision as of 12:05, 15 October 2010

Functional Specification: JAXB Package Annotations

bug 327912 - Resource model support for JAXB 2.2 package annotations

Document History

Feature overview

This feature is about support for JAXB package annotations

Goals:

• Support the ability to annotate packages
• Support JAXB package level annotations and default values
  • @XmlSchema
  • @XmlNs
  • @XmlAccessorType
  • @XmlAccessorOrder
  • @XmlSchemaType/Types
  • @XmlJavaTypeAdapter/Adapters
• Support JAXB package level enums
  • XmlNsForm
  • XmlAccessType
  • XmlAccessOrder

Concepts

Package annotations could conceivably be placed on a package declaration of any class within a package, but in truth, in eclipse, it is only possible to annotate the package-info.java file. Annotating any other package declaration leads to a compile error. In addition, it is extremely unlikely that any externally compiled classes (e.g. jars) come from anything other than file-system-based java implementations, and so extremely unlikely that we'll have to deal with anything other than package annotations only being on the package-info "class".

Dali does not currently support package-info.java annotations, so that is the first technical hurdle. However, much has already been done in bug 265087.

References

Java Language Specification: Packages

Bug 265087: Package-level annotations support

Requirements / Functionality

Support package level annotations

See above comments and reference

@XmlSchema

@XmlSchema is used on a package to declare its namespace and any prefixes to be used for included namespaces. This can be used with the above described namespace-to-schema map to validate mappings within this package and eventually to help users edit mapping information. It also includes information for whether attributes and elements are to be prefixed in instance documents.

• namespace - String; specifies target namespace URI to be used for XML instances representing this package; default value is no namespace
• xmlns - @XmlNs array; specifies prefixes for namespaces involved in XML instances representing this package; default is no prefixes
• location - String; specifies location of (previously generated) schema; default is no location
• attribute/elementFormDefault - XmlNsForm; specifies whether XML instances should have attributes/elements prefix qualified; default is UNSET

@XmlNs

@XmlNs is used within an @XmlSchema annotation to provide prefix information for namespaces used in instance documents.

• namespaceURI - namespace to be given prefix
• prefix - prefix to be used

@XmlAccessorType

@XmlAccessorType is used on a package or a type to indicate the access type for mappings within JAXB classes. If used on a package, it specifies the default access type for classes within the package.

• value - XmlAccessType; default value is PUBLIC_MEMBER

@XmlAccessorOrder

@XmlAccessorOrder is used on a package or a type to indicate the XML instance order of properties and fields that are mapped to XML elements (XML attributes are unordered by nature). If used on a package, it specifies the default access order for classes within the package.

• value - XmlAccessOrder; default value is UNDEFINED

@XmlSchemaType/Types

@XmlSchemaType is used on a package, field or method, and allows a custom mapping to a built in XML schema type (or other similar simple atomic types). When used on a package, it becomes the default for all mappings using that type in the package.

• name - String; specifies the name of the datatype
• namespace - String; specifies the namespace of the datatype; default is the XML schema namespace ("http://www.w3.org/2001/XMLSchema")
• type - Class; specifies the java type which uses the given datatype; must be specified when annotation is used at the package level

@XmlSchemaTypes is used a container for multiple @XmlSchemaType annotations.

@XmlJavaTypeAdapter/Adapters

@XmlJavaTypeAdapter is used on a package, type, field or method (or parameter), and is one of the coolest features of JAXB. It allows 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, type=Foo.class) on the package (or without the type variable if declared on the class) to indicate that when JAXB classes refer to instances of Foo, then FooAdapter should be used to map the XML.

See here for more.

@XmlJavaTypeAdapters is used a container for multiple @XmlJavaTypeAdapter annotations.

Code Completion

Code completion should be implemented where feasible to help users with values. Note that code completion has not been implemented by the JDT for package level annotations. Perhaps we could also provide some basic annotation code assist here to help. bug 326610