Resin Documentation

jaxb annotations for soa/ioc

JAXB annotations customize the serialization of a model bean.

@XmlAccessorType sets default field and property serializability. By default, JAXB serializes public fields and properties. By setting @XmlAccessorType, the bean can choose to only allow annotated fields to be serialized.

@XmlAccessorType works with the other annotations and @XmlTransient to serialize fields and properties. @XmlTransient prevents serialization, overriding the @XmlAccessorType. The presense of any other annotation will force serialization, overriding the @XmlAccessorType.

@XmlAccessorType(XmlAccessType.FIELD)
class Bean {
  private String data;
}

<Bean>
  <data>Sample Data</data>
</Bean>

@Target(value={PACKAGE,TYPE})
public @interface XmlAccessorType {
  public XmlAccessType value() default XmlAccessType.PUBLIC_MEMBER;
}

public enum XmlAccessType {
    FIELD, NONE, PROPERTY, PUBLIC_MEMBER;
}

@XmlAttribute marks a field or property as serialized to an XML attribute. By default, fields serialize to XML elements. It can also customize the XML attribute name and namespace.

@XmlAttribute can work with @XmlAccessorType to select which fields and properties should be serialized to XML. By default, public fields and properties will be serialized. Adding @XmlAttribute to a private field will mark that field as serializable.

@XmlAttribute can also customize the XML attribute name. By default, the XML attribute name is taken from the field name or the property name. The name() value of the @XmlAttribute annotation will override the default element name.

@XmlRootElement
class Bean {
  @XmlAttribute("sample-field")
  private String _myField;
}

<Bean sample-field="A sample value">
</Bean>

@Target(value={FIELD,METHOD})
public @interface XmlAttribute {
  public String name() default "##default";
  public boolean required() default false;
  public String namespace() default "##default";
}

@XmlElement marks a field or property as serialized to an XML element. It can also customize the XML element name and namespace.

@XmlElement can work with @XmlAccessorType to select which fields and properties should be serialized to XML. By default, public fields and properties will be serialized. Adding @XmlElement to a private field will mark that field as serializable.

@XmlElement can also customize the XML element name. By default, the XML element name is taken from the field name or the property name. The name() value of the @XmlElement annotation will override the default element name.

@XmlRootElement
class Bean {
  @XmlElement("sample-field")
  private String _myField;
}

<Bean>
  <sample-field>A sample value</sample-field>
</Bean>

@Target(value={FIELD,METHOD})
public @interface XmlElement {
  public String name() default "##default";
  public boolean nillable() default false;
  public boolean required() default false;
  public String namespace() default "##default";
  public String defaultValue() default "\u0000";
  public Class type() DEFAULT.class;
}

@XmlElements allows lists to contain multiple different tags. It contains a list of @XmlElement values allowed as values.

class Bean {
  @XmlElements({
    @XmlElement(name="a",type=BeanA.class),
    @XmlElement(name="b",type=BeanB.class)
  })
  private List<SubBean> data = new List<SubBean>();
}

class BeanA extends SubBean {
  @XmlValue
  private String data;
}

class BeanB extends SubBean {
  @XmlValue
  private String data;
}

<Bean>
  <a>Some BeanA Data</a>
  <b>Some BeanB Data</b>
  <a>Another BeanA Data</a>
</Bean>

@Target(value={FIELD,METHOD})
public @interface XmlElements {
  public XmlElement[] value();
}

@XmlElementWrapper adds a wrapper XML tag for list values. By default, JAXB list values are serialized directly without any extra tags. @XmlElementWrapper adds a container XML tags.

class Bean {
  @XmlElementWrapper(name="values")
  private List<String> data = new ArrayList<String>();
}

<Bean>
  <values>
    <data>Some data</data>
    <data>Another item</data>
    <data>Third item</data>
  </values>
</Bean>

@Target(value={FIELD,METHOD})
public @interface XmlElementWrapper {
  public String name() default "##default";
  public String namespace() default "##default";
  public boolean nillable() default false;
}

@XmlJavaTypeAdapter specifies a Java class which converts helper values to final values.

In some cases, the Java model may not directly match the XML model. For example, it's complicated to represent Java maps in XML. The @XmlJavaTypeAdapter provides a standard way of managing complex types.

class Bean {
  @XmlJavaTypeAdapter(MyMapAdapter.class)
  private HashMap<String,String> map;
}

class MyMapAdapter
  extends XmlAdapter<Temp,Map<String,String>> {
  ...
}

class Temp {
  @XmlElement
  private List<Item> entry = new ArrayList<item>();
}

class Item {
  @XmlAttribute
  private String key;

  @XmlAttribute
  private String value;
}

<Bean>
  <entry key="a" value="data-a"/>
  <entry key="b" value="data-b"/>
  <entry key="c" value="data-c"/>
</Bean>

@Target({PACKAGE, FIELD, METHOD, TYPE, PARAMETER})
public @interface XmlJavaTypeAdapter {
  Class<? extends XmlAdapter> value();
  Class type() default DEFAULT.class;
}

@XmlRootElement marks a class as a top-level XML node. @XmlRootElement can also be used with @XmlElementRef to handle some inheritance situations.

The name() value of @XmlRootElement customizes the XML name used to serialize a top-level element. The default value is the class name.

@XmlRootElement(name="my-bean")
class Bean {
  public String data;
}

<my-bean>
  <data>A sample value</data>
</my-bean>

@Target(value=TYPE)
public @interface XmlRootElement {
  public String name() default "##default";
  public String namespace() default "##default";
}

@XmlTransient marks a field or property as unserializable. JAXB will ignore the transient field.

@Target(value={FIELD,METHOD})
public @interface XmlTransient {
}

@XmlValue marks a single field as representing the entire content of the bean. If a bean has an @XmlValue annotation, no other property or field may be serialized.

class Bean {
  @XmlValue
  private String data;
}

<Bean>Sample Data</Bean>

@Target(value={FIELD,METHOD})
public @interface XmlValue {
}