org.cache2k

Interface Cache<K,T>

All Superinterfaces:

AutoCloseable, CacheSource<K,T>, Closeable, Iterable<CacheEntry<K,T>>, KeyValueSource<K,T>

public interface Cache<K,T>
extends KeyValueSource<K,T>, Iterable<CacheEntry<K,T>>, Closeable

Interface to the cache2k cache implementation. To obtain a cache instance use the CacheBuilder.

Author:

Jens Wilke

See Also:

to create a new cache

Method Summary

Modifier and Type	Method and Description
void	clear() Clear the cache contents
void	close() Free all resources and remove the cache from the CacheManager.
boolean	contains(K key) Returns true if the there is a mapping for the specified key.
void	destroy() Deprecated. use close()
void	flush() Ensure that any transient data is stored in the persistence storage.
T	get(K key) Returns object in the cache that is mapped to the key.
Map<K,T>	getAll(Set<? extends K> keys) Disclaimer: This method is here to be able to support known coding similar to JSR107.
CacheEntry<K,T>	getEntry(K key) Returns a mapped entry from the cache or null.
String	getName()
int	getTotalEntryCount() Number of entries the cache holds in total.
ClosableIterator<CacheEntry<K,T>>	iterator() Iterate all entries in the cache.
T	peek(K key) Returns the value if it is mapped within the cache and not expired, or null.
CacheEntry<K,T>	peekEntry(K key) Returns a mapped entry from the cache or null.
void	prefetch(K key) Signals the intent to call a get on the same key in the near future.
void	prefetch(List<K> keys, int _startIndex, int _afterEndIndex)
void	prefetch(Set<K> keys) Signals the intend to call get on the set of keys in the near future.
void	purge() Remove persistent entries, that are not longer needed.
void	put(K key, T value) Set object value for the key
boolean	putIfAbsent(K key, T value)
void	remove(K key) Remove the object mapped to key from the cache.
void	removeAllAtOnce(Set<K> key) Remove the mappings for the keys atomically.
String	toString() Returns information about the caches internal information.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

getName

String getName()

clear

void clear()

Clear the cache contents

get

T get(K key)

Returns object in the cache that is mapped to the key.

Specified by:

get in interface CacheSource<K,T>

Specified by:

get in interface KeyValueSource<K,T>

getEntry

CacheEntry<K,T> getEntry(K key)

Returns a mapped entry from the cache or null. If no entry is present or the entry is expired, null is also returned.

If an exception was thrown during fetching the entry via the cache source, method does not follow the same schema of rethrowing the exception like in get() and peek(), instead the exception can be retrieved via, CacheEntry.getException()

The reason for the existence of this method is, that in the presence of null values it cannot be determined by peek() and get() if there is a mapping or a null value.

Multiple calls for the same key may return different instances of the entry object.

prefetch

void prefetch(K key)

Signals the intent to call a get on the same key in the near future.

Triggers a prefetch and returns immediately. If the entry is in the cache already and still fresh nothing will happen. If the entry is not in the cache or expired a fetch will be triggered. The fetch will take place with the same thread pool then the one used for background refresh.

prefetch

void prefetch(Set<K> keys)

Signals the intend to call get on the set of keys in the near future.

Without threads: Issues a bulk fetch on the set of keys not in the cache.

With threads: If a thread is available than start the fetch operation on the missing key mappings and return after the keys are locked for data fetch within the fetch. A sequential get on a key will stall until the value is loaded.

prefetch

void prefetch(List<K> keys,
              int _startIndex,
              int _afterEndIndex)

peek

T peek(K key)

Returns the value if it is mapped within the cache and not expired, or null. No request on the cache source is made.

Throws:

PropagatedCacheException - if an exception happened when the value was fetched by the cache source

peekEntry

CacheEntry<K,T> peekEntry(K key)

Returns a mapped entry from the cache or null. If no entry is present or the entry is expired, null is also returned. As with peek(Object), no request to the CacheSource is made, if no entry is available for the requested key.

If an exception was thrown during fetching the entry via the cache source, method does not follow the same schema of rethrowing the exception like in get() and peek(), instead the exception can be retrieved via, CacheEntry.getException()

The reason for the existence of this method is, that in the presence of null values it cannot be determined by peek() and get() if there is a mapping or a null value.

Multiple calls for the same key may return different instances of the entry object.

contains

boolean contains(K key)

Returns true if the there is a mapping for the specified key. Does not invoke the CacheSource if no entry exists.

put

void put(K key,
         T value)

Set object value for the key

putIfAbsent

boolean putIfAbsent(K key,
                    T value)

remove

void remove(K key)

Remove the object mapped to key from the cache.

removeAllAtOnce

void removeAllAtOnce(Set<K> key)

Remove the mappings for the keys atomically. Missing keys will be ignored.

Parallel fetches from the cache source, that are currently ongoing for some of the given keys, will be ignored.

getAll

Map<K,T> getAll(Set<? extends K> keys)

Disclaimer: This method is here to be able to support known coding similar to JSR107. Do not use it. Just use prefetch() and the normal Cache.get(). Since Cache.get() is almost as fast as a HashMap there is no need to build up mini-caches. The caller code will also look much cleaner.

Bulk get: gets all values associated with the keys. If an exception happened during the fetch of any key, this exception will be thrown wrapped into a PropagatedCacheException. If more exceptions exist, the selection is arbitrary.

The cache source does not need to support the bulk operation. It is neither guaranteed that the bulk get is called on the cache source if it exists.

The operation may be split into chunks and not performed atomically. The entries that are processed within a chunk will be locked, to avoid duplicate fetches from the cache source. To avoid deadlocks there is a fallback non-bulk operation if a fetch is ongoing and the keys overlap.

In contrast to JSR107 the following guarantees are met if the operation returns without exception: map.size() == keys.size()

Exception handling: The method may terminate normal, even if a cache fetch via cache source failed. In this case the exception will be thrown when the value is requested from the map.

Throws:

PropagatedCacheException - may be thrown if the fetch fails.

getTotalEntryCount

int getTotalEntryCount()

Number of entries the cache holds in total. When iterating the entries the cache will always return less or an identical number of entries. The reason for this is, that duplicate entries may exist in different storage layers (typically in heap and in persistent storage), or may be expired already.

The method has more statistical value and the result depends on the actual configuration of the cache.

TODO-API: Keep this for the final API?

iterator

ClosableIterator<CacheEntry<K,T>> iterator()

Iterate all entries in the cache.

Contract: All entries present in the cache by the call of the method call will be iterated if not removed during the iteration goes on. The iteration may or may not iterate entries inserted during the iteration is in progress. The iteration never iterates duplicate entries.

The iteration is usable concurrently. Concurrent operations will not be influenced. Mutations of the cache, like remove or put, will not stop the iteration.

The iterator itself is not thread safe. Calls to one iterator instance from different threads need to be properly synchronized.

The iterator holds resources. If an iteration is aborted, the resources should be freed by calling ClosableIterator.close(), e.g. with a try with resources pattern.

Specified by:

iterator in interface Iterable<CacheEntry<K,T>>

purge

void purge()

Remove persistent entries, that are not longer needed. Only has an effect if a storage is defined.

flush

void flush()

Ensure that any transient data is stored in the persistence storage. Nothing will be done if no persistent storage is configured.

destroy

void destroy()

Deprecated. use close()

close

void close()

Free all resources and remove the cache from the CacheManager. If persistence support is enabled, the cache may flush unwritten data. Depending on the configuration of the persistence, this method only returns after all unwritten data is flushed to disk.

The method is designed to free resources and finish operations as gracefully and fast as possible. Some cache operations take an unpredictable long time such as the call of the CacheSource.get(Object), so it may happen that the cache still has threads in use when this method returns.

After close, subsequent cache operations will throw a CacheException. Cache operations currently in progress, may or may not terminated with an exception.

If all caches need to be closed it is more effective to use CacheManager.close()

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

toString

String toString()

Returns information about the caches internal information. Calling toString() on the cache object is an expensive operation, since internal statistics are collected and other thread users need to be locked out, to have a consistent view.

Overrides:

toString in class Object