001package org.apache.commons.jcs.access.behavior;
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.access.exception.CacheException;
023import org.apache.commons.jcs.engine.behavior.ICacheElement;
024import org.apache.commons.jcs.engine.behavior.IElementAttributes;
025
026import java.util.Map;
027import java.util.Set;
028
029/**
030 * ICacheAccess defines the behavior for client access.
031 */
032public interface ICacheAccess<K, V>
033    extends ICacheAccessManagement
034{
035    /**
036     * Basic get method.
037     * <p>
038     * @param name
039     * @return Object or null if not found.
040     */
041    V get( K name );
042
043    /**
044     * Retrieve matching objects from the cache region this instance provides access to.
045     * <p>
046     * @param pattern - a key pattern for the objects stored
047     * @return A map of key to values. These are stripped from the wrapper.
048     */
049    Map<K, V> getMatching( String pattern );
050
051    /**
052     * Puts in cache if an item does not exist with the name in that region.
053     * <p>
054     * @param name
055     * @param obj
056     * @throws CacheException
057     */
058    void putSafe( K name, V obj )
059        throws CacheException;
060
061    /**
062     * Puts and/or overrides an element with the name in that region.
063     * <p>
064     * @param name
065     * @param obj
066     * @throws CacheException
067     */
068    void put( K name, V obj )
069        throws CacheException;
070
071    /**
072     * Description of the Method
073     * <p>
074     * @param name
075     * @param obj
076     * @param attr
077     * @throws CacheException
078     */
079    void put( K name, V obj, IElementAttributes attr )
080        throws CacheException;
081
082    /**
083     * This method returns the ICacheElement&lt;K, V&gt; wrapper which provides access to element info and other
084     * attributes.
085     * <p>
086     * This returns a reference to the wrapper. Any modifications will be reflected in the cache. No
087     * defensive copy is made.
088     * <p>
089     * This method is most useful if you want to determine things such as the how long the element
090     * has been in the cache.
091     * <p>
092     * The last access time in the ElementAttributes should be current.
093     * <p>
094     * @param name Key the object is stored as
095     * @return The ICacheElement&lt;K, V&gt; if the object is found or null
096     */
097    ICacheElement<K, V> getCacheElement( K name );
098
099    /**
100     * Get multiple elements from the cache based on a set of cache keys.
101     * <p>
102     * This method returns the ICacheElement&lt;K, V&gt; wrapper which provides access to element info and other
103     * attributes.
104     * <p>
105     * This returns a reference to the wrapper. Any modifications will be reflected in the cache. No
106     * defensive copy is made.
107     * <p>
108     * This method is most useful if you want to determine things such as the how long the element
109     * has been in the cache.
110     * <p>
111     * The last access time in the ElementAttributes should be current.
112     * <p>
113     * @param names set of Object cache keys
114     * @return a map of Object key to ICacheElement&lt;K, V&gt; element, or empty map if none of the keys are
115     *         present
116     */
117    Map<K, ICacheElement<K, V>> getCacheElements( Set<K> names );
118
119    /**
120     * Get multiple elements from the cache based on a set of cache keys.
121     * <p>
122     * This method returns the ICacheElement&lt;K, V&gt; wrapper which provides access to element info and other
123     * attributes.
124     * <p>
125     * This returns a reference to the wrapper. Any modifications will be reflected in the cache. No
126     * defensive copy is made.
127     * <p>
128     * This method is most useful if you want to determine things such as the how long the element
129     * has been in the cache.
130     * <p>
131     * The last access time in the ElementAttributes should be current.
132     * <p>
133     * @param pattern key search pattern
134     * @return a map of Object key to ICacheElement&lt;K, V&gt; element, or empty map if no keys match the
135     *         pattern
136     */
137    Map<K, ICacheElement<K, V>> getMatchingCacheElements( String pattern );
138
139    /**
140     * Remove an object for this key if one exists, else do nothing.
141     * <p>
142     * @param name
143     * @throws CacheException
144     */
145    void remove( K name )
146        throws CacheException;
147
148    /**
149     * Reset the attributes on the object matching this key name.
150     * <p>
151     * @param name
152     * @param attributes
153     * @throws CacheException
154     */
155    void resetElementAttributes( K name, IElementAttributes attributes )
156        throws CacheException;
157
158    /**
159     * Gets the elementAttributes attribute of the ICacheAccess object
160     * <p>
161     * @param name
162     * @return The elementAttributes value
163     * @throws CacheException
164     */
165    IElementAttributes getElementAttributes( K name )
166        throws CacheException;
167}