001    package railo.commons.io.cache;
002    
003    import java.io.IOException;
004    import java.util.List;
005    
006    import railo.commons.io.cache.exp.CacheException;
007    import railo.runtime.config.Config;
008    import railo.runtime.type.Struct;
009    
010    public interface Cache {
011            
012            /**
013             * initialize the cache
014             * @param arguments configuration arguments
015             * @throws CacheException 
016             */
017            public void init(Config config,String cacheName,Struct arguments) throws IOException;
018            
019            /**
020             * return cache entry that match the key, throws a CacheException when entry does not exist or is stale
021             * @param key key of the cache entry to get
022             * @return cache entry
023             * @throws CacheException
024             */
025            public CacheEntry getCacheEntry(String key) throws IOException;
026            
027            /**
028             * return value that match the key, throws a CacheException when entry does not exist or is stale
029             * @param key key of the value to get
030             * @return value
031             * @throws CacheException
032             */
033            public Object getValue(String key) throws IOException;
034            
035            /**
036             * return cache entry that match the key or the defaultValue when entry does not exist
037             * @param key key of the cache entry to get
038             * @return cache entry
039             */
040            public CacheEntry getCacheEntry(String key,CacheEntry defaultValue);
041            
042            /**
043             * return value that match the key or the defaultValue when entry does not exist
044             * @param key key of the value to get
045             * @return value
046             */
047            public Object getValue(String key,Object defaultValue);
048            
049            /**
050             * puts a cache entry to the cache, overwrite existing entries that already exists inside the cache with the same key
051             * @param value
052             */
053            public void put(String key, Object value,Long idleTime,Long until);
054            
055            /**
056             * check if there is a entry inside the cache that match the given key
057             * @param key
058             * @return contains a value that match this key
059             */
060            public boolean contains(String key);
061            
062    
063            /**
064             * remove entry that match this key
065             * @param key
066             * @return returns if there was a removal
067             */
068            public boolean remove(String key) throws IOException;
069            
070            /**
071             * remove all entries that match the given filter
072             * @param filter 
073             * @return returns the count of the removal or -1 if this information is not available
074             */
075            public int remove(CacheKeyFilter filter) throws IOException;
076            
077            /**
078             * remove all entries that match the given filter
079             * @param filter 
080             * @return returns the count of the removal or -1 if this information is not available
081             */
082            public int remove(CacheEntryFilter filter) throws IOException;
083    
084    
085            /**
086             * 
087             * Returns a List of the keys contained in this cache. 
088             * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
089             * @return a set of the keys contained in this cache.
090             */
091            public List<String> keys() throws IOException;
092            
093            /**
094             * 
095             * Returns a List of the keys contained in this cache that match the given filter. 
096             * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
097             * @param filter 
098             * @return a set of the keys contained in this cache.
099             */
100            public List<String> keys(CacheKeyFilter filter) throws IOException;
101            
102            /**
103             * 
104             * Returns a List of the keys contained in this cache that match the given filter. 
105             * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
106             * @param filter 
107             * @return a set of the keys contained in this cache.
108             */
109            public List<CacheEntry> keys(CacheEntryFilter filter) throws IOException;
110            
111            /**
112             * Returns a List of values containing in this cache. 
113             * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
114             * @return a set of the entries contained in this cache.
115             */
116            public List<Object> values() throws IOException;
117            
118            /**
119             * Returns a list of values containing in this cache that match the given filter.
120             * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
121             * @return a set of the entries contained in this cache.
122             */
123            public List<Object> values(CacheKeyFilter filter) throws IOException;
124            
125            /**
126             * Returns a list of values containing in this cache that match the given filter.
127             * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
128             * @return a set of the entries contained in this cache.
129             */
130            public List<Object> values(CacheEntryFilter filter) throws IOException; 
131            
132            /**
133             * Returns a List of entries containing in this cache Each element in the returned list is a CacheEntry. 
134             * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
135             * @return a set of the entries contained in this cache.
136             */
137            public List<CacheEntry> entries() throws IOException;
138            
139            /**
140             * Returns a list of entries containing in this cache that match the given filter.
141             * Each element in the returned set is a CacheEntry. 
142             * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
143             * @return a set of the entries contained in this cache.
144             */
145            public List<CacheEntry> entries(CacheKeyFilter filter) throws IOException;
146            
147            /**
148             * Returns a list of entries containing in this cache that match the given filter.
149             * Each element in the returned set is a CacheEntry. 
150             * The set is NOT backed by the cache, so changes to the cache are NOT reflected in the set, and vice-versa. 
151             * @return a set of the entries contained in this cache.
152             */
153            public List<CacheEntry> entries(CacheEntryFilter filter) throws IOException;
154    
155    
156            /**
157             * how many time was the cache accessed?
158             * this information is optional and depends on the implementation,
159             * when information is not available -1 is returned
160             * @return access count
161             */
162            public long hitCount();
163    
164            /**
165             * how many time was the cache accessed for a record that does not exist?
166             * this information is optional and depends on the implementation,
167             * when information is not available -1 is returned
168             * @return access count
169             */
170            public long missCount();
171    
172            /**
173             * get all information data available for this cache
174             */
175            public Struct getCustomInfo();
176    
177    }