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 }