JAXB - Annotations, Controlling Element Selection: XmlAccessorType, XmlTransient

If JAXB binds a class to XML, then, by default, all public members will be bound, i.e., public getter and setter pairs, or public fields. Any protected, package-visible or private member is bound if it is annotated with a suitable annotation such as XmlElement or XmlAttribute. You have several possibilities to influence this default behaviour.

You can annotate a package or a top level class with XmlAccessorType, setting its value element to one of the enum constants FIELD, PROPERTY, PUBLIC_MEMBER or NONE. If FIELD is set every non static, non transient field will be automatically bound. PROPERTY instructs JAXB to do this for getter and setter pairs. NONE suppresses bind except for explicitly annotated fields or properties. A class without this annotation inherits the XmlAccessorType setting either from its superclass or from the package setting.

The other annotation to be mentioned in this context is XmlTransient. It suppresses binding for its target which can be an entire class or a field or a method. This is also useful if you have a name clash resulting from a public field, say foo, and methods getFoo and setFoo.

The first class illustrates a class that restricts the set of XML elements from an accessor type setting of PUBLIC_MEMBER. Member getB is blocked from being bound.

@XmlAccessorType( XmlAccessType.PUBLIC_MEMBER )
public class SomeClass {
    private String a;
    private String b;

    public SomeClass(){ ... }

    public String getA(){ ... }
    public void setA( String value ){ ... }

    @XmlTransient
    public String getB(){ ... }
    public void setB( String value ){ ... }
}

The corresponding XML schema type definition looks like this:

<xs:complexType name="someClass">
    <xs:sequence>
        <xs:element name="a" type="xs:string" minOccurs="0"/>
    </xs:sequence>
</xs:complexType>

The second example illustrates the reverse process. It shows a class with the most restrictive accessor type setting, with one member explicitly annotated as an element.

@XmlAccessorType( XmlAccessType.NONE )
public class OtherClass {
    private String a;
    private String b;

    public OtherClass(){ ... }

    public String getA(){ ... }
    public void setA( String value ){ ... }

    @XmlElement( required = true )
    public String getB(){ ... }
    public void setB( String value ){ ... }
}

Since we have set the annotation element required to true, the generated schema snippet is slightly different:

<xs:complexType name="otherClass">
    <xs:sequence>
        <xs:element name="b" type="xs:string"/>
    </xs:sequence>
</xs:complexType>

The final example for this topic demonstrates using these annotations in somewhat special circumstances. First, XmlTransient is used on the public field to avoid the name clash with the method pair. Second, XmlElement is used to request binding for getB, which doesn't have its setB spouse. (The getter follows the standard pattern of the JAXB generated Java code for elements bound to List<?>, with changes being made on the list object.)

@XmlAccessorType( XmlAccessType.PUBLIC_MEMBER )
public class SpecialClass {
    @XmlTransient
    public String a;
    private List<String> b;

    public SpecialClass(){ ... }

    public String getA(){ ... }
    public void setA( String value ){ ... }

    @XmlElement
    public List<String> getB(){
        if( b == null ) b = new ArrayList<String>();
        return b;
    }
}

The generated complex type features both elements.

<xs:complexType name="specialClass">
    <xs:sequence>
        <xs:element name="a" type="xs:string" minOccurs="0"/>
        <xs:element name="b" type="xs:string" maxOccurs="unbounded" minOccurs="0"/>
    </xs:sequence>
</xs:complexType>

Taken together, this means that you can, either at package level or at some superclass, define the strategy for all classes within the package or for all subclasses, respectively. This strategy may be generally permissive, oriented on fields or properties, or restrictive, permitting nothing by default. Within a class, you may extend a restrictive setting by adding XmlElement or XmlAttribute, or you may inhibit bindings using the XmlTransient annotation.