Response caching bundle for Dropwizard resources.

There are two functions supported by the bundle: generate cache-control options for resources and caching responses. The cache-control generation can be used without the response caching. For example, if there is already an upstream HTTP caching proxy.

The cache support handles the various HTTP request and response cache-control options to ensure that the resource method is only invoked if the response can not be served from the cache.

• For Dropwizard 0.6: use caching bundle 1.X
• For Dropwizard 0.7: use caching bundle 2.X

Cache Keys

The cache key generated by the bundle includes:

• Request method
• Request path
• Request query parameters
• A hash of
  • Request body if @IncludeBodyInCacheKey annotation is enabled
  • Headers from the @Vary annotation

Initialize

1. Add the maven dependency:

   <dependency>
       <groupId>com.bazaarvoice.dropwizard</groupId>
       <artifactId>dropwizard-caching-bundle</artifactId>
       <version>${dropwizard-caching-bundle.version}</version>
   </dependency>

2. Modify your application configuration class to implement com.bazaarvoice.dropwizard.caching.CachingBundleConfiguration

3. Load the bundle when during application bootstrap:

   public void initialize(Bootstrap<ExampleConfiguration> bootstrap) {
       bootstrap.addBundle(new CachingBundle());
   }

At this point, the caching bundle has been loaded into the application. However, the caching bundle has no effect until configured.

Configuration

Cache Control

The first step in configuring caching is to specify the caching options for different resource methods. Use the com.bazaarvoice.dropwizard.caching.CacheGroup annotation on resource methods to set the group name.

# A list of caching configuration options. The first set of options that match a resource will be
# used.
cacheControl:
      # Only one of group or groupRegex can be specified. If neither is specified, the settings
      # will be used for all resources that were not matched by previous settings and all GET
      # methods without an explicit group name.
    - group: pattern    # Optional. Simple pattern that matches cache group name. * can be used
                        # to match 0 or more characters.
      groupRegex: regex # Optional. Regular expression that matches cache group name.
      
      # For more detailed info on the following cache-control options,
      # see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9
      
      maxAge: duration          # Optional. Max time that the response can be cached.
                                # Example: 5m (5 minutes), 30s (30 seconds)
                                # Resolution is seconds. Partial seconds are rounded down.
                                # Supported suffixes: s (seconds), m (minutes), h (hours), d (days)
                                # Although you can set this value higher, the max recommended
                                # value by the HTTP standard is 1 year (365d).
      sharedMaxAge: duration    # Optional. Max time that the response can be cached in a
                                # shared cache. If specified, this value is used by the caching
                                # layer. Otherwise, maxAge is used. A shared cache is one where a
                                # cached response can be returned to multiple clients. A private
                                # cache is usually the local cache where the request originated
                                # whereas the shared cache is usually the caching proxy server.
                                # The same formatting rules that apply to maxAge apply to this
                                # option.
      flags:                    # Set of caching directives
        - no-cache              # A cache MUST NOT use the response to satisfy a subsequent
                                # request without successful revalidation with the origin server.
        - no-store              # A cache MUST NOT store any part of either the response or the
                                # request that elicited it.
        - must-revalidate       # A cache MUST NOT use the cached response after it has expired.
                                # Because a cache can be configured to ignore cache expiration and
                                # the client can specify the max-stale option, this flag provides
                                # a mechanism to require revalidation of stale entries.
        - proxy-revalidate      # Has the same meaning as must-revalidate, but only applies to
                                # shared caches.
        - no-transform          # An intermediate cache or proxy MUST NOT change the headers that
                                # are subject to the no-transform directive or the response body
                                # itself.
                                # http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.5.2
        - private               # Indicates that all or part of the response message is intended
                                # for a single user and MUST NOT be cached by a shared cache.
        - public                # Indicates that the response MAY be cached by any cache, even if
                                # it would normally be non-cacheable or cacheable only within a
                                # non-shared cache.
                                 
      private:                  # List of header fields in the response that are intended for a
                                # single user and MUST NOT be cached by a shared cache. Setting
                                # this option automatically sets the private flag.
        - Authorization
        
      noCache:                  # List of header fields that MUST NOT be sent in the response to a
                                # subsequent request without successful revalidation with the
                                # origin server.
        - Content-Type
        
      extensions:               # Custom cache-control directives.
        bare:                   # With no or empty value, output is a bare directive
        has-value: 17           # With a value, output is has-value="17"

Examples

# Cache all resources (GET methods and resources with an explicit group) for 30 seconds.
# DANGER: this may have unexpected consequences if the resource is not expecting caching to occur.
cacheControl:
    - maxAge: 30s

Caching

After setting the cache control options, an in-process response cache can be enabled, possibly backed by an external store.

The local, in-process cache and the external store can be used independently of each other. For example, with no local cache, the store will be queried for each request.

cache:
    # Optional. Configuration options for the local, in-memory cache. If no options are specified,
    # no local response caching occurs.
    local:
        maximumSize: Size  # Maximum memory the local cache can consume.
                           # Examples: 100MB, 10KB
                           # Suffixes: B, KB, MB, GB, TB 
        expire: Duration   # Maximum amount of time to keep an item in the in-memory cache. This
                           # may be longer or shorter than the maxAge for the response.
          
    # Optional. Configuration for remote, shared cache storage. For example, a memcached cluster.
    # The local, in-memory cache is consulted first and, if not found, the store is queried.
    store:
        type: Type         # Type of storage. The type defines what other options are available.

Memcached

To use a memcached cluster:

1. Add the maven dependency:

   <dependency>
       <groupId>com.bazaarvoice.dropwizard</groupId>
       <artifactId>dropwizard-caching-bundle-memcached</artifactId>
       <version>${dropwizard-caching-bundle.version}</version>
   </dependency>

2. Configure memcached

   cache:
       store:
           type: memcached
           servers:             # List of memcached server host or ip address and port
               - localhost:11211
           keyPrefix: String    # Prefix to add to all cache keys.
           readOnly: Boolean    # True to only read from the cache, but not update. Default false.

Memcached Requirements

The memcached server must support the memcached binary protocol.

Keys

Memcached limits keys to 250 bytes. If the key is longer than 250 bytes, the memcached store will hash the original key, truncate the key, and append the hash.