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}