1 /* 2 * MIT License 3 * 4 * Copyright (c) 2010-2022 The Waffle Project Contributors: https://github.com/Waffle/waffle/graphs/contributors 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to deal 8 * in the Software without restriction, including without limitation the rights 9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 * copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in all 14 * copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22 * SOFTWARE. 23 */ 24 package waffle.util.cache; 25 26 import java.util.NoSuchElementException; 27 import java.util.ServiceLoader; 28 29 /** 30 * A semi-persistent mapping from keys to values. 31 * 32 * @param <K> 33 * the type of keys maintained by this cache 34 * @param <V> 35 * the type of mapped values 36 * 37 * @author Simon Legner 38 * 39 * @see <a href="https://github.com/Waffle/waffle/blob/master/Docs/CustomCache.md">Can I provide a custom cache 40 * implementation?</a> 41 */ 42 public interface Cache<K, V> { 43 44 /** 45 * Creates a new cache with the specified timeout. 46 * <p> 47 * The cache implementation is obtained using {@link ServiceLoader}. To create your own implementation, implement 48 * {@link CacheSupplier} and register it using the {@code /META-INF/services/waffle.util.cache.CacheSupplier} file 49 * on your classpath. 50 * 51 * @param timeout 52 * timeout in seconds 53 * @param <K> 54 * the type of keys maintained by this cache 55 * @param <V> 56 * the type of mapped values 57 * 58 * @return a new cache 59 * 60 * @throws NoSuchElementException 61 * if no cache can be instantiated, use {@link Exception#getSuppressed()} to obtain details. 62 */ 63 static <K, V> Cache<K, V> newCache(int timeout) throws NoSuchElementException { 64 final NoSuchElementException exception = new NoSuchElementException(); 65 for (CacheSupplier cacheSupplier : ServiceLoader.load(CacheSupplier.class)) { 66 try { 67 return cacheSupplier.newCache(timeout); 68 } catch (Exception e) { 69 exception.addSuppressed(e); 70 } 71 } 72 throw exception; 73 } 74 75 /** 76 * Fetches the key from the cache 77 * 78 * @param key 79 * the key 80 * 81 * @return the corresponding value 82 * 83 * @see java.util.Map#get 84 */ 85 V get(K key); 86 87 /** 88 * Stores a binding for the key and the value in the cache 89 * 90 * @param key 91 * the key 92 * @param value 93 * the value 94 * 95 * @see java.util.Map#put 96 */ 97 void put(K key, V value); 98 99 /** 100 * Removes the binding for the key from the cache 101 * 102 * @param key 103 * the key 104 * 105 * @see java.util.Map#remove(Object) 106 */ 107 void remove(K key); 108 109 /** 110 * Returns the number of bindings in this cache 111 * 112 * @return the size 113 * 114 * @see java.util.Map#size 115 */ 116 int size(); 117 }