Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


 

Resin Documentation

home company blog wiki docs 
app server web server 
health cloud java ee pro 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

jaxb annotations for soa/ioc


JAXB annotations customize the serialization of a model bean.

@XmlAccessorType

@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 values
NONEOnly annotated fields and properites should be serialized>
FIELDAll fields (public or private) should be serialized>
PROPERTYAll properties (public or private) should be serialized>
PUBLIC_MEMBERPublic fields and properties>
@XmlAccessorType serializing fields
@XmlAccessorType(XmlAccessType.FIELD)
class Bean {
  private String data;
}
XML Document
<Bean>
  <data>Sample Data</data>
</Bean>
@XmlAccessorType
@Target(value={PACKAGE,TYPE})
public @interface XmlAccessorType {
  public XmlAccessType value() default XmlAccessType.PUBLIC_MEMBER;
}
XmlAccessType
public enum XmlAccessType {
    FIELD, NONE, PROPERTY, PUBLIC_MEMBER;
}

@XmlAttribute

@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.

@XmlAttribute for a private field
@XmlRootElement
class Bean {
  @XmlAttribute("sample-field")
  private String _myField;
}
XML document for the Bean
<Bean sample-field="A sample value">
</Bean>
@XmlAttribute definition
@Target(value={FIELD,METHOD})
public @interface XmlAttribute {
  public String name() default "##default";
  public boolean required() default false;
  public String namespace() default "##default";
}

@XmlElement

@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.

@XmlElement for a private field
@XmlRootElement
class Bean {
  @XmlElement("sample-field")
  private String _myField;
}
XML document for the Bean
<Bean>
  <sample-field>A sample value</sample-field>
</Bean>
@XmlElement definition
@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

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

@XmlElement allowing two tags
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;
}
XML document for the example
<Bean>
  <a>Some BeanA Data</a>
  <b>Some BeanB Data</b>
  <a>Another BeanA Data</a>
</Bean>
@XmlElements definition
@Target(value={FIELD,METHOD})
public @interface XmlElements {
  public XmlElement[] value();
}

@XmlElementWrapper

@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.

Bean example with @XmlElementWrapper
class Bean {
  @XmlElementWrapper(name="values")
  private List<String> data = new ArrayList<String>();
}
XML document for example
<Bean>
  <values>
    <data>Some data</data>
    <data>Another item</data>
    <data>Third item</data>
  </values>
</Bean>
@XmlElementWrapper definition
@Target(value={FIELD,METHOD})
public @interface XmlElementWrapper {
  public String name() default "##default";
  public String namespace() default "##default";
  public boolean nillable() default false;
}

@XmlJavaTypeAdapter

@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.

Maps in a Bean
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;
}
XML Document
<Bean>
  <entry key="a" value="data-a"/>
  <entry key="b" value="data-b"/>
  <entry key="c" value="data-c"/>
</Bean>
@XmlJavaTypeAdapter
@Target({PACKAGE, FIELD, METHOD, TYPE, PARAMETER})
public @interface XmlJavaTypeAdapter {
  Class<? extends XmlAdapter> value();
  Class type() default DEFAULT.class;
}

@XmlRootElement

@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 for renaming
@XmlRootElement(name="my-bean")
class Bean {
  public String data;
}
XML document for the Bean
<my-bean>
  <data>A sample value</data>
</my-bean>
@XmlRootElement definition
@Target(value=TYPE)
public @interface XmlRootElement {
  public String name() default "##default";
  public String namespace() default "##default";
}

@XmlTransient

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

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

@XmlValue

@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.

@XmlValue filling a bean
class Bean {
  @XmlValue
  private String data;
}
XML document for @XmlValue
<Bean>Sample Data</Bean>
@XmlValue definition
@Target(value={FIELD,METHOD})
public @interface XmlValue {
}

Copyright © 1998-2012 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.

Cloud-optimized Resin Server is a Java EE certified Java Application Server, and Web Server, and Distributed Cache Server (Memcached).
Leading companies worldwide with demand for reliability and high performance web applications including SalesForce.com, CNET, DZone and many more are powered by Resin.

home company blog wiki docs 
app server web server 
health cloud java ee pro