1 /*
2 * This file is part of Waarp Project (named also Waarp or GG).
3 *
4 * Copyright (c) 2019, Waarp SAS, and individual contributors by the @author
5 * tags. See the COPYRIGHT.txt in the distribution for a full listing of
6 * individual contributors.
7 *
8 * All Waarp Project is free software: you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation, either version 3 of the License, or (at your
11 * option) any later version.
12 *
13 * Waarp is distributed in the hope that it will be useful, but WITHOUT ANY
14 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
15 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License along with
18 * Waarp . If not, see <http://www.gnu.org/licenses/>.
19 */
20 package org.waarp.common.lru;
21
22 import java.util.Collection;
23 import java.util.concurrent.Callable;
24
25 /**
26 * LRU cache interface.
27 *
28 * @author Damian Momot
29 */
30 public interface InterfaceLruCache<K, V> {
31 /**
32 * Removes all entries from cache
33 */
34 void clear();
35
36 /**
37 * Removes all oldest entries from cache (ttl based)
38 *
39 * @return the number of removed entries
40 */
41 int forceClearOldest();
42
43 /**
44 * Checks whether cache contains valid entry for key
45 *
46 * @param key
47 *
48 * @return true if cache contains key and entry is valid
49 */
50 boolean contains(K key);
51
52 /**
53 * Returns value cached with key.
54 *
55 * @param key
56 *
57 * @return value or null if key doesn't exist or entry is not valid
58 */
59 V get(K key);
60
61 /**
62 * Tries to get element from cache. If get fails callback is used to create
63 * element and returned value is
64 * stored in cache.
65 * <p>
66 * Default TTL is used
67 *
68 * @param key
69 * @param callback
70 *
71 * @return Value
72 *
73 * @throws Exception if callback throws exception
74 */
75 V get(K key, Callable<V> callback) throws Exception;
76
77 /**
78 * Tries to get element from cache. If get fails callback is used to create
79 * element and returned value is
80 * stored in cache
81 *
82 * @param key
83 * @param callback
84 * @param ttl time to live in milliseconds
85 *
86 * @return Value
87 *
88 * @throws Exception if callback throws exception
89 */
90 V get(K key, Callable<V> callback, long ttl) throws Exception;
91
92 /**
93 * Returns cache capacity
94 *
95 * @return capacity of cache
96 */
97 int getCapacity();
98
99 /**
100 * Returns number of entries stored in cache (including invalid ones)
101 *
102 * @return number of entries
103 */
104 int size();
105
106 /**
107 * Returns cache TTL
108 *
109 * @return ttl in milliseconds
110 */
111 long getTtl();
112
113 /**
114 * Set a new TTL (for newly set objects only, not changing old values).
115 *
116 * @param ttl
117 */
118 void setNewTtl(long ttl);
119
120 /**
121 * Checks whether cache is empty.
122 * <p>
123 * If any entry exists (including invalid one) this method will return true
124 *
125 * @return true if no entries are stored in cache
126 */
127 boolean isEmpty();
128
129 /**
130 * Puts value under key into cache. Default TTL is used
131 *
132 * @param key
133 * @param value
134 */
135 void put(K key, V value);
136
137 /**
138 * Puts value under key into cache with desired TTL
139 *
140 * @param key
141 * @param value
142 * @param ttl time to live in milliseconds
143 */
144 void put(K key, V value, long ttl);
145
146 /**
147 * Removes entry from cache (if exists)
148 *
149 * @param key
150 *
151 * @return the value if it still exists
152 */
153 V remove(K key);
154
155 /**
156 * Update the TTL of the associated object if it still exists
157 *
158 * @param key
159 */
160 void updateTtl(K key);
161
162 /**
163 * @return the Collection of Values
164 */
165 Collection<V> values();
166 }