If you want more control over the marshalling and unmarshalling of objects, such as skipping some fields or renaming field names, you can use the Java Architecture for XML Binding (JAXB) annotations to indicate this to the runtime. Let's take a quick look at this feature.

JAXB allows Java developers to access and process the XML data without worrying about the XML structure of the content. JAXB offers annotations that map XML to the Java class and vice versa, letting you work on the Java objects. JAX-RS can automatically read and write both XML and JSON by using JAXB. Our discussions in this section are focused on using the JAXB annotation for managing the serialization of Java objects.

Here is a brief description of the commonly used JAXB annotations to control the serialization of Java objects:

• @javax.xml.bind.annotation.XmlRootElement: When a top-level class is annotated with the @XmlRootElement annotation, the JAX-RS runtime takes care of the serialization of all its instances at runtime.
• @javax.xml.bind.annotation.XmlAccessorType: This annotation controls whether the fields or JavaBean properties are serialized by default. It takes the following values:
  • XmlAccessType.FIELD: Every non-static, non-transient field will be copied in an XML or JSON representation
  • XmlAccessType.NONE: No fields are copied
  • XmlAccessType.PROPERTY: Every getter/setter pair will be copied in an XML or JSON representation
  • XmlAccessType.PUBLIC_MEMBER: Every public field and public getter/setter pair will be copied in an XML or JSON representation

• @javax.xml.bind.XmlElement: This value maps a JavaBean property to an XML or JSON element derived from the property name
• @javax.xml.bind.XmlTransient: This value prevents the mapping of a JavaBean property/type to JSON

Consider the following Department object with the JAXB annotation to manage the serialization of contents:

//Other imports removed for brevity 
import javax.xml.bind.annotation.XmlAccessType; 
import javax.xml.bind.annotation.XmlAccessorType; 
import javax.xml.bind.annotation.XmlElement; 
import javax.xml.bind.annotation.XmlRootElement; 
import javax.xml.bind.annotation.XmlTransient;  
 
@XmlRootElement(name="department") 
@XmlAccessorType(XmlAccessType.FIELD) 
public class Department implements Serializable { 
  @XmlElement(name="departmentId") 
  private Short id; 
  private String departmentName; 
  @XmlTransient 
  public List<Employee> employees; 
  //Rest of the code removed for brevity 
} 

Let's see how the JAX-RS runtime makes use of the JAXB annotations while serializing results returned by a resource method into the JSON representation:

1. The following resource class method returns the Department object in response to a GET request, for example, GET /departments/10 HTTP/1/1:

@GET 
@Path("{id}") 
@Produces(MediaType.APPLICATION_JSON) 
public Department find(@PathParam("id") Short id) { 
  return findDepartmentEntity(id); 
} 

2. The JAX-RS runtime deploys entity providers that implement javax.ws.rs.ext.MessageBodyWriter to serialize Java objects into an appropriate output stream representation, such as JSON or XML. The MessageBodyWriter implementation scans through the JAXB annotations defined on the Department class and converts values to the JSON data, as appropriate.

The sample JSON output produced by the preceding resource class method will look like the following code:

{"departmentId":30, 
  "departmentName":"HR"} 

Note that the List<Employee> employees field that you see in the Department class is not present in the JSON output data because this field is marked as @XmlTransient in the class definition. Furthermore, @XmlElement(name="departmentId") for the id field causes the provider to rename id to departmentId in the JSON representation.

You now have enough information on all the commonly used JAX-RS annotations that you will need for a RESTful web service. Let's move on and build a simple RESTful web service by using JAX-RS to get a real feel of the topics that we have discussed so far in this chapter.