Part 4: JAXB Annotations

This tutorial is part 4 of 5-part tutorial on JEE annotations. We recommend that you read Prerequisite section first, review the abstract and Example Application to understand the context. You can also jump to other parts by clicking on the links below.

JAXB Annotations - Contents:

AnnotationPackage Detail/Import statement
@XmlRootElementimport javax.xml.bind.annotation.XmlRootElement;
@XmlElementimport javax.xml.bind.annotation.XmlElement;
@XmlTypeimport javax.xml.bind.annotation.XmlType;
@XmlTransientimport javax.xml.bind.annotation.XmlTransient;
@XmlSeeAlsoimport javax.xml.bind.annotation.XmlSeeAlso;
Using JAXB and JPA Annotations in Conjunction
Using JAX-RS Annotations with JAXB and JPA Annotations

As stated earlier in Example Application, we are using JAXB to convert our Entities to XML or JSON format, so our rich clients like Ext-js or jQuery can easily process and present the data.

@XmlRootElement

Define the root element for the XML to be produced with @XmlRootElement JAXB annotation. The name of the root XML element is derived from the class name.
@XmlRootElement
public class Contact implements Serializable {
...
}
You can also specify the name of the root element of the XML using its name attribute, for example @XmlRootElement(name = "CompanyContact")

@XmlElement

Annotate all fields that needs to be included in XML/JSON output with @XMLElement.
  @XmlElement
  public String getName() {
    return name;
  }
Either annotate all fields or all getter methods in your Entity bean. A mix of both is not supported. Add @XmlAccessorType(XmlAccessType.FIELD) at the class level if you want to annotate private fields instead of getter methods.

@XmlType

Specify the order in which XML elements or JSON output will be produced.
@XmlRootElement
@XmlType(propOrder = { "id", "firstName", "lastName", "email", "telephone" })
public class Contact implements Serializable {
...
}
The above @XmlType annotation will produce the following XML.

	38
	FirstName
	LastName
	dummyEmail@techferry.com
	1111111111

Similarly, it will produce the following JSON.
{"id":"38","firstName":"FirstName","lastName":"LastName",
"email":"dummyEmail@techferry.com","telephone":"1111111111"}

@XmlTransient

Annotate fields that we do not want to be included in XML or JSON output with @XMLTransient.
  @XmlTransient
  public Date getVersion() {
    return version;
  }

@XmlSeeAlso

Use @XmlSeeAlso annotation when we want another Entity bean included in the XML output. In our example below, CompanyList bean refers to Company bean and the XML output should include XML generated from Company Entity too.
@XmlRootElement(name = "List")
@XmlSeeAlso(Company.class)
public class CompanyList {

  @XmlElement(name = "companyList")
  public List<Company> getList() {
    return list;
  }
...
}


To include more than 1 classes, we can use @XmlSeeAlso JAXB annotation as:
@XmlSeeAlso({ A.class, B.class })

Using JAXB and JPA Annotations in Conjunction

If you have reviewed both
Hibernate - JPA Annotations and JAXB Annotations, the following snippet illustrates usage of both JAXB and JPA annotations in the same entity Contact.
@Entity
@Table(name = "CONTACT")
@XmlRootElement
@XmlType(propOrder = { "id", "firstName", "lastName", "email", "telephone" })
public class Contact implements Serializable {

  @Id
  @Column(name = "ID")
  @GeneratedValue
  private Integer id;

  @Column(name = "firstName")
  private String firstName;

  @Column(name = "lastName")
  private String lastName;

  @Column(name = "EMAIL")
  private String email;

  @Column(name = "TELEPHONE")
  private String telephone;

  @Version
  @Column(name = "version")
  private Date version;

  @ManyToOne
  @JoinColumn(name = "companyId")
  private Company company;

  @OneToOne(mappedBy = "contact", cascade = CascadeType.ALL)
  private ContactDetail contactDetail;

  @XmlTransient
  public Company getCompany() {
    return company;
  }

  public void setCompany(Company company) {
    this.company = company;
  }

  @XmlTransient
  public ContactDetail getContactDetail() {
    return contactDetail;
  }

  public void setContactDetail(ContactDetail contactDetail) {
    this.contactDetail = contactDetail;
  }

  @XmlTransient
  public Date getVersion() {
    return version;
  }

  public void setVersion(Date version) {
    this.version = version;
  }

  @XmlElement
  public Integer getId() {
    return id;
  }

  public void setId(Integer id) {
    this.id = id;
  }

  @XmlElement
  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  @XmlElement
  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }

  @XmlElement
  public String getEmail() {
    return email;
  }

  public void setEmail(String email) {
    this.email = email;
  }

  @XmlElement
  public String getTelephone() {
    return telephone;
  }

  public void setTelephone(String telephone) {
    this.telephone = telephone;
  }

}

Using JAX-RS Annotations with JAXB and JPA Annotations

This section assumes that you have reviewed
RESTful JAX-RS Annotations, Hibernate - JPA Annotations and JAXB Annotations. Also see the section above on using JAXB and JPA Annotations in Conjunction.

Now that you have an entity bean containing both JAXB and JPA Annotations which is capable of doing data exchange with database and coverting it to required JSON/XML format, the next step is to send this data to rich clients using jQuery or Ext-js. In your REST based web-service methods, return the Contact entity bean as shown below. Jersey, JAXB will take care of data conversion and appropriate response generation.
  @GET
  @Produces("application/xml")
  @Path("xml/{firstName}")
  public Contact getXML(@PathParam("firstName") String firstName) {
    Contact contact = contactService.findByFirstName(firstName);
    return contact;
  }
  @GET
  @Produces("application/json")
  @Path("json/{firstName}")
  public Contact getJSON(@PathParam("firstName") String firstName) {
    Contact contact = contactService.findByFirstName(firstName);
    return contact;
  }

References:

  1. JAXB Annotations: http://docs.oracle.com/javaee/6/api/javax/xml/bind/annotation/package-summary.html