001/**
002 *
003 * Copyright (c) 2014, the Railo Company Ltd. All rights reserved.
004 *
005 * This library is free software; you can redistribute it and/or
006 * modify it under the terms of the GNU Lesser General Public
007 * License as published by the Free Software Foundation; either 
008 * version 2.1 of the License, or (at your option) any later version.
009 * 
010 * This library is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013 * Lesser General Public License for more details.
014 * 
015 * You should have received a copy of the GNU Lesser General Public 
016 * License along with this library.  If not, see <http://www.gnu.org/licenses/>.
017 * 
018 **/
019package lucee.commons.io.cache;
020
021import java.io.IOException;
022import java.util.List;
023
024import lucee.commons.io.cache.exp.CacheException;
025import lucee.runtime.config.Config;
026import lucee.runtime.type.Struct;
027
028public interface Cache {
029        
030        /**
031         * initialize the cache
032         * @param arguments configuration arguments
033         * @throws CacheException 
034         */
035        public void init(Config config,String cacheName,Struct arguments) throws IOException;
036        
037        /**
038         * return cache entry that match the key, throws a CacheException when entry does not exist or is stale
039         * @param key key of the cache entry to get
040         * @return cache entry
041         * @throws CacheException
042         */
043        public CacheEntry getCacheEntry(String key) throws IOException;
044        
045        /**
046         * return value that match the key, throws a CacheException when entry does not exist or is stale
047         * @param key key of the value to get
048         * @return value
049         * @throws CacheException
050         */
051        public Object getValue(String key) throws IOException;
052        
053        /**
054         * return cache entry that match the key or the defaultValue when entry does not exist
055         * @param key key of the cache entry to get
056         * @return cache entry
057         */
058        public CacheEntry getCacheEntry(String key,CacheEntry defaultValue);
059        
060        /**
061         * return value that match the key or the defaultValue when entry does not exist
062         * @param key key of the value to get
063         * @return value
064         */
065        public Object getValue(String key,Object defaultValue);
066        
067        /**
068         * puts a cache entry to the cache, overwrite existing entries that already exists inside the cache with the same key
069         * @param value
070         */
071        public void put(String key, Object value,Long idleTime,Long until);
072        
073        /**
074         * check if there is a entry inside the cache that match the given key
075         * @param key
076         * @return contains a value that match this key
077         */
078        public boolean contains(String key);
079        
080
081        /**
082         * remove entry that match this key
083         * @param key
084         * @return returns if there was a removal
085         */
086        public boolean remove(String key) throws IOException;
087        
088        /**
089         * remove all entries that match the given filter
090         * @param filter 
091         * @return returns the count of the removal or -1 if this information is not available
092         */
093        public int remove(CacheKeyFilter filter) throws IOException;
094        
095        /**
096         * remove all entries that match the given filter
097         * @param filter 
098         * @return returns the count of the removal or -1 if this information is not available
099         */
100        public int remove(CacheEntryFilter filter) throws IOException;
101
102
103        /**
104         * 
105         * Returns a List of the keys contained in this cache. 
106         * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
107         * @return a set of the keys contained in this cache.
108         */
109        public List<String> keys() throws IOException;
110        
111        /**
112         * 
113         * Returns a List of the keys contained in this cache that match the given filter. 
114         * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
115         * @param filter 
116         * @return a set of the keys contained in this cache.
117         */
118        public List<String> keys(CacheKeyFilter filter) throws IOException;
119        
120        /**
121         * 
122         * Returns a List of the keys contained in this cache that match the given filter. 
123         * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
124         * @param filter 
125         * @return a set of the keys contained in this cache.
126         */
127        public List<String> keys(CacheEntryFilter filter) throws IOException;
128        
129        /**
130         * Returns a List of values containing in this cache. 
131         * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
132         * @return a set of the entries contained in this cache.
133         */
134        public List<Object> values() throws IOException;
135        
136        /**
137         * Returns a list of values containing in this cache that match the given filter.
138         * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
139         * @return a set of the entries contained in this cache.
140         */
141        public List<Object> values(CacheKeyFilter filter) throws IOException;
142        
143        /**
144         * Returns a list of values containing in this cache that match the given filter.
145         * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
146         * @return a set of the entries contained in this cache.
147         */
148        public List<Object> values(CacheEntryFilter filter) throws IOException; 
149        
150        /**
151         * Returns a List of entries containing in this cache Each element in the returned list is a CacheEntry. 
152         * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
153         * @return a set of the entries contained in this cache.
154         */
155        public List<CacheEntry> entries() throws IOException;
156        
157        /**
158         * Returns a list of entries containing in this cache that match the given filter.
159         * Each element in the returned set is a CacheEntry. 
160         * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
161         * @return a set of the entries contained in this cache.
162         */
163        public List<CacheEntry> entries(CacheKeyFilter filter) throws IOException;
164        
165        /**
166         * Returns a list of entries containing in this cache that match the given filter.
167         * Each element in the returned set is a CacheEntry. 
168         * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
169         * @return a set of the entries contained in this cache.
170         */
171        public List<CacheEntry> entries(CacheEntryFilter filter) throws IOException;
172
173
174        /**
175         * how many time was the cache accessed?
176         * this information is optional and depends on the implementation,
177         * when information is not available -1 is returned
178         * @return access count
179         */
180        public long hitCount();
181
182        /**
183         * how many time was the cache accessed for a record that does not exist?
184         * this information is optional and depends on the implementation,
185         * when information is not available -1 is returned
186         * @return access count
187         */
188        public long missCount();
189
190        /**
191         * get all information data available for this cache
192         */
193        public Struct getCustomInfo();
194
195}