Abstract base class and factory for caches. A cache is a key-value mapping. It has properties that make it more suitable for caching than a Map. The factory methods can be used to obtain two different implementations. They have the following properties: . keys and values reside in memory . keys and values must be non-null . maximum size. Replacements are made in LRU order. . optional lifetime, specified in seconds. . safe for concurrent use by multiple threads . values are held by either standard references or via SoftReferences. SoftReferences have the advantage that they are automatically cleared by the garbage collector in response to memory demand. This makes it possible to simple set the maximum size to a very large value and let the GC automatically size the cache dynamically depending on the amount of available memory. However, note that because of the way SoftReferences are implemented in HotSpot at the moment, this may not work perfectly as it clears them fairly eagerly. Performance may be improved if the Java heap size is set to larger value using e.g. java -Xms64M -Xmx128M foo.Test Cache sizing: the memory cache is implemented on top of a LinkedHashMap. In its current implementation, the number of buckets (NOT entries) in (Linked)HashMaps is always a power of two. It is recommended to set the maximum cache size to value that uses those buckets fully. For example, if a cache with somewhere between 500 and 1000 entries is desired, a maximum size of 750 would be a good choice: try 1024 buckets, with a load factor of 0.75f, the number of entries can be calculated as buckets / 4 * 3. As mentioned above, with a SoftReference cache, it is generally reasonable to set the size to a fairly large value.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	Cache.CacheVisitor<K, V>
public static class	Cache.EqualByteArray Utility class that wraps a byte array and implements the equals() and hashCode() contract in a way suitable for Maps and caches.

Access	Constructor and Description
protected	Cache()

Method Summary

Modifier and Type	Method and Description
public abstract void	accept(Cache.CacheVisitor<K, V> visitor) accept a visitor
public abstract void	clear() Remove all entries from the cache.
public abstract V	get(Object key) Get a value from the cache.
public static <K, V> Cache<K, V>	newHardMemoryCache(int size) Return a new memory cache with the specified maximum size, unlimited lifetime for entries, with the values held by standard references.
public static <K, V> Cache<K, V>	newHardMemoryCache(int size, int timeout) Return a new memory cache with the specified maximum size, the specified maximum lifetime (in seconds), with the values held by standard references.
public static <K, V> Cache<K, V>	newNullCache() Return a dummy cache that does nothing.
public static <K, V> Cache<K, V>	newSoftMemoryCache(int size) Return a new memory cache with the specified maximum size, unlimited lifetime for entries, with the values held by SoftReferences.
public static <K, V> Cache<K, V>	newSoftMemoryCache(int size, int timeout) Return a new memory cache with the specified maximum size, the specified maximum lifetime (in seconds), with the values held by SoftReferences.
public static <K, V> Cache<K, V>	newSoftMemoryQueue(int size, int timeout, int maxQueueSize)
public abstract V	pull(Object key) Pull an entry from the cache.
public abstract void	put(K key, V value) Add an entry to the cache.
public void	put(K key, V value, boolean canQueue) Add V to the cache with the option to use a QueueCacheEntry if the cache is configured for it.
public abstract void	remove(Object key) Remove an entry from the cache.
public abstract void	setCapacity(int size) Set the maximum size.
public abstract void	setTimeout(int timeout) Set the timeout(in seconds).
public abstract int	size() Return the number of currently valid entries in the cache.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Cache	back to summary
protected Cache()

Method Detail

accept	back to summary
public abstract void accept(Cache.CacheVisitor<K, V> visitor) accept a visitor

clear	back to summary
public abstract void clear() Remove all entries from the cache.

get	back to summary
public abstract V get(Object key) Get a value from the cache.

newHardMemoryCache	back to summary
public static <K, V> Cache<K, V> newHardMemoryCache(int size) Return a new memory cache with the specified maximum size, unlimited lifetime for entries, with the values held by standard references.

newHardMemoryCache	back to summary
public static <K, V> Cache<K, V> newHardMemoryCache(int size, int timeout) Return a new memory cache with the specified maximum size, the specified maximum lifetime (in seconds), with the values held by standard references.

newNullCache	back to summary
public static <K, V> Cache<K, V> newNullCache() Return a dummy cache that does nothing. Annotations @SuppressWarnings:unchecked

newNullCache

back to summary

public static <K, V> Cache<K, V> newNullCache()

Return a dummy cache that does nothing.

Annotations

@SuppressWarnings:unchecked

newSoftMemoryCache	back to summary
public static <K, V> Cache<K, V> newSoftMemoryCache(int size) Return a new memory cache with the specified maximum size, unlimited lifetime for entries, with the values held by SoftReferences.

newSoftMemoryCache	back to summary
public static <K, V> Cache<K, V> newSoftMemoryCache(int size, int timeout) Return a new memory cache with the specified maximum size, the specified maximum lifetime (in seconds), with the values held by SoftReferences.

newSoftMemoryQueue	back to summary
public static <K, V> Cache<K, V> newSoftMemoryQueue(int size, int timeout, int maxQueueSize)

pull	back to summary
public abstract V pull(Object key) Pull an entry from the cache.

put	back to summary
public abstract void put(K key, V value) Add an entry to the cache.

put	back to summary
public void put(K key, V value, boolean canQueue) Add V to the cache with the option to use a QueueCacheEntry if the cache is configured for it. If the cache is not configured for a queue, V will silently add the entry directly.

remove	back to summary
public abstract void remove(Object key) Remove an entry from the cache.

setCapacity	back to summary
public abstract void setCapacity(int size) Set the maximum size.

setTimeout	back to summary
public abstract void setTimeout(int timeout) Set the timeout(in seconds).

size	back to summary
public abstract int size() Return the number of currently valid entries in the cache.

sun.security.util back to summary

public Interface Cache.CacheVisitor<K, V>

Known Direct Implementers: sun.security.ssl.SSLSessionContextImpl.SessionCacheVisitor

Method Summary

Modifier and Type	Method and Description
public void	visit(Map<K, V> map)

Method Detail

visit	back to summary
public void visit(Map<K, V> map)

sun.security.util back to summary

public Class Cache.EqualByteArray

Class Inheritance

extends Object

java.lang.Object
sun.security.util.Cache.EqualByteArray

Utility class that wraps a byte array and implements the equals() and hashCode() contract in a way suitable for Maps and caches.

Field Summary

Modifier and Type	Field and Description
private final byte[]	b
private int	hash

Constructor Summary

Access	Constructor and Description
public	EqualByteArray(byte[] b)

Method Summary

Modifier and Type	Method and Description
public boolean	equals(Object obj) Overrides java.lang.Object.equals. Indicates whether some other object is "equal to" this one.
public int	hashCode() Overrides java.lang.Object.hashCode. Returns a hash code value for this object.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll toString wait wait wait

Field Detail

b	back to summary
private final byte[] b

hash	back to summary
private int hash

Constructor Detail

EqualByteArray	back to summary
public EqualByteArray(byte[] b)

Method Detail

equals back to summary

equals	back to summary
public boolean equals(Object obj) Overrides java.lang.Object.equals. Doc from java.lang.Object.equals. Indicates whether some other object is "equal to" this one. The `equals` method implements an equivalence relation on non-null object references: It is reflexive: for any non-null reference value `x`, `x.equals(x)` should return `true`. It is symmetric: for any non-null reference values `x` and `y`, `x.equals(y)` should return `true` if and only if `y.equals(x)` returns `true`. It is transitive: for any non-null reference values `x`, `y`, and `z`, if `x.equals(y)` returns `true` and `y.equals(z)` returns `true`, then `x.equals(z)` should return `true`. It is consistent: for any non-null reference values `x` and `y`, multiple invocations of `x.equals(y)` consistently return `true` or consistently return `false`, provided no information used in `equals` comparisons on the objects is modified. For any non-null reference value `x`, `x.equals(null)` should return `false`. An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Doc from java.lang.Object.equals.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

It is reflexive: for any non-null reference value x, x.equals(x) should return true.
It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
For any non-null reference value x, x.equals(null) should return false.

An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.

hashCode back to summary

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Doc from java.lang.Object.hashCode. Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by `java.util.HashMap`. The general contract of `hashCode` is: Whenever it is invoked on the same object more than once during an execution of a Java application, the `hashCode` method must consistently return the same integer, provided no information used in `equals` comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the `equals` method, then calling the `hashCode` method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the `equals` method, then calling the `hashCode` method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

public abstract Class Cache<K, V>

Nested and Inner Type Summary

Constructor Summary

Method Summary

Constructor Detail

Method Detail

public Interface Cache.CacheVisitor<K, V>

Method Summary

Method Detail

public Class Cache.EqualByteArray

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail