Class COM.odi.util.OSHashtable

java.lang.Object
   |
   +----COM.odi.util.OSDictionary
           |
           +----COM.odi.util.OSHashtable

public class OSHashtable

extends OSDictionary

implements Cloneable, Serializable

Certain operations on OSHashtable that require comparison of objects might cause ObjectStore to throw ReferencedObjectNotFoundException. If this occurs, it indicates that one or more of the key or value objects referenced by the hash table cannot be accessed, most likely because they have been destroyed. The OSHashtable class provides a clearDestroyed() operation that can be used to remove entries that contain these references to these destroyed objects.

You do not need to run the postprocessor on the OSHashtable class. It is already persistence-capable. If you define a subclass that extends OSHashtable and you want the subclass to be persistence-capable, you must either run the postprocessor on the subclass or manually annotate the subclass.

Additional information about OSHashtable is in the user guide. Here are exceptions that might be thrown by many of the methods in this class:

DatabaseNotOpenException If the database containing the object is not open.

NoTransactionInProgressException If there is no transaction in progress.

ObjectNotFoundException If the object was not found, either because the object itself, its segment, or its database was destroyed. ObjectException If the object was local and was fetched in a previous transaction.

ObjectStoreException If the session implied by an argument to the call or the object the method is called on has been terminated or if the current thread is associated with a session other than the session implied by an argument to the call or the object the method is called on.

UpdateReadOnlyException If there is a readonly transaction in progress or if the database is open for readonly.

See Also:

IPersistent, Hashtable

OSHashtable()

Constructs a new persistence-capable hash table.

OSHashtable(ClassInfo)

Constructs a new hollow hash table.

OSHashtable(int)

Constructs a new persistence-capable hash table and allocates internal structures.

OSHashtable(int, boolean)

Constructs a new persistence-capable hash table and can allocate or delay allocating internal structures.

clear()

Removes all entries from the hash table.

clearContents()

Resets the values of the fields of an active persistent object to the default initial values of that class of object.

clearDestroyed()

Removes from the hash table all entries which reference destroyed objects either as a key or value.

clone()

Clones the object.

contains(Object)

Checks whether or not the hash table contains a specified value as an element.

containsKey(Object)

Checks whether or not the hash table contains an element with the specified key and maintains a cache from the OSHashtable object to the element.

containsKey(Object, boolean)

Checks whether or not the hash table contains an element with the specified key and optionally maintains a cache from the OSHashtable object to the element.

containsValue(Object)

Returns true if this Map maps one or more keys to this value.

destroy()

Destroys the hash table in the database.

elements()

Obtains an enumeration of the elements in the hash table.

entries()

Returns a Collection view of the mappings contained in this Map.

flushContents(GenericObject)

Stores the values of the fields of an active persistent object in an instance of GenericObject.

get(Object)

Obtains the element mapped at the specified key and maintains a cache from the OSHashtable object to the element.

get(Object, boolean)

Obtains the element mapped at the specified key and optionally maintains a cache from the OSHashtable object to the element.

getKey(Object)

Returns the actual key stored in the hash table for the key you specify and maintains a cache from the OSHashtable object to the element.

getKey(Object, boolean)

Returns the actual key stored in the hash table for the specified key and optionally maintains a cache from the OSHashtable object to the element.

initializeContents(GenericObject)

Initializes the values of the fields of a hollow persistent object from data contained in an instance of GenericObject.

isEmpty()

Determines whether or not there are any keys in the hash table.

keys()

Returns an enumeration of the keys in the hash table.

keySet()

Returns a Set view of the keys contained in this Map.

put(Object, Object)

Enters the mapping of a key to a value in the hash table.

putAll(Map)

Copies all of the mappings from the specified Map to this Map.

remove(Object)

Removes any existing mapping at the specified key.

removeValue(Object)

Removes the specified value from the hashtable.

size()

Determines the number of keys in the hash table.

toString()

Produces a printable representation of the object.

values()

Returns a Collection view of the values contained in this Map.

  protected OSHashtable(ClassInfo ignored)

Constructs a new hollow hash table. This constructor should be used only for that purpose.

Parameters:

ignored - Only used to distinguish this overloading. The value is not used.

  public OSHashtable(int initialCapacity)

Constructs a new persistence-capable hash table and allocates internal structures.

Parameters:

initialCapacity - The initial expected capacity requirement for the hash table.

  public OSHashtable(int initialCapacity,
                     boolean lazy)

Constructs a new persistence-capable hash table and can allocate or delay allocating internal structures.

Parameters:

initialCapacity - The initial expected capacity requirement for the hash table.

lazy - A true argument delays allocation of the internal structures used to represent the hash table until the first element is added to the hash table. This option helps minimize storage associated with hash tables that are empty. A false argument causes the internal structures to be created immediately; this is the default initial representation used by OSHashtable.

  public OSHashtable()

Constructs a new persistence-capable hash table. A default size is used as the initial hash table capacity.

  public void initializeContents(GenericObject genObject)

Initializes the values of the fields of a hollow persistent object from data contained in an instance of GenericObject. ObjectStore arranges to call this method when an application calls fetch() or dirty() on a persistent object. If you define a subclass of this class, you must define a method that overrides this method and initializes all fields in the hollow persistent object, including any fields defined by superclasses. Initialize superclass fields by invoking initializeContents() on the superclass. This is similar to calls to superclass constructors, although in this case the superclass initialization is not enforced by the compiler.

Parameters:

genObj - The representation of the persistent object that the method should read the field values from.

Overrides:

initializeContents in class OSDictionary

See Also:

initializeContents

  public void flushContents(GenericObject genObject)

Stores the values of the fields of an active persistent object in an instance of GenericObject. ObjectStore arranges to call this method when a modified persistent object is evicted and when a transaction is committed. If you define a subclass of this class, you must define a method that overrides this method and writes all fields, even fields that were not modified.

Parameters:

genObject - The representation of the persistent object that this method should write the field values into.

Overrides:

flushContents in class OSDictionary

See Also:

flushContents

  public void clearContents()

Resets the values of the fields of an active persistent object to the default initial values of that class of object. This causes the object to become a stale persistent object. If you define a subclass of this class, you must define a method that overrides this method and invokes clearContents() on its superclass to ensure that all fields are correctly cleared.

Overrides:

clearContents in class OSDictionary

See Also:

clearContents

  public synchronized void destroy()

Destroys the hash table in the database. The keys and elements in the hash table are unaffected by this operation. If the hash table is persistent, the database must be open for update and there must be an update transaction in progress.

Throws: DatabaseNotOpenException

If the database containing the object is not open.

Throws: NoTransactionInProgressException

If there is no transaction in progress.

Throws: ObjectNotFoundException

If the object was not found, either because the object itself, its segment, or its database was destroyed, or because the object was local and was fetched in a previous transaction.

Throws: ObjectStoreException

If the session implied by the hash table has been terminated or if the current thread is associated with a session other than the session implied by the hash table.

Throws: UpdateReadOnlyException

If there is a read-only transaction in progress or if the database is open read-only.

  public int size()

Determines the number of keys in the hash table.

Returns:

An integer that indicates the number of keys.

Overrides:

size in class OSDictionary

  public boolean isEmpty()

Determines whether or not there are any keys in the hash table.

Returns:

The true constant if there are no keys in the hash table. The false constant if there is at least one key in the hash table.

Overrides:

isEmpty in class OSDictionary

  public synchronized IndexIterator keys()

Returns an enumeration of the keys in the hash table. Note that the enumeration is only guaranteed to be valid for the duration of the current transaction.

Overrides:

keys in class OSDictionary

  public synchronized IndexIterator elements()

Obtains an enumeration of the elements in the hash table. Note that the elements are not necessarily unique and that the enumeration is only guaranteed to be valid for the duration of the current transaction.

Returns:

Enumeration The list of elements in the hash table.

Overrides:

elements in class OSDictionary

  public synchronized boolean contains(Object value)

Checks whether or not the hash table contains a specified value as an element.

Parameters:

value - The element to search for, which must be non-null.

Returns:

The true constant if the element is in the hash table. The false constant if the element is not in the hash table.

Throws: NullPointerException

If value is null.

Throws: ReferencedObjectNotFoundException

If an entry value is not found.

Overrides:

contains in class OSDictionary

  public boolean containsKey(Object key)

Checks whether or not the hash table contains an element with the specified key and maintains a cache from the OSHashtable object to the element. This cache prevents the element from being garbage collected unless the application evicts the entire OSHashtable.

Parameters:

key - The key to search for.

Returns:

The true constant if the hash table contains an element with the specified key. The false constant if the hash table does not.

Throws: NullPointerException

If key is null.

Throws: ReferencedObjectNotFoundException

If an entry key is not found.

Overrides:

containsKey in class OSDictionary

  public synchronized boolean containsKey(Object key,
                                          boolean noCache)

Checks whether or not the hash table contains an element with the specified key and optionally maintains a cache from the OSHashtable object to the element. Normally, the containsKey() method maintains this cache which prevents the element from being garbage collected unless the application evicts the entire OSHashtable.

Parameters:

key - The key to search for.

noCache - If true, the OSHashtable does not maintain a cache to the returned element. This allows the object to be garbage collected. If false, the OSHashtable maintains a cache to the element.

Returns:

The true constant if the hash table contains an element with the specified key. The false constant if the hash table does not.

Throws: NullPointerException

If key is null.

  public Object get(Object key)

Obtains the element mapped at the specified key and maintains a cache from the OSHashtable object to the element. This cache prevents the element from being garbage collected unless the application evicts the entire OSHashtable.

If you prefer to not maintain the cache, invoke get(key, noCache).

Parameters:

key - The key for the element you want to obtain.

Returns:

The element at the key, or null if no such key exists. Since this method does not have to fetch the value, it returns the corresponding value, even if it has been destroyed. To determine whether or not the element has been destroyed, you can call ObjectStore.isDestroyed(value) on the element. This method returns the correct value only when the object has been fetched or destroyed in the current transaction. ObjectStore returns null for a destroyed object only when the destroyed object is a String. In fact, getting a destroyed String from any field returns null - this is not specific to OSHashtable. For other destroyed objects, the destroyed object is returned.

Throws: NullPointerException

If key is null.

Throws: ReferencedObjectNotFoundException

If an entry key is not found.

Overrides:

get in class OSDictionary

  public synchronized Object get(Object key,
                                 boolean noCache)

Obtains the element mapped at the specified key and optionally maintains a cache from the OSHashtable object to the element. Normally, the get() method maintains this cache, which prevents the element from being garbage collected.

There is a potential performance penalty if an application repeatedly invokes get() for the same key without maintaining a cache. This is because there is no caching.

Parameters:

key - The key for the element you want to obtain.

noCache - If true, the OSHashtable does not maintain a cache to the returned element. This allows the object to be garbage collected. If false, the OSHashtable maintains a cache to the element.

Returns:

The element at the key or null if no such key exists or the object that it refers to is destroyed.

Throws: NullPointerException

If key is null.

  public Object getKey(Object key)

Returns the actual key stored in the hash table for the key you specify and maintains a cache from the OSHashtable object to the element. Maintenance of this cache prevents the element from being garbage collected.

Each hash table entry holds a reference to a key object and a value object. The getKey method searches the hash table for an entry whose key object is equal to the value of the key specified as the argument to getKey(). If such a key is found, the method returns the key object itself, which is equal to the key specified in the argument but is not necessarily the very same object. In other words, == would not necessarily return true.

Parameters:

key - The key to search for.

Returns:

The actual key stored in the hash table for the specified key, or null if no such key exists.

Throws: NullPointerException

If key is null.

Throws: ReferencedObjectNotFoundException

If an entry key is not found.

Overrides:

getKey in class OSDictionary

  public synchronized Object getKey(Object key,
                                    boolean noCache)

Returns the actual key stored in the hash table for the specified key and optionally maintains a cache from the OSHashtable object to the element. Normally, the getKey() method maintains this cache, which prevents the element from being garbage collected.

Each hash table entry holds a reference to a key object and a value object. The getKey method searches the hash table for an entry whose key object is equal to the value of the key specified as the argument to getKey(). If such a key is found, the method returns the key object itself, which is equal to the key specified in the argument but is not necessarily the very same object. In other words, == would not necessarily return true.

There is a potential performance penalty if an application repeatedly invokes getKey() for the same key without maintaining a cache. This is because there is no caching.

Parameters:

key - The key to search for.

noCache - If true, the OSHashtable does not maintain a cache to the returned element. This allows the object to be garbage collected. If false, the OSHashtable maintains a cache to the element.

Returns:

The actual key stored in the hash table for the given key, or null if no such key exists.

Throws: NullPointerException

If key is null.

  public synchronized Object put(Object key,
                                 Object value)

Enters the mapping of a key to a value in the hash table.

Parameters:

key - The identifier for the value.

value - The value being stored in the hash table.

Returns:

The object previously mapped at the specified key, or null.

Throws: NullPointerException

If either key or value is null.

Throws: ReferencedObjectNotFoundException

If an entry key is not found.

Overrides:

put in class OSDictionary

  public synchronized Object remove(Object key)

Removes any existing mapping at the specified key.

Parameters:

key - The key of the object to remove.

Returns:

The object previously mapped at the specified key, or null.

Throws: NullPointerException

If key is null.

Throws: ReferencedObjectNotFoundException

If an entry key is not found.

Overrides:

remove in class OSDictionary

  public synchronized boolean removeValue(Object value)

Removes the specified value from the hashtable. If more than one key maps to this element, the first such mapping that is found is removed.

Parameters:

value - The element to search for, which must be nonnull.

Returns:

The true constant if the hash table was changed as a result of this operation (that is, if the value was an element of the hashtable). The false constant if the element is not in the hash table.

Throws: NullPointerException

If value is null.

Throws: ReferencedObjectNotFoundException

If an entry value is not found.

Overrides:

removeValue in class OSDictionary

  public synchronized void clear()

Removes all entries from the hash table.

Overrides:

clear in class OSDictionary

  public synchronized void clearDestroyed()

Removes from the hash table all entries which reference destroyed objects either as a key or value. The current implementation of this method requires that all key, value objects referenced by the OSHashtable be fetched, which may require significant heap space.

Overrides:

clearDestroyed in class OSDictionary

  public synchronized Object clone()

Clones the object.

Returns:

The cloned object.

Overrides:

clone in class OSDictionary

  public synchronized String toString()

Produces a printable representation of the object.

Returns:

A string that represents the object.

Overrides:

toString in class Object

See Also:

toString

  public boolean containsValue(Object value)

Returns true if this Map maps one or more keys to this value. More formally, returns true if and only if this Map contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)).

Parameters:

value - value whose presence in this Map is to be tested.

  public synchronized void putAll(Map m)

Copies all of the mappings from the specified Map to this Map. These mappings will replace any mappings that this Map had for any of the keys currently in the specified Map.

Parameters:

t - Mappings to be stored in this Map.

Throws: ReferencedObjectNotFoundException

an entry key is not found.

Throws: NullPointerException

the specified key or value is null.

  public synchronized Set keySet()

Returns a Set view of the keys contained in this Map. The Set is backed by the Map, so changes to the Map are reflected in the Set, and vice-versa. (If the Map is modified while while an iteration over the Set is in progress, the results of the iteration are undefined.) The Set supports element removal (which removes the corresponding mapping from the Map) via the Iterator.remove, Set.remove, removeAll retainAll, and clear operations. It does not support the add or addAll operations.

Overrides:

keySet in class OSDictionary

  public synchronized Collection values()

Returns a Collection view of the values contained in this Map. The Collection is backed by the Map, so changes to the Map are reflected in the Collection, and vice-versa. (If the Map is modified while while an iteration over the Collection is in progress, the results of the iteration are undefined.) The Collection supports element removal (which removes the corresponding mapping from the Map) via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Overrides:

values in class OSDictionary

  public synchronized Set entries()

Returns a Collection view of the mappings contained in this Map. Each element in this collection is a Map.Entry. The Collection is backed by the Map, so changes to the Map are reflected in the Collection, and vice-versa. (If the Map is modified while while an iteration over the Collection is in progress, the results of the iteration are undefined.) The Collection supports element removal (which removes the corresponding mapping from the Map) via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Overrides:

entries in class OSDictionary