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