public interface ICacheKeyGenerator extends Serializable
Like Strings, CacheKeyGenerators are immutable. A cache key generator must contain sufficient information within its instance data to be able to generate a cache key for a request without referring to the module that the generator is associated with. Because cache key generators are immutable, they must not be affected by changes to the originating module source.
The requirement that CacheKeyGenerators be immutable allows cloneable objects like layers and modules, which maintain references to cache key generators, to clone the CacheKeyGenerators by reference, and so instances of CacheKeyGenerator do not, themselves, need to be cloneable.
A layer is identified by the collection of modules that it aggregates. Each
layer manages a cache of layer builds, were each layer build aggregates a
collection of module builds that were built with different request
attributes. Associated with each layer is a map of CacheKeyGenerators where
the map key is a CacheKeyGeneator class name and the map value is a
CacheKeyGenerator object that was created by calling
combine(ICacheKeyGenerator)
on the
CacheKeyGenerators associated with each module in the layer that have the
same CacheKeyGenerator class name. The cache keys obtained from each of these
per-class combined generators are then concatenated to form the cache key for
the layer build.
If a module builder implementation does not need to generate a cache key because the builder's response data is invariant with regard to the request, then it may provide a null CacheKeyGenerator.
Modifier and Type | Method and Description |
---|---|
ICacheKeyGenerator |
combine(ICacheKeyGenerator other)
Combines this cache key generator with the specified cache key generator
so that the cache key returned by the resulting generator can be used to
identify a layer build containing the module(s) represented by this cache
key generator as well as the module(s) represented by the specified cache
key generator.
|
boolean |
equals(Object other)
This method should return true if this object's
generateKey(HttpServletRequest)
method will always return the same value as other for the same
HttpServletRequest object. |
String |
generateKey(javax.servlet.http.HttpServletRequest request)
Returns a string that will be used to identify cached responses for the
specified request.
|
List<ICacheKeyGenerator> |
getCacheKeyGenerators(javax.servlet.http.HttpServletRequest request)
This method returns the (possibly empty) list of constituent cache key
generators belonging to a composite cache key generator.
|
boolean |
isProvisional()
Instances of this object can be provisional.
|
String |
toString()
Cache key generators should implement this function to return a short
keyword identifier for the generator (typically the same keyword used
in generated keys) plus a string representation of the instance data
that is used in constructing the keys (if any).
|
String generateKey(javax.servlet.http.HttpServletRequest request)
For clarity's sake, keys should avoid using semi-colons since these are used as a separator when aggregating the keys from multiple cache key generators.
Note that IOptions
properties do not need to be factored into the
returned key since any changes in these properties invalidates cached
responses and clears the module and layer caches.
request
- The request objectICacheKeyGenerator combine(ICacheKeyGenerator other)
For most implementations, these two generators will be identical and a reference to the current object should be returned. Only implementations who's cache keys are dependent on module content or other factors external to the request object need to provide a non-trivial implementation for this method. An example would be a javascript minifier which performs has.js feature trimming of code based on the list of feature names provided in the request. Cache keys for this module might identify the feature conditionals that the module actually contains, allowing cached module builds to be reused for requests that specify the same values for the set of features that are of concern to the module while ignoring those that are not relevant. In this example, the combine method would create a new CacheKeyGenerator from the union of the feature name sets from this generator and the specified generator.
If either this cache key generator or the specified cached key generator is a provisional cache key generator and the other is not, the returned object must be a non-provisional cache key generator.
If combining this cache key generator with the specified cache key generator yields a cache key generator that produces identical cache keys as this cache key generator, then this cache key generator should be returned.
other
- A reference to the CacheKeyGenerator object that is to be
combined with this object. The Aggregator guarantees that
other
will be of the same type as the current object,
so it is always safe to cast other
to an instance of
the current object.other
will produce a cache key
generator that generates the same keys as this object.List<ICacheKeyGenerator> getCacheKeyGenerators(javax.servlet.http.HttpServletRequest request)
Composite cache key generators are useful for controlling the output of other cache key generators in ways that depend on aspects of the current request that are outside the scope of the key generator being controlled. Composite cache key generators must adhere to the following restrictions:
generateKey(HttpServletRequest)
method for
this cache key generator should be the same as the combined (semi-colon
delimited) output of the generateKey
methods for the cache key
generators returned by this method.request
- The request objectboolean isProvisional()
IModuleBuilder.getCacheKeyGenerators(IAggregator)
should return a
provisional cache key generator, which generates keys based on
information available in the request only. The builder should then
provide a non-provisional cache key generator in the ModuleBuild
object returned from
IModuleBuilder.build(String, IResource, HttpServletRequest, List)
when it is subsequently called by a separate worker thread for the same
request.
The cache key returned by a provisional cache key generator must be either more specific than, or as specific as, the cache key returned by a non-provisional cache key generator for the same module with the same request parameters. The requirement is that if a provisional cache key generator returns identical keys for two different requests, then the non-provisional cache key generator must also return identical keys for the same two requests. The converse is not a requirement.
Provisional cache key generators are used to allow the module cache manager to cache module builds while they are still pending, potentially allowing an in-progress build to satisfy other outstanding requests. This need arises when information about the contents of the module, which is gained in the process of building it, can be used to broaden the scope of the key by ignoring request parameters or features that are not applicable to the module as determined by its content.
String toString()
boolean equals(Object other)
generateKey(HttpServletRequest)
method will always return the same value as other
for the same
HttpServletRequest
object. Classes that implement this method should
implement Object.hashCode()
as well.Copyright © 2011-2015 IBM. All Rights Reserved.