Guide to JAXB Annotations
Learn about JAXB annotations in detail along with their usage during marshalling and unmarshalling operations on Java beans.
| Annotation | Scope | Description |
|---|---|---|
| @XmlRootElement | Class, Enum | Defines the XML root element. Root Java classes must be registered with the JAXB context when created. |
| @XmlAccessorType | Package, Class | Defines the fields and properties of your Java classes that the JAXB engine uses for binding. It has four values: PUBLIC_MEMBER , FIELD , PROPERTY and NONE . |
| @XmlAccessorOrder | Package, Class | Defines the sequential order of the children. |
| @XmlType | Class, Enum | Maps a Java class to a schema type. It defines the type name and order of its children. |
| @XmlElement | Field | Maps a field or property to an XML element |
| @XmlAttribute | Field | Maps a field or property to an XML attribute |
| @XmlTransient | Field | Prevents mapping a field or property to the XML Schema |
| @XmlValue | Field | Maps a field or property to the text value on an XML tag. |
| @XmlList | Field, Parameter | Maps a collection to a list of values separated by space. |
| @XmlElementWrapper | Field | Maps a Java collection to an XML-wrapped collection |
This maps a class or an enum type to an XML root element. 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.
@XmlRootElement(name = "employee") @XmlAccessorType(XmlAccessType.PROPERTY) public class Employee implements Serializable < //More code >The above will result into:
It defines the class fields that the JAXB engine uses for including into generated XML. It has four possible values.
- FIELD – Every non-static, non-transient field in a JAXB-bound class will be automatically bound to XML, unless annotated by XmlTransient .
- NONE – None of the fields or properties is bound to XML unless they are specifically annotated with some of the JAXB annotations.
- PROPERTY – Every getter/setter pair in a JAXB-bound class will be automatically bound to XML, unless annotated by XmlTransient .
- PUBLIC_MEMBER – Every public getter/setter pair and every public field will be automatically bound to XML, unless annotated by XmlTransient .
- Default value is PUBLIC_MEMBER .
@XmlRootElement(name = "employee") @XmlAccessorType(XmlAccessType.FIELD) public class Employee implements Serializable
The above will result into:
It controls the ordering of fields and properties in the generated XML. We can have predefined values ALPHABETICAL or UNDEFINED .
@XmlRootElement(name = "employee") @XmlAccessorOrder(AccessorOrder.ALPHABETICAL) public class Employee implements Serializable
The above will result into:
It maps a Java class or enum type to a schema type. It defines the type name, namespace and order of its children. It is used to match the element in the schema to the element in the model.
@XmlRootElement(name = "employee") @XmlType(propOrder=) public class Employee implements Serializable
It maps a JavaBean property to an XML element derived from the property name.
@XmlRootElement(name = "employee") public class Employee implements Serializable
The above will result into:
It maps a JavaBean property to an XML attribute.
@XmlRootElement(name = "employee") public class Employee implements Serializable
The above will result into:
It prevents the mapping of a JavaBean property/type to XML representation. When placed on a class, it indicates that it shouldn’t be mapped to XML. Properties on such class will be mapped to XML along with its derived classes as if the class is inlined.
@XmlTransient is mutually exclusive with all other JAXB-defined annotations.
@XmlRootElement(name = "employee") @XmlAccessorType(XmlAccessType.FIELD) public class Employee implements Serializable
The above will result into:
It enables mapping a class to an XML Schema complex type with simple content or an XML Schema simple type. It’s more related to schema mapping to model mapping.
It is used to map a property to a List simple type. It allows multiple values to be represented as whitespace-separated tokens in a single element.
@XmlRootElement(name = "employee") @XmlAccessorType(XmlAccessType.FIELD) public class Employee implements Serializable < private Listhobbies; >After using @XmlList , observe the output.
@XmlRootElement(name = "employee") @XmlAccessorType(XmlAccessType.FIELD) public class Employee implements Serializable < @XmlList private Listhobbies; >Generates a wrapper element around XML representation. This is primarily intended to be used to produce a wrapper XML element around collections. So, it must be used with collection property.
@XmlRootElement(name = "employee") @XmlAccessorType(XmlAccessType.FIELD) public class Employee implements Serializable < @XmlElementWrapper(name="hobbies") @XmlElement(name="hobby") private Listhobbies; >The above will result into:
2. JAXB Annotation Example
Learn to apply JAXB annotations on model classes and then marshal the object into the XML file.
import java.io.Serializable; import java.util.List; import javax.xml.bind.annotation.XmlAccessType; import javax.xml.bind.annotation.XmlAccessorType; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlElementWrapper; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement(name = "employee") @XmlAccessorType(XmlAccessType.FIELD) public class Employee implements Serializable < private Integer id; private String firstName; private String lastName; private Department department; @XmlElementWrapper(name="hobbies") @XmlElement(name="hobby") private Listhobbies; //Constructors, Setters and Getters >The following code marshals an instance of the Employee class.
import java.io.File; import java.util.Arrays; import javax.xml.bind.JAXBContext; import javax.xml.bind.JAXBException; import javax.xml.bind.Marshaller; import com.howtodoinjava.demo.model.Department; import com.howtodoinjava.demo.model.Employee; public class JaxbExample < public static void main(String[] args) < Employee employee = new Employee(1, "Lokesh", "Gupta", new Department(101, "IT")); employee.setHobbies(Arrays.asList("Swimming","Playing", "Karate")); jaxbObjectToXML(employee); >private static void jaxbObjectToXML(Employee employee) < try < JAXBContext jaxbContext = JAXBContext.newInstance(Employee.class); Marshaller jaxbMarshaller = jaxbContext.createMarshaller(); jaxbMarshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE); // To format XML //Print XML String to Console jaxbMarshaller.marshal(employee, new File("employee.xml")); >catch (JAXBException e) < e.printStackTrace(); >> > 1 Lokesh Gupta 101 IT Swimming Playing Karate Drop me your questions in the comments section.
Customizing Generated Classes and Java Program Elements
The following sections describe how to customize generated JAXB classes and Java program elements.
Schema-to-Java
Custom JAXB binding declarations enable you to customize your generated JAXB classes beyond the XML-specific constraints in an XML schema to include Java-specific refinements, such as class and package name mappings.
JAXB provides two ways to customize an XML schema:
- As inline annotations in a source XML schema
- As declarations in an external binding customization file that is passed to the JAXB binding compiler
Code examples that show how to customize JAXB bindings are provided later in this document.
Java-to-Schema
The JAXB annotations defined in the javax.xml.bind.annotation package can be used to customize Java program elements to XML schema mapping. The following table summarizes the JAXB annotations that can be used with a Java package.
Table: JAXB Annotations Associated with a Java Package
@XmlSchema ( xmlns = <>, namespace = "", elementFormDefault = XmlNsForm.UNSET, attributeFormDefault = XmlNsForm.UNSET )
@XmlAccessorType ( value = AccessType.PUBLIC_MEMBER )
@XmlAccessorOrder ( value = AccessorOrder.UNDEFINED )
@XmlSchemaType ( namespace = "http://www.w3.org/2001/XMLSchema", type = DEFAULT.class )
The following table summarizes JAXB annotations that can be used with a Java class.
Table: JAXB Annotations Associated with a Java Class
@XmlType ( name = "##default", propOrder = , namespace = "##default", factoryClass = DEFAULT.class, factoryMethod = "" )
@XmlRootElement ( name = "##default", namespace = "##default" )
The following table summarizes JAXB annotations that can be used with a Java enum type.
Table: JAXB Annotations Associated with a Java enum Type
@XmlEnum ( value = String.class )
@XmlType ( name = "##default", propOrder = , namespace = "##default", factoryClass = DEFAULT.class, factoryMethod = "" )
@XmlRootElement ( name = "##default", namespace = "##default" )
The following table summarizes JAXB annotations that can be used with Java properties and fields.
Table: JAXB Annotations Associated with Java Properties and Fields
@XmlElement ( name = "##default", nillable = false, namespace = "##default", type = DEFAULT.class, defaultValue = "\u0000" )
@XmlElementRef ( name = "##default", namespace = "##default", type = DEFAULT.class )
@XmlElementWrapper ( name = "##default", namespace = "##default", nillable = false )
@XmlAnyElement ( lax = false, value = W3CDomHandler.class )
@XmlAttribute ( name = ##default, required = false, namespace = "##default" )
The following table summarizes the JAXB annotation that can be used with object factories.
Table: JAXB Annotations Associated with Object Factories
@XmlElementDecl ( scope = GLOBAL.class, namespace = "##default", substitutionHeadNamespace = "##default", substitutionHeadName = "" )
The following table summarizes JAXB annotations that can be used with adapters.
Table: JAXB Annotations Associated with Adapters
@XmlJavaTypeAdapter ( type = DEFAULT.class )