com.sas.collection
Interface StaticDictionaryInterface

All Superinterfaces:

java.lang.Cloneable, com.sas.collection.ContentsChangedSource, com.sas.util.Countable, com.sas.util.Enumerable, com.sas.beans.PropertyChangeSource, com.sas.PublicClonable, StaticCollectionInterface

All Known Subinterfaces:

AssociationListInterface, DictionaryInterface

All Known Implementing Classes:

AssociationList, ColorNameList, Dictionary, RGBList, StaticDictionary

public interface StaticDictionaryInterface
extends StaticCollectionInterface

A static dictionary interface, for objects which retrieve values by an Object key. This interface defines read-only access to a dictionary. You can count the number of items; obtain enumerations of the keys or values; or test if the dictionary contains a key or value.

A Dictionary is like a Hashtable (which extends the abstract Dictionary class) but has some differences. A com.sas.collection.Dictionary can have null values for either the keys or the values. This implies that simply testing the result of a get call for null

 Object value = dictionary.get(myKey);
 if (value != null)
    // assume the key exists...
 

will not work for com.sas.collection dictionaries (because if it returned null, there would be no way to know if the null was the value associated with the key, or if the null meant no such value exists.) The get method will throw a NoSuchElementException if there is no corresponding item for the key you specify. Instead, you must first test if the dictionary contains the item:

 if ( dictionary.containsKey(myKey) )
 {
    Obect value = dictionary.get(myKey);
    // and so on
 }
 

See Also:

Dictionary, StaticDictionary, AssociationList

Method Summary

abstract java.lang.Object	clone() Clone the object.
abstract boolean	containsKey(java.lang.Object key) Test the existence of an key in a dictionary.
abstract java.lang.Object	get(java.lang.Object key) Fetch the item corresponding to a key.
abstract java.lang.Object	getKey(java.lang.Object item) Get the key corrsponding to an item.
abstract java.util.Enumeration	getKeys() Return an enumeration of all the keys.
abstract java.util.Enumeration	getKeys(java.lang.Object item) Return an enumeration of all the keys for a given item.

Methods inherited from interface com.sas.collection.StaticCollectionInterface

apply, contains

Methods inherited from interface com.sas.collection.ContentsChangedSource

addContentsChangedListener, removeContentsChangedListener

Methods inherited from interface com.sas.beans.PropertyChangeSource

addPropertyChangeListener, removePropertyChangeListener

Methods inherited from interface com.sas.util.Countable

count

Methods inherited from interface com.sas.util.Enumerable

getItems

Method Detail

containsKey

boolean containsKey(java.lang.Object key)

Test the existence of an key in a dictionary.

Parameters:

key - the key to search for

Returns:

true if and only if an item with the specified key exists in this dictionary.

get

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

Fetch the item corresponding to a key.

Parameters:

key - the Object key with which the item was inserted.

Returns:

the item in this dictionary which corresponds to the given key. A value of null does not mean the item was not found; instead it means an item exists corresponding to the key, but the value associated with the key was null.

Throws:

java.util.NoSuchElementException - when there is no item for the specified key. (Note that null is a valid value for a key or a value.)

getKey

java.lang.Object getKey(java.lang.Object item)

Get the key corrsponding to an item. Note that a dictionary may contain the same item via multiple keys. If so, this method returns one, but the interface does not specify which one (i.e. it does not have to be the first one entered in this dictionary, or the first one as found in the elements() enumeration.

Parameters:

item - the item whose key you wish to find.

Returns:

a key that maps to the item value. Note that the returned key may be null; this does not mean there is no key for the item, just that the item's key was actually null.

Throws:

java.util.NoSuchElementException - if the item was not found

getKeys

java.util.Enumeration getKeys(java.lang.Object item)

Return an enumeration of all the keys for a given item. The order is unspecified. If the item does not exist, an empty enumeration is returned. Note that this is typically an expensive operation.

Parameters:

item - the item to search for

Returns:

an Enumeration of the keys corresponding to the item.

getKeys

java.util.Enumeration getKeys()

Return an enumeration of all the keys.

Returns:

an Enumeration of this dictionary's keys.

clone

java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clone the object.

Specified by:

clone in interface com.sas.PublicClonable

Specified by:

clone in interface StaticCollectionInterface

Returns:

a clone of this dictionary.

Throws:

java.lang.CloneNotSupportedException - if the object could not be cloned.