non-releases/trunk_before_flattening/src/java/org/apache/cocoon/caching/CacheableProcessingComponent.java

/*
 * Copyright 1999-2004 The Apache Software Foundation.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.cocoon.caching;

import org.apache.excalibur.source.SourceValidity;
import java.io.Serializable;

/**
 * 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
 * @version $Id$
 */
public interface CacheableProcessingComponent {

    /**
     * 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.
     */
    Serializable getKey();

    /**
     * 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>. 
     * </p>
     *
     * @return The generated validity object or <code>null</code> if the
     *         component is currently not cacheable.
     */
    SourceValidity getValidity();
}