Conditional Get and Http Caching using Jersey

In this tutorial you will learn the conditional http feature using Jersey.The HTTP Protocol defines a caching mechanism, in which the proxy web-servers can cache pages, files, images etc. Since caching is in place, There is a method which the servers are asked to return the document, either the “cached” or “live” document.

This request of asking the server for a document considering a specific parameter is called a Conditional GET Request.

ETags or entity tags are useful HTTP headers which can help in building a super fast application by minimizing the server load on system. ETag is set to the response to the client so a client can use various control request headers such as If-Match and If-None-Match for conditional requests. javax.ws.rs.core.Response.ResponseBuilder#tag() and javax.ws.rs.core.EntityTag are useful classes to work on ETags.

On server side, a unchanged ETag (match done between ETag attached with HTTP request and ETag calculated for requested resource) simply means, resource is unchanged from last requested time, so simply sending a HTTP 304 header [Not Modified] will be enough so that client can use the local available copy of resource without worrying much.

To demonstrate the example, I have two REST APIs in Employee Service class.

a) GET http://localhost:8080/RestFileServer/service/employee-service/get-employee/1

This API will get the employee resource which will have a ETag attached to it. This ETag will be used by server to verify if employee details have been updated since last request or not.

b) PUT http://localhost:8080/RestFileServer/service/employee-service/update-employee/1

This API will update the employee resource and it  will force the server to return the new copy of resource again.

So Lets get started !

Employee.java

@XmlAccessorType(XmlAccessType.NONE)
@XmlRootElement(name = "employee")
public class Employee implements Serializable {
@JsonProperty("id")
private int id;

@JsonProperty("firstName")
private String firstName;

@JsonProperty("lastName")
private String lastName;

@JsonProperty("last-modified")

private Date lastModified;

......//getter setters .........

Now we will create a dummy Employee database EmployeeData.

public class EmployeeData 
{
    public static HashMap<Integer, Employee> employees = new HashMap<Integer, Employee>();
    static
    {
        Employee emp = new Employee();
        emp.setId(1);
        emp.setFirstName("Kuntal");
        emp.setLastName("Ganguly");
        emp.setLastModified(new Date());
        employees.put(1, emp);
    }
     
    public static Employee getEmployeeById(Integer id)
    {
        return employees.get(id);
    }
     
    public static void updateEmployee(Integer id)
    {
        Employee emp = employees.get(id);
        emp.setLastName("Gangopadhay");
        emp.setLastModified(new Date());
    }
     
    public static Date getLastModifiedById(Integer id)
    {
        return employees.get(id).getLastModified();
    }

}

Finally the Employee Service.

@Path("/employee-service")
public class EmployeeService 
{
    @GET
    @Produces(MediaType.APPLICATION_JSON )
    @Path("/get-employee/{id}")
    public Response getEmployeeById(@PathParam("id") int id, @Context Request req) 
    {
        //Create cache control header
         CacheControl cc = new CacheControl();
         //Set max age to one day
         cc.setMaxAge(86400);
             
        Response.ResponseBuilder rb = null;
         
        //Calculate the ETag on last modified date of user resource  
        EntityTag etag = new EntityTag(EmployeeData.getLastModifiedById(id).hashCode()+"");
         
        //Verify if it matched with etag available in http request
        rb = req.evaluatePreconditions(etag);
         
        //If ETag matches the rb will be non-null; 
        //Use the rb to return the response without any further processing
        if (rb != null) 
        {
            return rb.cacheControl(cc).tag(etag).build();
        }
         
        //If rb is null then either it is first time request; or resource is modified
        //Get the updated representation and return with Etag attached to it
        rb = Response.ok(EmployeeData.getEmployeeById(id)).cacheControl(cc).tag(etag);
        return rb.build();
    }
     
    @PUT
    @Produces(MediaType.APPLICATION_JSON )
    @Path("/update-employee/{id}")
    public Response updateEmployeeById(@PathParam("id") int id) 
    {
        //Update the Employee resource
        EmployeeData.updateEmployee(id);
        return Response.status(200).build();
    }

}

After building and deploying this service in your server.You can navigate to the following and Validate:

1) First time request : GET http://localhost:8080/RestFileServer/service/employee-service/get-employee/1

2) Subsequent request(s) : GET http://localhost:8080/RestFileServer/service/employee-service/get-employee/1

3) Modify request : PUT http://localhost:8080/RestFileServer/service/employee-service/update-employee/1

4) Updated Resource : GET http://localhost:8080/RestFileServer/service/employee-service/get-employee/1

Hope you understand the http Caching and Conditional Get. :)
Download code