The Cache-Control header was defined as part of HTTP/1.1 and offers more options than the Expires HTTP header. This header is used for specifying the directives that must be obeyed by all caching mechanisms involved in HTTP communication. These directives indicate who can do the caching of a resource returned by the server, how the caching is done, and for how long the resource can be cached.

Here is a list of useful Cache-Control directives:

• private: This directive indicates only those clients who originally requested the resource (for example, browser). This directive can do the caching and no other entity in the request-response chain (for example, proxy) is expected to do the caching.
• public: This marks a response as cacheable and caching can be done by any entity in the request-response chain.
• no-cache: This directive tells the client (for example, browser or proxies) that it should validate with the server before serving the resource from the cache. The validation can be done with the server by sending a request with the appropriate header fields, such as If-Modified-Since, If-Unmodified-Since, If-Match, and If-None-Match.
• no-store: This directive indicates that a response can be cached (for example, in-memory), but should not be stored on a permanent storage (for example, disk).
• no-transform: This directive means that the resource should not be modified by any entity in the request-response chain. This directive is used for avoiding loss of data while transforming a response from one format to another by intermediate entities.
• max-age: This value (measured in seconds) indicates how long the cached resource will be considered fresh. After this, the cached content needs to be validated with the server while serving the next request.
• s-maxage: This directive is similar to the max-age directive, except that it only applies to shared (for example, proxy) caches, not for the client who originated the request.
• must-revalidate: This directive tells all caches that they must follow the freshness information set by the server while generating the resource. Note that the HTTP protocol allows caches to serve stale resources under special conditions. By specifying the must-revalidate directive in the header of a response, you are telling all caches not to use any stale resource from the cache and validate the expired cache resources with the server before serving the request.
• proxy-revalidate: This directive is similar to the must-revalidate header item, except that it only applies to the proxy caches (not for the client that originally requested the resource).

JAX-RS allows you to specify the Cache-Control directives on the javax.ws.rs.core.Response object returned by your REST resource method via the javax.ws.rs.core.CacheControl class. The CacheControl class exposes methods for accessing all possible Cache-Control directives.

The following code snippet illustrates the use of the CacheControl class for specifying cache expiry directives on the response object (the Department object) returned by the resource class method:

//Other imports are omitted for brevity 
import javax.ws.rs.core.CacheControl; 
import javax.ws.rs.core.MediaType; 
import javax.ws.rs.core.Response; 
import javax.ws.rs.core.Response.ResponseBuilder;  
 
@GET 
@Path("departments/{id}") 
@Produces(MediaType.APPLICATION_JSON) 
public Response findDepartmentById(@PathParam("id") Short deptId) 
     { 
 
    Department department = findDepartmentEntityById(deptId); 
    //Specifies max-age and private directive for the response 
    CacheControl cc = new CacheControl(); 
    //Cache is valid for a day (86400 sec)  
    cc.setMaxAge(86400); 
    cc.setPrivate(true); 
 
    ResponseBuilder builder = Response.ok(myBook); 
    //set the CacheControl object and build Response   
    builder.cacheControl(cc); 
    return builder.build(); 
} 

Here is the sample response header generated by the preceding method for the GET departments/10 HTTP/1.1 request:

Server: GlassFish Server Open Source Edition 4.1  
Cache-Control: private, no-transform, max-age=86400  
Content-Type: application/json  
Date: Mon, 02 Mar 2015 05:56:29 GMT  
Content-Length: 82