/*
* The contents of this file are subject to the Sapient Public License
* Version 1.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://carbon.sf.net/License.html.
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
* the specific language governing rights and limitations under the License.
*
* The Original Code is The Carbon Component Framework.
*
* The Initial Developer of the Original Code is Sapient Corporation
*
* Copyright (C) 2003 Sapient Corporation. All Rights Reserved.
*/
package org.sape.carbon.services.cache.total;
import java.util.Collection;
import java.util.Map;
import java.util.Set;
import org.sape.carbon.core.component.lifecycle.Startable;
import org.sape.carbon.core.component.lifecycle.Suspendable;
import org.sape.carbon.services.cache.Cache;
import org.sape.carbon.services.cache.CacheLoadException;
/**
* <p>
* This is the base class for caches of data that load all of their contents
* into memory. The methods implemented here fulfill the requirements of the
* Cache interfact with the exception of refreshAll. It also implements the
* Startable and Suspendable interfaces. Refresh and configuration
* functionality are left up to extending classes.
* </p>
*
* Copyright 2002 Sapient
* @since carbon 1.0
* @author Douglas Voet, July 2002
* @version $Revision: 1.7 $($Author: dvoet $ / $Date: 2003/05/05 21:21:08 $)
*/
public abstract class AbstractTotalCache
implements Cache, Startable, Suspendable {
/**
* Refresh the contents of the cache. First, initialize a holding cache.
* Then load the holding cache with new data from the data loader. Finally,
* activate the holding cache.
*
* @throws CacheLoadException when its data loader has failed to load data
*/
public abstract void refreshAll() throws CacheLoadException;
/**
* Removes all mappings from this cache.
*/
public void clear() {
getCacheMap().clear();
}
/**
* <p>For a given key value, return a boolean indicating if the cache
* contains a value for the key.</p>
*
* @param key key for the desired cache entry
* @return true if the cache contains a mapping for the specified key
*/
public boolean containsKey(Object key) {
return getCacheMap().containsKey(key);
}
/**
* Returns true if this cache maps one or more keys to the specified value.
* More formally, returns true if and only if this cache contains at least
* one mapping to a value v such that
* <code>(value==null ? v==null : value.equals(v))</code>.
* This operation will require time linear in the cache size.
*
* @param value value whose presence in this map is to be
* tested.
* @return true if this map maps one or more keys to the specified value.
*/
public boolean containsValue(Object value) {
return getCacheMap().containsValue(value);
}
/**
* Returns a set view of the mappings contained in this cache. Each element
* in the returned set is a Map.Entry. The set is backed by the cache, so
* changes to the map are reflected in the set, and vice-versa. If the cache
* is modified while an iteration over the set is in progress, the results
* of the iteration are undefined. The set supports element removal, which
* removes the corresponding mapping from the cache, via the
* Iterator.remove, Set.remove, removeAll, retainAll and clear operations.
* It does not support the add or addAll operations.
*
* @return the set of mappings in this cache
*/
public Set entrySet() {
return getCacheMap().entrySet();
}
/**
* <p>For a given key value, return the object associated with the key
* value from the cache. If the value is not found in the cache, or the key
* is associated with the value null, a null reference is returned. The only
* way to tell for certain if the cache contains the key is to use the
* containsKey() method.</p>
*
* @param key key for the desired cache entry
* @return <code>Object</code>
*/
public Object get(Object key) {
return getCacheMap().get(key);
}
/**
* Returns true if this map contains no key-value mappings.
*
* @return true if this map contains no key-value mappings
*/
public boolean isEmpty() {
return getCacheMap().isEmpty();
}
/**
* Returns the keys of the cache.
* @return <code>Set</code> The set of all keys in the cache.
*/
public Set keySet() {
return getCacheMap().keySet();
}
/**
* Put the Object value into the cache referenced by the Object key
*
* @param key key for the value to add to this cache
* @param value value to add for the given key
* @return the old value stored at the given key
*/
public Object put(Object key, Object value) {
return getCacheMap().put(key, value);
}
/**
* Copies all of the mappings from the specified map to this cache.
* These mappings will replace any mappings that this cache had for any of
* the keys currently in the specified cache.
*
* @param t the map to place all values of into this cache
*/
public void putAll(Map t) {
getCacheMap().putAll(t);
}
/**
* Removes the mapping for this key from this cache.
*
* @param key the key to remove from the cache
* @return previous value associated with specified key, or null if there
* was no mapping for key.
*/
public Object remove(Object key) {
return getCacheMap().remove(key);
}
/**
* Returns the number of key-value mappings in this map. If the map contains
* more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
*
* @return the number of key-value mappings in this map.
*/
public int size() {
return getCacheMap().size();
}
/**
* Returns a collection view of the values contained in this cache. The
* collection is backed by the cache, so changes to the cache are reflected
* in the collection, and vice-versa.
*
* @return a collection view of the values contained in this cache
*/
public Collection values() {
return getCacheMap().values();
}
/**
* @see Startable#start()
*/
public void start() throws CacheLoadException {
refreshAll();
}
/**
* @see Startable#stop()
*/
public void stop() {
}
/**
* @see Suspendable#resume()
*/
public void resume() throws CacheLoadException {
refreshAll();
}
/**
* @see Suspendable#suspend()
*/
public void suspend() {
}
/**
* This execution should flush the cache of the current entries and refill
* it from the dataloader with new entries.
* @see org.sape.carbon.services.scheduler.Schedulable#runScheduledTask
* @throws CacheLoadException when their is a failure to load the values
* from the dataloader.
*/
public void runScheduledTask() throws CacheLoadException {
refreshAll();
}
/**
* Returns a referench to the Map that contains all the cached data. This
* is used by the Map interface methods of this class.
*
* @return Map containing the cached data
*/
protected abstract Map getCacheMap();
}
|