|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectjava.util.AbstractMap<K,V>
com.sun.sgs.app.util.ScalableHashMap<K,V>
K - the type of keys maintained by this mapV - the type of mapped valuespublic class ScalableHashMap<K,V>
A scalable implementation of Map. The internal structure of the map
is separated into distributed pieces, which reduces the amount of data any
one operation needs to access. The distributed structure increases the
concurrency and allows for parallel write operations to successfully
complete.
Developers may use this class as a drop-in replacement for the HashMap class for use in a ManagedObject. A HashMap will typically perform better than this class when the number of
mappings is small, the objects being stored are small, and minimal
concurrency is required. As the size of the serialized HashMap
increases, this class will perform significantly better. Developers are
encouraged to profile the serialized size of their map to determine which
implementation will perform better. Note that HashMap does not
provide any concurrency for Tasks running in parallel that attempt
to modify the map at the same time, so this class may perform better in
situations where multiple tasks need to modify the map concurrently, even if
the total number of mappings is small. Also note that, unlike HashMap, this class can be used to store ManagedObject instances
directly.
This implementation requires that all non-null keys and values
implement Serializable. Attempting to add keys or values to the map
that do not implement Serializable will result in an IllegalArgumentException being thrown. If a key or value is an instance of
Serializable but does not implement ManagedObject, this
class will persist the object as necessary; when such an object is removed
from the map, it is also removed from the DataManager. If a key or
value is an instance of ManagedObject, the developer will be
responsible for removing these objects from the DataManager when
done with them. Developers should not remove these object from the DataManager prior to removing them from the map.
Applications must make sure that objects used as keys in maps of this class
have equals and hashCode methods that return the same values
after the keys have been serialized and deserialized. In particular, keys
that use Object.equals and Object.hashCode will typically not be equal, and will have different hash
codes, each time they are deserialized, and so are probably not suitable for
use with this class. The same requirements apply to objects used as values
if the application intends to use containsValue or to
compare map entries.
This class marks itself for update as necessary; no additional calls to the
DataManager are necessary when modifying the map. Developers do not
need to call markForUpdate or getForUpdate on this map, as
this will eliminate all the concurrency benefits of this class. However,
calling getForUpdate or markForUpdate can be used if a
operation needs to prevent all access to the map.
Note that, unlike most collections, the size and isEmpty
methods for this class are not constant-time operations. Because of
the asynchronous nature of the map, these operations may require accessing
all of the entries in the map.
An instance of ScalableHashMap offers one parameter for performance
tuning: minConcurrency, which specifies the minimum number of write
operations to support in parallel. This parameter acts as a hint to the map
on how to perform resizing. As the map grows, the number of supported
parallel operations will also grow beyond the specified minimum. Setting
the minimum concurrency too high will waste space and time, while setting it
too low will cause conflicts until the map grows sufficiently to support
more concurrent operations.
Since the expected distribution of objects in the map is essentially random, the actual concurrency will vary. Developers are strongly encouraged to use hash codes that provide a normal distribution; a large number of collisions will likely reduce the performance.
This class provides Serializable views from the entrySet, keySet and values methods. These
views may be shared and persisted by multiple ManagedObject
instances.
The Iterator for each view also implements
Serializable. A single iterator may be saved by different ManagedObject instances, which will create distinct copies of the original
iterator. A copy starts its iteration from where the state of the original
was at the time of the copy. However, each copy maintains a separate,
independent state from the original and will therefore not reflect any
changes to the original iterator. To share a single Iterator
between multiple ManagedObject and have the iterator use a
consistent view for each, the iterator should be contained within a shared
ManagedObject.
The iterators do not throw ConcurrentModificationException. The iterators are stable with
respect to concurrent changes to the associated collection, but may ignore
additions and removals made to the collection during iteration, and may also
visit more than once a key value that is removed and re-added. Attempting
to use an iterator when the associated map has been removed from the DataManager will result in an ObjectNotFoundException being thrown,
although the remove method may throw IllegalStateException instead if that is appropriate.
If a call to the next method on the iterators causes
an ObjectNotFoundException to be thrown because the return value has
been removed from the DataManager, the iterator will still have
successfully moved to the next entry in its iteration. In this case, the
remove method may be called on the iterator to
remove the current object even though that object could not be returned.
This class and its iterator implement all optional operations and support
both null keys and values. This map provides no guarantees on the
order of elements when iterating over the key set, values or entry set.
Object.hashCode,
Map,
Serializable,
ManagedObject,
Serialized Form| Nested Class Summary |
|---|
| Nested classes/interfaces inherited from class java.util.AbstractMap |
|---|
AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V> |
| Nested classes/interfaces inherited from interface java.util.Map |
|---|
Map.Entry<K,V> |
| Constructor Summary | |
|---|---|
ScalableHashMap()
Constructs an empty map with the default minimum concurrency ( 32). |
|
ScalableHashMap(int minConcurrency)
Creates an empty map with the specified minimum concurrency. |
|
ScalableHashMap(Map<? extends K,? extends V> map)
Constructs a new map with the same mappings as the specified Map, and the default minimum concurrency (32). |
|
| Method Summary | |
|---|---|
void |
clear()
Clears the map of all entries. |
boolean |
containsKey(Object key)
|
boolean |
containsValue(Object value)
Note that the execution time of this method grows substantially as the map size increases due to the cost of accessing the data manager. |
Set<Map.Entry<K,V>> |
entrySet()
Returns a concurrent, Serializable Set of all the
mappings contained in this map. |
V |
get(Object key)
Returns the value to which this key is mapped or null if the map
contains no mapping for this key. |
boolean |
isEmpty()
Returns whether this map has no mappings. |
Set<K> |
keySet()
Returns a concurrent, Serializable Set of all the keys
contained in this map. |
V |
put(K key,
V value)
Associates the specified key with the provided value and returns the previous value if the key was previous mapped. |
void |
putAll(Map<? extends K,? extends V> m)
Copies all of the mappings from the provided map into this map. |
V |
remove(Object key)
Removes the mapping for the specified key from this map if present. |
void |
removingObject()
Performs additional operations that are needed when this object is removed. |
int |
size()
Returns the size of the tree. |
Collection<V> |
values()
Returns a concurrent, Serializable Collection of all the
values contained in this map. |
| Methods inherited from class java.util.AbstractMap |
|---|
equals, hashCode, toString |
| Methods inherited from class java.lang.Object |
|---|
getClass, notify, notifyAll, wait, wait, wait |
| Constructor Detail |
|---|
public ScalableHashMap(int minConcurrency)
minConcurrency - the minimum number of concurrent write operations
to support
IllegalArgumentException - if minConcurrency is
not greater than zeropublic ScalableHashMap()
32).
public ScalableHashMap(Map<? extends K,? extends V> map)
Map, and the default minimum concurrency (32).
map - the mappings to include
IllegalArgumentException - if any of the keys or values contained
in the argument are not null and do not implement Serializable| Method Detail |
|---|
public void clear()
ManagedObject keys and values persisted by this map will be removed
from the DataManager.
clear in interface Map<K,V>clear in class AbstractMap<K,V>public boolean containsKey(Object key)
containsKey in interface Map<K,V>containsKey in class AbstractMap<K,V>public boolean containsValue(Object value)
containsValue in interface Map<K,V>containsValue in class AbstractMap<K,V>public V get(Object key)
null if the map
contains no mapping for this key. Note that the return value of null does not necessarily imply that no mapping for this key existed
since this implementation supports null values. The containsKey method can be used to determine whether a
mapping exists.
get in interface Map<K,V>get in class AbstractMap<K,V>key - the key whose mapped value is to be returned
null if no such
mapping exists
ObjectNotFoundException - if the value associated with the key has
been removed from the DataManager
public V put(K key,
V value)
null keys and values.
If the value currently associated with key has been removed from
the DataManager, then an ObjectNotFoundException will be
thrown and the mapping will not be changed.
put in interface Map<K,V>put in class AbstractMap<K,V>key - the keyvalue - the value to be mapped to the key
IllegalArgumentException - if either key or value
is not null and does not implement Serializable
ObjectNotFoundException - if the previous value associated with
the key has been removed from the DataManagerpublic void putAll(Map<? extends K,? extends V> m)
putAll in interface Map<K,V>putAll in class AbstractMap<K,V>m - the map to be copied
IllegalArgumentException - if any of the keys or values contained
in the argument are not null and do not implement Serializable. If this exception is thrown, some of the entries
from the argument may have already been added to this map.public boolean isEmpty()
isEmpty in interface Map<K,V>isEmpty in class AbstractMap<K,V>true if this map contains no mappingspublic int size()
O(n*log(n)) time. Developers should be cautious of calling this
method on large maps, as the execution time grows significantly. Developers can avoid possible scaling problems by using an iterator to count the number of elements in the tree, but counting only a few elements before scheduling the rest of the job as a task to be performed by the task scheduler.
size in interface Map<K,V>size in class AbstractMap<K,V>public V remove(Object key)
If the value currently associated with key has been removed from
the DataManager, then an ObjectNotFoundException will be
thrown and the mapping will not be removed.
remove in interface Map<K,V>remove in class AbstractMap<K,V>key - key whose mapping is to be removed from the map
key, or null
if there was no mapping for key. (A null return
can also indicate that the map previously associated null with key.)
ObjectNotFoundException - if the value associated with the key has
been removed from the DataManagerpublic void removingObject()
This implementation removes from the DataManager all non-ManagedObject keys and values persisted by this map, as well as objects
that make up the internal structure of the map itself.
removingObject in interface ManagedObjectRemovalpublic Set<Map.Entry<K,V>> entrySet()
Serializable Set of all the
mappings contained in this map. The returned Set is backed by
the map, so changes to the map will be reflected by this view. Note
that the time complexity of the operations on this set will be the same
as those on the map itself.
The iterator returned by this set also implements Serializable.
See the javadoc for details.
entrySet in interface Map<K,V>entrySet in class AbstractMap<K,V>public Set<K> keySet()
Serializable Set of all the keys
contained in this map. The returned Set is backed by the map,
so changes to the map will be reflected by this view. Note that the
time complexity of the operations on this set will be the same as those
on the map itself.
The iterator returned by this set also implements Serializable.
See the javadoc for details.
keySet in interface Map<K,V>keySet in class AbstractMap<K,V>public Collection<V> values()
Serializable Collection of all the
values contained in this map. The returned Collection is backed
by the map, so changes to the map will be reflected by this view. Note
that the time complexity of the operations on this set will be the same
as those on the map itself.
The iterator returned by this set also implements Serializable.
See the javadoc for details.
values in interface Map<K,V>values in class AbstractMap<K,V>
|
Project Darkstar, Version 0.9.9.6 2009-05-08 15:39:40 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||