Version 4.5.2
[nikiroo-utils.git] / src / be / nikiroo / utils / Cache.java
1 package be.nikiroo.utils;
2
3 import java.io.File;
4 import java.io.FileInputStream;
5 import java.io.FileNotFoundException;
6 import java.io.IOException;
7 import java.io.InputStream;
8 import java.net.URL;
9 import java.util.Date;
10
11 /**
12 * A generic cache system, with special support for {@link URL}s.
13 * <p>
14 * This cache also manages timeout information.
15 *
16 * @author niki
17 */
18 public class Cache {
19 private File dir;
20 private long tooOldChanging;
21 private long tooOldStable;
22 private TraceHandler tracer = new TraceHandler();
23
24 /**
25 * Only for inheritance.
26 */
27 protected Cache() {
28 }
29
30 /**
31 * Create a new {@link Cache} object.
32 *
33 * @param dir
34 * the directory to use as cache
35 * @param hoursChanging
36 * the number of hours after which a cached file that is thought
37 * to change ~often is considered too old (or -1 for
38 * "never too old")
39 * @param hoursStable
40 * the number of hours after which a cached file that is thought
41 * to change rarely is considered too old (or -1 for
42 * "never too old")
43 *
44 * @throws IOException
45 * in case of I/O error
46 */
47 public Cache(File dir, int hoursChanging, int hoursStable)
48 throws IOException {
49 this.dir = dir;
50 this.tooOldChanging = 1000L * 60 * 60 * hoursChanging;
51 this.tooOldStable = 1000L * 60 * 60 * hoursStable;
52
53 if (dir != null && !dir.exists()) {
54 dir.mkdirs();
55 }
56
57 if (dir == null || !dir.exists()) {
58 throw new IOException("Cannot create the cache directory: "
59 + (dir == null ? "null" : dir.getAbsolutePath()));
60 }
61 }
62
63 /**
64 * The traces handler for this {@link Cache}.
65 *
66 * @return the traces handler
67 */
68 public TraceHandler getTraceHandler() {
69 return tracer;
70 }
71
72 /**
73 * The traces handler for this {@link Cache}.
74 *
75 * @param tracer
76 * the new traces handler
77 */
78 public void setTraceHandler(TraceHandler tracer) {
79 if (tracer == null) {
80 tracer = new TraceHandler(false, false, false);
81 }
82
83 this.tracer = tracer;
84 }
85
86 /**
87 * Check the resource to see if it is in the cache.
88 *
89 * @param uniqueID
90 * the resource to check
91 * @param allowTooOld
92 * allow files even if they are considered too old
93 * @param stable
94 * a stable file (that dones't change too often) -- parameter
95 * used to check if the file is too old to keep or not
96 *
97 * @return TRUE if it is
98 *
99 */
100 public boolean check(String uniqueID, boolean allowTooOld, boolean stable) {
101 return check(getCached(uniqueID), allowTooOld, stable);
102 }
103
104 /**
105 * Check the resource to see if it is in the cache.
106 *
107 * @param url
108 * the resource to check
109 * @param allowTooOld
110 * allow files even if they are considered too old
111 * @param stable
112 * a stable file (that dones't change too often) -- parameter
113 * used to check if the file is too old to keep or not
114 *
115 * @return TRUE if it is
116 *
117 */
118 public boolean check(URL url, boolean allowTooOld, boolean stable) {
119 return check(getCached(url), allowTooOld, stable);
120 }
121
122 /**
123 * Check the resource to see if it is in the cache.
124 *
125 * @param cached
126 * the resource to check
127 * @param allowTooOld
128 * allow files even if they are considered too old
129 * @param stable
130 * a stable file (that dones't change too often) -- parameter
131 * used to check if the file is too old to keep or not
132 *
133 * @return TRUE if it is
134 *
135 */
136 private boolean check(File cached, boolean allowTooOld, boolean stable) {
137 if (cached.exists() && cached.isFile()) {
138 if (!allowTooOld && isOld(cached, stable)) {
139 if (!cached.delete()) {
140 tracer.error("Cannot delete temporary file: "
141 + cached.getAbsolutePath());
142 }
143 } else {
144 return true;
145 }
146 }
147
148 return false;
149 }
150
151 /**
152 * Clean the cache (delete the cached items).
153 *
154 * @param onlyOld
155 * only clean the files that are considered too old for a stable
156 * resource
157 *
158 * @return the number of cleaned items
159 */
160 public int clean(boolean onlyOld) {
161 return clean(onlyOld, dir);
162 }
163
164 /**
165 * Clean the cache (delete the cached items) in the given cache directory.
166 *
167 * @param onlyOld
168 * only clean the files that are considered too old for stable
169 * resources
170 * @param cacheDir
171 * the cache directory to clean
172 *
173 * @return the number of cleaned items
174 */
175 private int clean(boolean onlyOld, File cacheDir) {
176 int num = 0;
177 File[] files = cacheDir.listFiles();
178 if (files != null) {
179 for (File file : files) {
180 if (file.isDirectory()) {
181 num += clean(onlyOld, file);
182 } else {
183 if (!onlyOld || isOld(file, true)) {
184 if (file.delete()) {
185 num++;
186 } else {
187 tracer.error("Cannot delete temporary file: "
188 + file.getAbsolutePath());
189 }
190 }
191 }
192 }
193 }
194
195 return num;
196 }
197
198 /**
199 * Open a resource from the cache if it exists.
200 *
201 * @param uniqueID
202 * the unique ID
203 * @param allowTooOld
204 * allow files even if they are considered too old
205 * @param stable
206 * a stable file (that dones't change too often) -- parameter
207 * used to check if the file is too old to keep or not
208 *
209 * @return the opened resource if found, NULL if not
210 */
211 public InputStream load(String uniqueID, boolean allowTooOld, boolean stable) {
212 return load(getCached(uniqueID), allowTooOld, stable);
213 }
214
215 /**
216 * Open a resource from the cache if it exists.
217 *
218 * @param url
219 * the resource to open
220 * @param allowTooOld
221 * allow files even if they are considered too old
222 * @param stable
223 * a stable file (that doesn't change too often) -- parameter
224 * used to check if the file is too old to keep or not in the
225 * cache
226 *
227 * @return the opened resource if found, NULL if not
228 */
229 public InputStream load(URL url, boolean allowTooOld, boolean stable) {
230 return load(getCached(url), allowTooOld, stable);
231 }
232
233 /**
234 * Open a resource from the cache if it exists.
235 *
236 * @param cached
237 * the resource to open
238 * @param allowTooOld
239 * allow files even if they are considered too old
240 * @param stable
241 * a stable file (that dones't change too often) -- parameter
242 * used to check if the file is too old to keep or not
243 *
244 * @return the opened resource if found, NULL if not
245 */
246 private InputStream load(File cached, boolean allowTooOld, boolean stable) {
247 if (cached.exists() && cached.isFile()
248 && (allowTooOld || !isOld(cached, stable))) {
249 try {
250 return new MarkableFileInputStream(new FileInputStream(cached));
251 } catch (FileNotFoundException e) {
252 return null;
253 }
254 }
255
256 return null;
257 }
258
259 /**
260 * Save the given resource to the cache.
261 *
262 * @param in
263 * the input data
264 * @param uniqueID
265 * a unique ID used to locate the cached resource
266 *
267 * @throws IOException
268 * in case of I/O error
269 */
270 public void save(InputStream in, String uniqueID) throws IOException {
271 File cached = getCached(uniqueID);
272 cached.getParentFile().mkdirs();
273 save(in, cached);
274 }
275
276 /**
277 * Save the given resource to the cache.
278 *
279 * @param in
280 * the input data
281 * @param url
282 * the {@link URL} used to locate the cached resource
283 *
284 * @throws IOException
285 * in case of I/O error
286 */
287 public void save(InputStream in, URL url) throws IOException {
288 File cached = getCached(url);
289 save(in, cached);
290 }
291
292 /**
293 * Save the given resource to the cache.
294 * <p>
295 * Will also clean the {@link Cache} from old files.
296 *
297 * @param in
298 * the input data
299 * @param cached
300 * the cached {@link File} to save to
301 *
302 * @throws IOException
303 * in case of I/O error
304 */
305 private void save(InputStream in, File cached) throws IOException {
306 clean(true);
307 IOUtils.write(in, cached);
308 }
309
310 /**
311 * Remove the given resource from the cache.
312 *
313 * @param uniqueID
314 * a unique ID used to locate the cached resource
315 *
316 * @return TRUE if it was removed
317 */
318 public boolean remove(String uniqueID) {
319 File cached = getCached(uniqueID);
320 return cached.delete();
321 }
322
323 /**
324 * Remove the given resource from the cache.
325 *
326 * @param url
327 * the {@link URL} used to locate the cached resource
328 *
329 * @return TRUE if it was removed
330 */
331 public boolean remove(URL url) {
332 File cached = getCached(url);
333 return cached.delete();
334 }
335
336 /**
337 * Check if the {@link File} is too old according to
338 * {@link Cache#tooOldChanging}.
339 *
340 * @param file
341 * the file to check
342 * @param stable
343 * TRUE to denote stable files, that are not supposed to change
344 * too often
345 *
346 * @return TRUE if it is
347 */
348 private boolean isOld(File file, boolean stable) {
349 long max = tooOldChanging;
350 if (stable) {
351 max = tooOldStable;
352 }
353
354 if (max < 0) {
355 return false;
356 }
357
358 long time = new Date().getTime() - file.lastModified();
359 if (time < 0) {
360 tracer.error("Timestamp in the future for file: "
361 + file.getAbsolutePath());
362 }
363
364 return time < 0 || time > max;
365 }
366
367 /**
368 * Return the associated cache {@link File} from this {@link URL}.
369 *
370 * @param url
371 * the {@link URL}
372 *
373 * @return the cached {@link File} version of this {@link URL}
374 */
375 private File getCached(URL url) {
376 File subdir;
377
378 String name = url.getHost();
379 if (name == null || name.isEmpty()) {
380 // File
381 File file = new File(url.getFile());
382 if (file.getParent() == null) {
383 subdir = new File("+");
384 } else {
385 subdir = new File(file.getParent().replace("..", "__"));
386 }
387 subdir = new File(dir, allowedChars(subdir.getPath()));
388 name = allowedChars(url.getFile());
389 } else {
390 // URL
391 File subsubDir = new File(dir, allowedChars(url.getHost()));
392 subdir = new File(subsubDir, "_" + allowedChars(url.getPath()));
393 name = allowedChars("_" + url.getQuery());
394 }
395
396 File cacheFile = new File(subdir, name);
397 subdir.mkdirs();
398
399 return cacheFile;
400 }
401
402 /**
403 * Get the basic cache resource file corresponding to this unique ID.
404 * <p>
405 * Note that you may need to add a sub-directory in some cases.
406 *
407 * @param uniqueID
408 * the id
409 *
410 * @return the cached version if present, NULL if not
411 */
412 private File getCached(String uniqueID) {
413 File file = new File(dir, allowedChars(uniqueID));
414 File subdir = new File(file.getParentFile(), "_");
415 return new File(subdir, file.getName());
416 }
417
418 /**
419 * Replace not allowed chars (in a {@link File}) by "_".
420 *
421 * @param raw
422 * the raw {@link String}
423 *
424 * @return the sanitised {@link String}
425 */
426 private String allowedChars(String raw) {
427 return raw.replace('/', '_').replace(':', '_').replace("\\", "_");
428 }
429 }