svn commit: r279595 - /cocoon/trunk/src/java/org/apache/cocoon/caching/CacheableProcessingComponent.java

[bl...@apache.org]

Author: bloritsch
Date: Thu Sep  8 10:52:48 2005
New Revision: 279595

URL: http://svn.apache.org/viewcvs?rev=279595&view=rev
Log:
update the javadocs

Modified:
    cocoon/trunk/src/java/org/apache/cocoon/caching/CacheableProcessingComponent.java

Modified: cocoon/trunk/src/java/org/apache/cocoon/caching/CacheableProcessingComponent.java
URL: http://svn.apache.org/viewcvs/cocoon/trunk/src/java/org/apache/cocoon/caching/CacheableProcessingComponent.java?rev=279595&r1=279594&r2=279595&view=diff
==============================================================================
--- cocoon/trunk/src/java/org/apache/cocoon/caching/CacheableProcessingComponent.java (original)
+++ cocoon/trunk/src/java/org/apache/cocoon/caching/CacheableProcessingComponent.java Thu Sep  8 10:52:48 2005
@@ -19,20 +19,64 @@
 import java.io.Serializable;
 
 /**
- * This marker interface declares a (sitemap) component as cacheable.
- *
+ * This interface declares a (sitemap) component as cacheable.
  * This interface deprecates the org.apache.cocoon.caching.Cacheable interface!
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * 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
+ * <code>CachingPipeline</code> will respect the contracts defined in this
+ * interface.
+ * </p>
  *
  * @since 2.1
  * @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
- * @version CVS $Id: CacheableProcessingComponent.java,v 1.3 2004/03/05 13:02:45 bdelacretaz Exp $
+ * @version CVS $Id$
  */
 public interface CacheableProcessingComponent {
 
     /**
-     * Generate the unique key.
-     * This key must be unique inside the space of this component.
-     * This method must be invoked before the getValidity() method.
+     * Generate the unique key for the resource being rendered.
+     * <p>
+     * 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:
+     * </p>
+     * <ul>
+     * <li>It must be Serializable (part of the contract of this method).</li>
+     * <li>It must be Immutable--the key is used as a lookup value.</li>
+     * <li>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).</li>
+     * <li>The equals() and hashCode() methods must be consistent (i.e. if two
+     *     keys are equal, the hashCode must also be equal).</li>
+     * </ul>
+     * <p>
+     * Thankfully there is a perfectly suitable object that satisfies these
+     * obligations from Java's core: <code>java.lang.String</code>. You can
+     * also use your own specific key objects provided they respect the above
+     * contracts.
+     * </p>
+     * <p>
+     * <strong>Important:</strong>If the cache key is <code>null</code> then
+     * your component will not be cached at all. You can use this to your
+     * advantage to cache some things but not others.
+     * </p>
      *
      * @return The generated key or <code>null</code> if the component
      *              is currently not cacheable.
@@ -40,9 +84,20 @@
     Serializable getKey();
 
     /**
-     * Generate the validity object.
-     * Before this method can be invoked the getKey() method
-     * must be invoked.
+     * Generate the validity object.  This method is invoked after the
+     * <code>getKey()</code> method.
+     * <p>
+     * The caching contracts use the Excalibur <code>SourceValidity</code>
+     * 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 
+     * <a href="http://excalibur.apache.org/sourceresolve/index.html">Apache
+     * Excalibur site</a>. Alternatively you can use the built in 
+     * <code>CacheValidity</code> objects in the
+     * <code>org.apache.cocoon.caching</code> package and then use the
+     * {@link CacheValidityToSourceValidity} adaptor object.
+     * </p>
      *
      * @return The generated validity object or <code>null</code> if the
      *         component is currently not cacheable.