001package org.apache.commons.jcs.auxiliary;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *   http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import org.apache.commons.jcs.engine.behavior.ICache;
023import org.apache.commons.jcs.engine.behavior.IElementSerializer;
024import org.apache.commons.jcs.engine.logging.behavior.ICacheEventLogger;
025import org.apache.commons.jcs.engine.stats.behavior.IStats;
026
027import java.io.IOException;
028import java.util.Set;
029
030/**
031 * Tag interface for auxiliary caches. Currently this provides no additional methods over what is in
032 * ICache, but I anticipate that will change. For example, there will be a mechanism for determining
033 * the type (disk/lateral/remote) of the auxiliary here -- and the existing getCacheType will be
034 * removed from ICache.
035 */
036public interface AuxiliaryCache<K, V>
037    extends ICache<K, V>
038{
039    /**
040     * Get a set of the keys for all elements in the auxiliary cache.
041     * <p>
042     * @return a set of the key type
043     * TODO This should probably be done in chunks with a range passed in. This
044     *       will be a problem if someone puts a 1,000,000 or so items in a
045     *       region.
046     * @throws IOException if access to the auxiliary cache fails
047     */
048    Set<K> getKeySet() throws IOException;
049
050    /**
051     * @return the historical and statistical data for a region's auxiliary cache.
052     */
053    IStats getStatistics();
054
055    /**
056     * This returns the generic attributes for an auxiliary cache. Most implementations will cast
057     * this to a more specific type.
058     * <p>
059     * @return the attributes for the auxiliary cache
060     */
061    AuxiliaryCacheAttributes getAuxiliaryCacheAttributes();
062
063    /**
064     * Allows you to inject a custom serializer. A good example would be a compressing standard
065     * serializer.
066     * <p>
067     * @param elementSerializer
068     */
069    void setElementSerializer( IElementSerializer elementSerializer );
070
071    /**
072     * Every Auxiliary must allow for the use of an event logger.
073     * <p>
074     * @param cacheEventLogger
075     */
076    void setCacheEventLogger( ICacheEventLogger cacheEventLogger );
077}