org.apache.cocoon.caching
Interface CacheableProcessingComponent

public interface CacheableProcessingComponent

This interface declares a (sitemap) component as cacheable. This interface deprecates the org.apache.cocoon.caching.Cacheable interface!

Just about everything can be cached, so it makes sense to provide some controls to make sure that the user always gets valid results. There are two aspects to a cacheable component: the key and the validition. The key is used to determine within the component's scheme of things whether a result is unique. For example, if your generator provides dynamic information based on an ID and a user, you want to combine the two elements into one key. That way Cocoon can determine whether to use the cached information for the given ID/User combination or create it from scratch.

The CachingPipeline will check the component's key to see if it even has the information cached to begin with. Next, it will check the validity of the cached value if there is one. If the cache has the resource and it is valid, the CachingPipeline will return the cached results. If either condition is false, then the CachingPipeline will generate the results and cache it for later use. It is important to realize that only the CachingPipeline will respect the contracts defined in this interface.

Since:

2.1

Version:

$Id: CacheableProcessingComponent.html 1304280 2012-03-23 11:18:01Z ilgrosso $

Method Summary

Serializable	getKey() Generate the unique key for the resource being rendered.
SourceValidity	getValidity() Generate the validity object.

Method Detail

getKey

public Serializable getKey()

Generate the unique key for the resource being rendered.

The cache key is the single most important part of the caching implementation. If you don't get it right, you can introduce more load on the caching engine than is necessary. It is important that the cache key has the following attributes:

• It must be Serializable (part of the contract of this method).
• It must be Immutable--the key is used as a lookup value.
• It must be Unique within the space of the component (i.e. the key "1" for MyCacheableComponent must be for the same resource every time, but we don't have to worry about the key "1" for YourCacheableComponent).
• The equals() and hashCode() methods must be consistent (i.e. if two keys are equal, the hashCode must also be equal).

Thankfully there is a perfectly suitable object that satisfies these obligations from Java's core: java.lang.String. You can also use your own specific key objects provided they respect the above contracts.

Important:If the cache key is null then your component will not be cached at all. You can use this to your advantage to cache some things but not others.

Returns:

The generated key or null if the component is currently not cacheable.

getValidity

public SourceValidity getValidity()

Generate the validity object. This method is invoked after the getKey() method.

The caching contracts use the Excalibur SourceValidity interface to determine whether a resource is valid or not. The validity can be a compound check that incorporates time since creation, parameter values, etc. As long as the sitemap can determine whether the cached resource is valid or not. More information is available on the Apache Excalibur site.

Returns:

The generated validity object or null if the component is currently not cacheable.