Developers may use this class as a drop-in replacement for the {@link java.util.HashMap} class for use in a {@link ManagedObject}. A {@code HashMap} will typically perform better than this class when the number ofmappings is small, the objects being stored are small, and minimal concurrency is required. As the size of the serialized {@code 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 {@code HashMap} does notprovide any concurrency for {@code Task}s 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 {@code HashMap}, this class can be used to store {@code ManagedObject} instancesdirectly.
This implementation requires that all non- {@code null} keys and valuesimplement {@link Serializable}. Attempting to add keys or values to the map that do not implement {@code Serializable} will result in an {@link IllegalArgumentException} being thrown. If a key or value is an instance of{@code Serializable} but does not implement {@code ManagedObject}, this class will persist the object as necessary; when such an object is removed from the map, it is also removed from the {@code DataManager}. If a key or value is an instance of {@code ManagedObject}, the developer will be responsible for removing these objects from the {@code DataManager} whendone with them. Developers should not remove these object from the {@code DataManager} prior to removing them from the map.
Applications must make sure that objects used as keys in maps of this class have {@code equals} and {@code hashCode} methods that return the same valuesafter the keys have been serialized and deserialized. In particular, keys that use {@link Object#equals Object.equals} and {@link Object#hashCode Object.hashCode} will typically not be equal, and will have different hashcodes, 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 {@link #containsValue containsValue} or tocompare map entries.
This class marks itself for update as necessary; no additional calls to the {@link DataManager} are necessary when modifying the map. Developers do notneed to call {@code markForUpdate} or {@code getForUpdate} on this map, asthis will eliminate all the concurrency benefits of this class. However, calling {@code getForUpdate} or {@code markForUpdate} can be used if aoperation needs to prevent all access to the map.
Note that, unlike most collections, the {@code size} and {@code 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 {@code ScalableHashMap} offers one parameter for performancetuning: {@code 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 {@code Serializable} views from the {@link #entrySet entrySet}, {@link #keySet keySet} and {@link #values values} methods. Theseviews may be shared and persisted by multiple {@code ManagedObject}instances.
The {@code Iterator} for each view also implements{@code Serializable}. A single iterator may be saved by different {@code ManagedObject} instances, which will create distinct copies of the originaliterator. 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 {@code Iterator}between multiple {@code ManagedObject} and have the iterator use aconsistent view for each, the iterator should be contained within a shared {@code ManagedObject}.
The iterators do not throw {@link java.util.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 {@code DataManager} will result in an {@code ObjectNotFoundException} being thrown,although the {@link Iterator#remove remove} method may throw {@code IllegalStateException} instead if that is appropriate.
If a call to the {@link Iterator#next next} method on the iterators causesan {@code ObjectNotFoundException} to be thrown because the return value hasbeen removed from the {@code DataManager}, the iterator will still have successfully moved to the next entry in its iteration. In this case, the {@link Iterator#remove remove} method may be called on the iterator toremove the current object even though that object could not be returned.
This class and its iterator implement all optional operations and support both {@code null} keys and values. This map provides no guarantees on theorder of elements when iterating over the key set, values or entry set. @param < K> the type of keys maintained by this map @param < V> the type of mapped values @see Object#hashCode Object.hashCode @see java.util.Map @see Serializable @see ManagedObject
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |