org.apache.cocoon.pipeline.caching.Cache Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of cocoon-pipeline Show documentation
The core of Cocoon 3. A Servlet API independent implementation of pipelines.
The newest version!
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.pipeline.caching;

import java.util.Set;

public interface Cache {

    /**
     * Stores the given cacheValue at the given cacheKey.

     * 

     * If this cache already contains the given cacheKey it will be replaced.

     * If two {@link CacheKey}s represent the same data is ultimately depending on the implementation, but usually relies on the
     * equals an/or hashcode methods.
     * 
     * @param cacheKey The {@link CacheKey} to be used for storing.
     * @param cacheValue The {@link CacheValue} to be stored.
     */
    void put(CacheKey cacheKey, CacheValue cacheValue);

    /**
     * Retrieves the {@link CacheValue} previously stored using the given cacheKey.

     * If the cacheKey is not stored in this {@link Cache} this method will return null.

     * 

     * Furthermore the {@link Cache} will check if the stored {@link CacheValue} is still valid (using the
     * {@link CacheValue#isValid(CacheKey)} method). If the {@link CacheValue} is considered to be invalid this method will return
     * null as well (indicating that no valid {@link CacheValue} is available).

     * 

     * To retrieve CacheValues even if they are invalid, use the {@link #get(CacheKey, boolean)} method.
     * 
     * @param cacheKey The {@link CacheKey} defining which {@link CacheValue} to retrieve.
     * @return The previously stored {@link CacheValue} or null if no or no valid {@link CacheValue} is stored at the
     *         given cacheValue.
     */
    CacheValue get(CacheKey cacheKey);

    /**
     * Retrieves the {@link CacheValue} previously stored using the given cacheKey.

     * If the cacheKey is not stored in this {@link Cache} this method will return null.

     * 

     * This method will omit the check for validity if includeInvalid is true (i.e. the returned CacheValue
     * might be invalid in this case).
     * 
     * @param cacheKey The {@link CacheKey} defining which {@link CacheValue} to retrieve.
     * @param includeInvalid Defines whether invalid {@link CacheValue} should be returned or not. Using true will also
     *            return invalid {@link CacheValue}. Using false will yield the same results as {@link #get(CacheKey)}.
     * @return The previously stored {@link CacheValue} or null if and only if no {@link CacheValue} is stored at the
     *         given cacheValue.
     */
    CacheValue get(CacheKey cacheKey, boolean includeInvalid);

    /**
     * Returns {@link Set} of {@link CacheKey} contained in this Cache
     *
     * @return a set CacheKey contained in this Cache
     */
    Set keySet();

    /**
     * Removes that CacheKey from this Cache.
     *
     * @param cacheKey
     */
    boolean remove(CacheKey cacheKey);

    /**
     * Removes all data coneined in this Cache
     */
    void clear();
}