Java Doc for ConcurrentReaderHashMap.java in  » J2EE » wicket » wicket » util » concurrent » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Successful retrievals using get(key) and containsKey(key) usually run without locking. Unsuccessful ones (i.e., when the key is not present) do involve brief synchronization (locking). Also, the size and isEmpty methods are always synchronized.

Because retrieval operations can ordinarily overlap with writing operations (i.e., put, remove, and their derivatives), retrievals can only be guaranteed to return the results of the most recently completed operations holding upon their onset. Retrieval operations may or may not return results reflecting in-progress writing operations. However, the retrieval operations do always return consistent results -- either those holding before any single modification or after it, but never a nonsense result. For aggregate operations such as putAll and clear, concurrent reads may reflect insertion or removal of only some entries. In those rare contexts in which you use a hash table to synchronize operations across threads (for example, to prevent reads until after clears), you should either encase operations in synchronized blocks, or instead use java.util.Hashtable.

This class also supports optional guaranteed exclusive reads, simply by surrounding a call within a synchronized block, as in
ConcurrentReaderHashMap t; ... Object v;
synchronized(t) { v = t.get(k); }
But this is not usually necessary in practice. For example, it is generally inefficient to write:

 ConcurrentReaderHashMap t; ...            // Inefficient version
 Object key; ...
 Object value; ...
 synchronized(t) { 
 if (!t.containsKey(key))
 t.put(key, value);
 // other code if not previously present
 }
 else {
 // other code if it was previously present
 }
 }
 

 ConcurrentReaderHashMap t; ...                // Use this instead
 Object key; ...
 Object value; ...
 Object oldValue = t.put(key, value);
 if (oldValue == null) {
 // other code if not previously present
 }
 else {
 // other code if it was previously present
 }
 

Iterators and Enumerations (i.e., those returned by keySet().iterator(), entrySet().iterator(), values().iterator(), keys(), and elements()) return elements reflecting the state of the hash table at some point at or since the creation of the iterator/enumeration. They will return at most one instance of each element (via next()/nextElement()), but might or might not reflect puts and removes that have been processed since they were created. They do not throw ConcurrentModificationException. However, these iterators are designed to be used by only one thread at a time. Sharing an iterator across multiple threads may lead to unpredictable results if the table is being concurrently modified. Again, you can ensure interference-free iteration by enclosing the iteration in a synchronized block.

This class may be used as a direct replacement for any use of java.util.Hashtable that does not depend on readers being blocked during updates. Like Hashtable but unlike java.util.HashMap, this class does NOT allow null to be used as a key or value. This class is also typically faster than ConcurrentHashMap when there is usually only one thread updating the table, but possibly many retrieving values from it.

Implementation note: A slightly faster implementation of this class will be possible once planned Java Memory Model revisions are in place.

[ Introduction to this package. ]

Note that this method is identical in functionality to containsValue, (which is part of the Map interface in the collections framework).
Parameters:
  value - a value to search for. true if and only if some key maps to thevalue argument in this table as determined by theequals method; false otherwise.
exception:
  NullPointerException - if the value is null.
See Also:   ConcurrentReaderHashMap.containsKey(Object)
See Also:   ConcurrentReaderHashMap.containsValue(Object)
See Also:   Map

The value can be retrieved by calling the get method with a key that is equal to the original key.
Parameters:
  key - the table key.
Parameters:
  value - the value. the previous value of the specified key in this table, ornull if it did not have one.
exception:
  NullPointerException - if the key or value is null.
See Also:   Object.equals(Object)
See Also:   ConcurrentReaderHashMap.get(Object)