javax.xml.bind.annotation

Defines annotations for customizing Java program elements to XML Schema mapping.

Package Specification

The following table shows the JAXB mapping annotations that can be associated with each program element.

Terminology

JavaBean property and field: For the purposes of mapping, there is no semantic difference between a field and a JavaBean property. Thus, an annotation that can be applied to a JavaBean property can always be applied to a field. Hence in the Javadoc documentation, for brevity, the term JavaBean property or property is used to mean either JavaBean property or a field. Where required, both are explicitly mentioned.

top level class: For the purpose of mapping, there is no semantic difference between a top level class and a static nested class. Thus, an annotation that can be applied to a top level class, can always be applied to a nested static class. Hence in the Javadoc documentation, for brevity, the term "top level class" or just class is used to mean either a top level class or a nested static class.

mapping annotation:A JAXB 2.0 defined program annotation based on the JSR 175 programming annotation facility.

Common Usage Constraints

The following usage constraints are defined here since they apply to more than annotation:

• For a property, a given annotation can be applied to either read or write property but not both.
• A property name must be different from any other property name in any of the super classes of the class being mapped.
• A mapped field name or the decapitalized name of a mapped property must be unique within a class.

Notations

The following namespace prefixes are used in the XML Schema fragments in this package.

Prefix	Namespace	Notes
xs	http://www.w3.org/2001/XMLSchema	Namespace of XML Schema namespace
ref	http://ws-i.org/profiles/basic/1.1/xsd	Namespace for swaref schema component
xsi	http://www.w3.org/2001/XMLSchema-instance	XML Schema namespace for instances

@since JAXB 2.0

Implementations of this interface will be used in conjunction with XmlAnyElement annotation to map an element of XML into a representation of infoset such as W3C DOM.

Implementations hide how a portion of XML is converted into/from such DOM-like representation, allowing JAXB providers to work with arbitrary such library.

This interface is intended to be implemented by library writers and consumed by JAXB providers.

Controls the ordering of fields and properties in a class.

Controls whether fields or Javabean properties are serialized by default.

Maps a JavaBean property to a map of wildcard attributes.

Usage

The @XmlAnyAttribute annotation can be used with the following program elements:

• JavaBean property
• non static, non transient field

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

• At most one field or property in a class can be annotated with @XmlAnyAttribute.

This annotation serves as a "catch-all" property while unmarshalling xml content into a instance of a JAXB annotated class.

Maps a JavaBean property to a XML attribute.

Usage

@XmlElement annotation can be used with the following program elements:

• a JavaBean property
• non static, non transient field
• within XmlElements

• This annotation can be used with following annotations: XmlID , XmlIDREF , XmlList , XmlSchemaType , XmlValue , XmlAttachmentRef , XmlMimeType , XmlInlineBinaryData , XmlElementWrapper , XmlJavaTypeAdapter
• if the type of JavaBean property is a collection type of array, an indexed property, or a parameterized list, and this annotation is used with XmlElements then, @XmlElement.type() must be DEFAULT.class since the collection item type is already known.

Usage

Maps a JavaBean property to a XML element derived from property's type.

Usage

@XmlElementRef annotation can be used with a JavaBean property or from within XmlElementRefs

This annotation dynamically associates an XML element name with the JavaBean property.

A container for multiple @ XmlElement annotations. Multiple annotations of the same type are not allowed on a program element.

Maps an enum type Enum to XML representation.

This annotation, together with XmlEnumValue provides a mapping of enum type to XML representation.

Usage

The @XmlEnum annotation can be used with the following program elements:

• enum type

The usage is subject to the following constraints:

• This annotation can be used the following other annotations: XmlType , XmlRootElement

See "Package Specification" in javax.xml.bind.package javadoc for additional common information

An enum type is mapped to a schema simple type with enumeration facets.

Maps a JavaBean property to XML ID.

To preserve referential integrity of an object graph across XML serialization followed by a XML deserialization, requires an object reference to be marshalled by reference or containment appropriately.

Maps a JavaBean property to XML IDREF.

To preserve referential integrity of an object graph across XML serialization followed by a XML deserialization, requires an object reference to be marshalled by reference or containment appropriately.

When XOP encoding is enabled as described in AttachmentMarshaller.isXOPPackage , this annotation disables datatypes such as Image or Source or byte[] that are bound to base64-encoded binary from being considered for XOP encoding.

Usage

The @XmlList annotation can be used with the following program elements:

• JavaBean property
• field

When a collection property is annotated just with @XmlElement, each item in the collection will be wrapped by an element. For example,

 @XmlRootElement
 class Foo {
 @XmlElement
 List<String> data;
 }
 

 <foo>
 <data>abc</data>
 <data>def</data>
 </foo>
 

This annotation is used in conjunction with datatypes such as Image or Source that are bound to base64-encoded binary in XML.

If a property that has this annotation has a sibling property bound to the xmime:contentType attribute, and if in the instance the property has a value, the value of the attribute takes precedence and that will control the marshalling.

Annotate a JavaBean multi-valued property to support mixed content.

The usage is subject to the following constraints:

• can be used with @XmlElementRef, @XmlElementRefs or @XmlAnyElement

The following can be inserted into @XmlMixed annotated multi-valued property

• XML text information items are added as values of java.lang.String.
• Children element information items are added as instances of JAXBElement or instances with a class that is annotated with @XmlRootElement.
• Unknown content that is not be bound to a JAXB mapped class is inserted as Element .

Associates a namespace prefix with a XML namespace URI.

Usage

The @XmlRootElement annotation can be used with the following program elements:

• a top level class
• an enum type

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

When a top level class or an enum type is annotated with the @XmlRootElement annotation, then its value is represented as XML element in an XML document.

This annotation can be used with the following annotations: XmlType , XmlEnum , XmlAccessorType , XmlAccessorOrder .

Example 1: Associate an element with XML Schema type

 // Example: Code fragment
 @XmlRootElement
 class Point {
 int x;
 int y;
 Point(int _x,int _y) {x=_x;y=_y;}
 }
 

 //Example: Code fragment corresponding to XML output
 marshal( new Point(3,5), System.out);
 

 <!-- Example: XML output -->
 <point>
 <x> 3 </x>
 <y> 5 </y>
 </point>
 

Maps a package name to a XML namespace.

Usage

@XmlSchemaType annotation can be used with the following program elements:

• a JavaBean property
• field
• package

@XmlSchemaType annotation defined for Java type applies to all references to the Java type from a property/field.

A container for multiple @ XmlSchemaType annotations.

Multiple annotations of the same type are not allowed on a program element.

Java makes it impractical/impossible to list all sub-classes of a given class.

Prevents the mapping of a JavaBean property/type to XML representation.

The @XmlTransient annotation is useful for resolving name collisions between a JavaBean property name and a field name or preventing the mapping of a field/property.

Maps a class or an enum type to a XML Schema type.

Usage

The @XmlType annnotation can be used with the following program elements:

• a top level class
• an enum type

See "Package Specification" in javax.xml.bind.package javadoc for additional common information.

Mapping a Class

A class maps to a XML Schema type.

Enables mapping a class to a XML Schema complex type with a simpleContent or a XML Schema simple type.