ptolemy.backtrack.util.java.util

Interface Map

All Superinterfaces:

Rollbackable

All Known Subinterfaces:

SortedMap

All Known Implementing Classes:

AbstractMap, HashMap, Hashtable, LinkedHashMap, TreeMap, WeakHashMap

public interface Map
extends Rollbackable

An object that maps keys onto values. Keys cannot be duplicated. This interface replaces the obsolete {

Since:

1.2

Author:

Original author unknown, Eric Blake (ebb9@email.byu.edu)

See Also:

HashMap, TreeMap, Hashtable, SortedMap, Collection, Set

Status

updated to 1.4

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Map.Entry A map entry (key-value pair).

Method Summary

Modifier and Type	Method and Description
void	$COMMIT(long timestamp) Commit changes up to the given timestamp, but not including changes made at timestamp and afterward.
Checkpoint	$GET$CHECKPOINT() Get the checkpoint object that monitors this rollbackable object.
void	$RESTORE(long timestamp, boolean trim) Restore a previous state to all the private fields of this rollbackable object.
java.lang.Object	$SET$CHECKPOINT(Checkpoint checkpoint) Set the checkpoint object of this rollbackable object.
void	clear() Remove all entries from this Map (optional operation).
boolean	containsKey(java.lang.Object key) Returns true if this contains a mapping for the given key.
boolean	containsValue(java.lang.Object value) Returns true if this contains at least one mapping with the given value.
Set	entrySet() Returns a set view of the mappings in this Map.
boolean	equals(java.lang.Object o) Compares the specified object with this map for equality.
java.lang.Object	get(java.lang.Object key) Returns the value mapped by the given key.
int	hashCode() Returns the hash code for this map.
boolean	isEmpty() Returns true if the map contains no mappings.
Set	keySet() Returns a set view of the keys in this Map.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Associates the given key to the given value (optional operation).
void	putAll(Map m) Copies all entries of the given map to this one (optional operation).
java.lang.Object	remove(java.lang.Object key) Removes the mapping for this key if present (optional operation).
int	size() Returns the number of key-value mappings in the map.
Collection	values() Returns a collection (or bag) view of the values in this Map.

Method Detail

clear

void clear()

Remove all entries from this Map (optional operation).

Throws:

java.lang.UnsupportedOperationException - if clear is not supported

containsKey

boolean containsKey(java.lang.Object key)

Returns true if this contains a mapping for the given key.

Parameters:

key - the key to search for

Returns:

true if the map contains the key

Throws:

java.lang.ClassCastException - if the key is of an inappropriate type

java.lang.NullPointerException - if key is null but the map does not permit null keys

containsValue

boolean containsValue(java.lang.Object value)

Returns true if this contains at least one mapping with the given value. In other words, returns true if a value v exists where (value == null ? v == null : value.equals(v)). This usually requires linear time.

Parameters:

value - the value to search for

Returns:

true if the map contains the value

Throws:

java.lang.ClassCastException - if the type of the value is not a valid type for this map.

java.lang.NullPointerException - if the value is null and the map doesn't support null values.

entrySet

Set entrySet()

Returns a set view of the mappings in this Map. Each element in the set is a Map.Entry. The set is backed by the map, so that changes in one show up in the other. Modifications made while an iterator is in progress cause undefined behavior. If the set supports removal, these methods remove the underlying mapping from the map: Iterator.remove, Set.remove, removeAll, retainAll, and clear. Element addition, via add or addAll, is not supported via this set.

Returns:

the set view of all mapping entries

See Also:

Map.Entry

equals

boolean equals(java.lang.Object o)

Compares the specified object with this map for equality. Returns true if the other object is a Map with the same mappings, that is,
o instanceof Map && entrySet().equals(((Map) o).entrySet(); This allows comparison of maps, regardless of implementation.

Overrides:

equals in class java.lang.Object

Parameters:

o - the object to be compared

Returns:

true if the object equals this map

See Also:

Set.equals(Object)

get

java.lang.Object get(java.lang.Object key)

Returns the value mapped by the given key. Returns null if there is no mapping. However, in Maps that accept null values, you must rely on containsKey to determine if a mapping exists.

Parameters:

key - the key to look up

Returns:

the value associated with the key, or null if key not in map

Throws:

java.lang.ClassCastException - if the key is an inappropriate type

java.lang.NullPointerException - if this map does not accept null keys

See Also:

containsKey(Object)

put

java.lang.Object put(java.lang.Object key,
                     java.lang.Object value)

Associates the given key to the given value (optional operation). If the map already contains the key, its value is replaced. Be aware that in a map that permits null values, a null return does not always imply that the mapping was created.

Parameters:

key - the key to map

value - the value to be mapped

Returns:

the previous value of the key, or null if there was no mapping

Throws:

java.lang.UnsupportedOperationException - if the operation is not supported

java.lang.ClassCastException - if the key or value is of the wrong type

java.lang.IllegalArgumentException - if something about this key or value prevents it from existing in this map

java.lang.NullPointerException - if either the key or the value is null, and the map forbids null keys or values

See Also:

containsKey(Object)

hashCode

int hashCode()

Returns the hash code for this map. This is the sum of all hashcodes for each Map.Entry object in entrySet. This allows comparison of maps, regardless of implementation, and satisfies the contract of Object.hashCode.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code

See Also:

Map.Entry.hashCode()

isEmpty

boolean isEmpty()

Returns true if the map contains no mappings.

Returns:

true if the map is empty

keySet

Set keySet()

Returns a set view of the keys in this Map. The set is backed by the map, so that changes in one show up in the other. Modifications made while an iterator is in progress cause undefined behavior. If the set supports removal, these methods remove the underlying mapping from the map: Iterator.remove, Set.remove, removeAll, retainAll, and clear. Element addition, via add or addAll, is not supported via this set.

Returns:

the set view of all keys

putAll

void putAll(Map m)

Copies all entries of the given map to this one (optional operation). If the map already contains a key, its value is replaced.

Parameters:

m - the mapping to load into this map

Throws:

java.lang.UnsupportedOperationException - if the operation is not supported

java.lang.ClassCastException - if a key or value is of the wrong type

java.lang.IllegalArgumentException - if something about a key or value prevents it from existing in this map

java.lang.NullPointerException - if the map forbids null keys or values, or if m is null.

See Also:

put(Object, Object)

remove

java.lang.Object remove(java.lang.Object key)

Removes the mapping for this key if present (optional operation). If the key is not present, this returns null. Note that maps which permit null values may also return null if the key was removed.

Parameters:

key - the key to remove

Returns:

the value the key mapped to, or null if not present.

Throws:

java.lang.UnsupportedOperationException - if deletion is unsupported

java.lang.NullPointerException - if the key is null and this map doesn't support null keys.

java.lang.ClassCastException - if the type of the key is not a valid type for this map.

size

int size()

Returns the number of key-value mappings in the map. If there are more than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE.

Returns:

the number of mappings

values

Collection values()

Returns a collection (or bag) view of the values in this Map. The collection is backed by the map, so that changes in one show up in the other. Modifications made while an iterator is in progress cause undefined behavior. If the collection supports removal, these methods remove the underlying mapping from the map: Iterator.remove, Collection.remove, removeAll, retainAll, and clear. Element addition, via add or addAll, is not supported via this collection.

Returns:

the collection view of all values

$COMMIT

void $COMMIT(long timestamp)

Description copied from interface: Rollbackable

Commit changes up to the given timestamp, but not including changes made at timestamp and afterward.

Specified by:

$COMMIT in interface Rollbackable

Parameters:

timestamp - The timestamp.

$RESTORE

void $RESTORE(long timestamp,
              boolean trim)

Description copied from interface: Rollbackable

Restore a previous state to all the private fields of this rollbackable object.

Specified by:

$RESTORE in interface Rollbackable

Parameters:

timestamp - The timestamp taken at the time when the previous state was recorded.

trim - Whether to delete the records used for the rollback.

See Also:

Checkpoint.rollback(long, boolean)

$GET$CHECKPOINT

Checkpoint $GET$CHECKPOINT()

Description copied from interface: Rollbackable

Get the checkpoint object that monitors this rollbackable object.

Specified by:

$GET$CHECKPOINT in interface Rollbackable

Returns:

The checkpoint object.

$SET$CHECKPOINT

java.lang.Object $SET$CHECKPOINT(Checkpoint checkpoint)

Description copied from interface: Rollbackable

Set the checkpoint object of this rollbackable object. A merge operation is performed on the current checkpoint object and the new checkpoint object, so that the two checkpoint objects monitor the same set of objects when this function returns.

Specified by:

$SET$CHECKPOINT in interface Rollbackable

Parameters:

checkpoint - The new checkpoint object.

Returns:

This rollbackable object itself.

See Also:

Checkpoint.setCheckpoint(Checkpoint)