/*
Copyright © 2013-2014, Silent Circle, LLC.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Any redistribution, use, or modification is done solely for personal
benefit and not for any commercial purpose or for monetary gain
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name Silent Circle nor the names of its contributors may
be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL SILENT CIRCLE, LLC BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/*
* This implementation is edited version of original Android sources.
*/
/*
* Copyright (C) 2011 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.silentcircle.contacts.utils;
// import com.android.contacts.test.NeededForTesting;
import java.util.concurrent.atomic.AtomicInteger;
import android.support.v4.util.LruCache;
//import javax.annotation.concurrent.Immutable;
//import javax.annotation.concurrent.ThreadSafe;
/**
* An LRU cache in which all items can be marked as expired at a given time and it is possible to
* query whether a particular cached value is expired or not.
* <p>
* A typical use case for this is caching of values which are expensive to compute but which are
* still useful when out of date.
* <p>
* Consider a cache for contact information:
* <pre>{@code
* private ExpirableCache<String, Contact> mContactCache;}</pre>
* which stores the contact information for a given phone number.
* <p>
* When we need to store contact information for a given phone number, we can look up the info in
* the cache:
* <pre>{@code
* CachedValue<Contact> cachedContact = mContactCache.getCachedValue(phoneNumber);
* }</pre>
* We might also want to fetch the contact information again if the item is expired.
* <pre>
* if (cachedContact.isExpired()) {
* fetchContactForNumber(phoneNumber,
* new FetchListener() {
* @Override
* public void onFetched(Contact contact) {
* mContactCache.put(phoneNumber, contact);
* }
* });
* }</pre>
* and insert it back into the cache when the fetch completes.
* <p>
* At a certain point we want to expire the content of the cache because we know the content may
* no longer be up-to-date, for instance, when resuming the activity this is shown into:
* <pre>
* @Override
* protected onResume() {
* // We were paused for some time, the cached value might no longer be up to date.
* mContactCache.expireAll();
* super.onResume();
* }
* </pre>
* The values will be still available from the cache, but they will be expired.
* <p>
* If interested only in the value itself, not whether it is expired or not, one should use the
* {@link #getPossiblyExpired(Object)} method. If interested only in non-expired values, one should
* use the {@link #get(Object)} method instead.
* <p>
* This class wraps around an {@link LruCache} instance: it follows the {@link LruCache} behavior
* for evicting items when the cache is full. It is possible to supply your own subclass of LruCache
* by using the {@link #create(LruCache)} method, which can define a custom expiration policy.
* Since the underlying cache maps keys to cached values it can determine which items are expired
* and which are not, allowing for an implementation that evicts expired items before non expired
* ones.
* <p>
* This class is thread-safe.
*
* @param <K> the type of the keys
* @param <V> the type of the values
*/
// @ThreadSafe
public class ExpirableCache<K, V> {
/**
* A cached value stored inside the cache.
* <p>
* It provides access to the value stored in the cache but also allows to check whether the
* value is expired.
*
* @param <V> the type of value stored in the cache
*/
public interface CachedValue<V> {
/** Returns the value stored in the cache for a given key. */
public V getValue();
/**
* Checks whether the value, while still being present in the cache, is expired.
*
* @return true if the value is expired
*/
public boolean isExpired();
}
/**
* Cached values storing the generation at which they were added.
*/
// @Immutable
private static class GenerationalCachedValue<V> implements ExpirableCache.CachedValue<V> {
/** The value stored in the cache. */
public final V mValue;
/** The generation at which the value was added to the cache. */
private final int mGeneration;
/** The atomic integer storing the current generation of the cache it belongs to. */
private final AtomicInteger mCacheGeneration;
/**
* @param cacheGeneration the atomic integer storing the generation of the cache in which
* this value will be stored
*/
public GenerationalCachedValue(V value, AtomicInteger cacheGeneration) {
mValue = value;
mCacheGeneration = cacheGeneration;
// Snapshot the current generation.
mGeneration = mCacheGeneration.get();
}
@Override
public V getValue() {
return mValue;
}
@Override
public boolean isExpired() {
return mGeneration != mCacheGeneration.get();
}
}
/** The underlying cache used to stored the cached values. */
private LruCache<K, CachedValue<V>> mCache;
/**
* The current generation of items added to the cache.
* <p>
* Items in the cache can belong to a previous generation, but in that case they would be
* expired.
*
* @see ExpirableCache.CachedValue#isExpired()
*/
private final AtomicInteger mGeneration;
private ExpirableCache(LruCache<K, CachedValue<V>> cache) {
mCache = cache;
mGeneration = new AtomicInteger(0);
}
/**
* Returns the cached value for the given key, or null if no value exists.
* <p>
* The cached value gives access both to the value associated with the key and whether it is
* expired or not.
* <p>
* If not interested in whether the value is expired, use {@link #getPossiblyExpired(Object)}
* instead.
* <p>
* If only wants values that are not expired, use {@link #get(Object)} instead.
*
* @param key the key to look up
*/
public CachedValue<V> getCachedValue(K key) {
return mCache.get(key);
}
/**
* Returns the value for the given key, or null if no value exists.
* <p>
* When using this method, it is not possible to determine whether the value is expired or not.
* Use {@link #getCachedValue(Object)} to achieve that instead. However, if using
* {@link #getCachedValue(Object)} to determine if an item is expired, one should use the item
* within the {@link CachedValue} and not call {@link #getPossiblyExpired(Object)} to get the
* value afterwards, since that is not guaranteed to return the same value or that the newly
* returned value is in the same state.
*
* @param key the key to look up
*/
public V getPossiblyExpired(K key) {
CachedValue<V> cachedValue = getCachedValue(key);
return cachedValue == null ? null : cachedValue.getValue();
}
/**
* Returns the value for the given key only if it is not expired, or null if no value exists or
* is expired.
* <p>
* This method will return null if either there is no value associated with this key or if the
* associated value is expired.
*
* @param key the key to look up
*/
// @NeededForTesting
// public V get(K key) {
// CachedValue<V> cachedValue = getCachedValue(key);
// return cachedValue == null || cachedValue.isExpired() ? null : cachedValue.getValue();
// }
/**
* Puts an item in the cache.
* <p>
* Newly added item will not be expired until {@link #expireAll()} is next called.
*
* @param key the key to look up
* @param value the value to associate with the key
*/
public void put(K key, V value) {
mCache.put(key, newCachedValue(value));
}
/**
* Mark all items currently in the cache as expired.
* <p>
* Newly added items after this call will be marked as not expired.
* <p>
* Expiring the items in the cache does not imply they will be evicted.
*/
public void expireAll() {
mGeneration.incrementAndGet();
}
/**
* Creates a new {@link CachedValue} instance to be stored in this cache.
* <p>
* Implementation of {@link LruCache#create(K)} can use this method to create a new entry.
*/
public CachedValue<V> newCachedValue(V value) {
return new GenerationalCachedValue<V>(value, mGeneration);
}
/**
* Creates a new {@link ExpirableCache} that wraps the given {@link LruCache}.
* <p>
* The created cache takes ownership of the cache passed in as an argument.
*
* @param <K> the type of the keys
* @param <V> the type of the values
* @param cache the cache to store the value in
* @return the newly created expirable cache
* @throws IllegalArgumentException if the cache is not empty
*/
public static <K, V> ExpirableCache<K, V> create(LruCache<K, CachedValue<V>> cache) {
return new ExpirableCache<K, V>(cache);
}
/**
* Creates a new {@link ExpirableCache} with the given maximum size.
*
* @param <K> the type of the keys
* @param <V> the type of the values
* @return the newly created expirable cache
*/
public static <K, V> ExpirableCache<K, V> create(int maxSize) {
return create(new LruCache<K, CachedValue<V>>(maxSize));
}
}