001package org.cache2k.storage;
002
003/*
004 * #%L
005 * cache2k core package
006 * %%
007 * Copyright (C) 2000 - 2015 headissue GmbH, Munich
008 * %%
009 * This program is free software: you can redistribute it and/or modify
010 * it under the terms of the GNU General Public License as
011 * published by the Free Software Foundation, either version 3 of the 
012 * License, or (at your option) any later version.
013 * 
014 * This program is distributed in the hope that it will be useful,
015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
017 * GNU General Public License for more details.
018 * 
019 * You should have received a copy of the GNU General Public 
020 * License along with this program.  If not, see
021 * <http://www.gnu.org/licenses/gpl-3.0.html>.
022 * #L%
023 */
024
025/**
026 * @author Jens Wilke; created: 2014-06-21
027 */
028public interface PurgeableStorage {
029
030  /**
031   * Removes all entries which have an expiry time before or equal to the
032   * given time. The time for the value expiry may be not identical to the
033   * current time, if the cache wants to keep some entries that are recently
034   * expired, e.g. if a CacheSource is present and a scheme like
035   * if-modified-since is supported by it.
036   *
037   * <p/>The storage implementation may choose to implement only one or no
038   * expiry variant by time.
039   *
040   * @param ctx Provides a multi-threaded context. Thread resources for purge
041   *            operations may be more limited or may have lower priority.
042   * @param _valueExpiryTime request to remove entries with lower value of
043   *           {@link StorageEntry#getValueExpiryTime()}
044   * @param _entryExpiryTime request to remove entries with with lower value of
045   *           {@link StorageEntry#getEntryExpiryTime()}
046   * @return statistical result of the operation, if nothing was done null.
047   */
048  public PurgeResult purge(PurgeContext ctx, long _valueExpiryTime, long _entryExpiryTime) throws Exception;
049
050  public static interface PurgeContext extends CacheStorage.MultiThreadedContext {
051
052    /**
053     * Runs the action under the entry lock for the key. The actual purge
054     * needs to be done within the runnable to avoid races. This is important
055     * if the storage relies on the entry locking of the cache and has no
056     * locking for the entry I/O itself.
057     */
058    void lockAndRun(Object key, PurgeAction _action);
059
060  }
061
062  /**
063   * Statistics
064   */
065  public static interface PurgeResult {
066
067    /**
068     * Free space reclaimed. -1 if not supported
069     */
070    long getBytesFreed();
071
072    /**
073     * Number of entries purged
074     */
075    int getEntriesPurged();
076
077    /**
078     * Number of entries scanned. This may be less than the total number
079     * of entries in the storage, if a partial purge is done.
080     */
081    int getEntriesScanned();
082
083  }
084
085  interface PurgeAction {
086
087    /**
088     * Check storage whether entry for the key is still expired. If yes,
089     * remove it. Otherwise the entry is returned.
090     */
091    StorageEntry checkAndPurge(Object key);
092
093  }
094}