com.sas.collection
Interface AssociationListInterface

All Superinterfaces:

CollectionInterface, ContentsChangedSource, Countable, DictionaryInterface, Enumerable, IndexedGetInterface, IndexedSetInterface, OrderedCollectionInterface, com.sas.beans.PropertyChangeSource, PublicClonable, Sortable, StaticCollectionInterface, StaticDictionaryInterface, StaticOrderedCollectionInterface

All Known Implementing Classes:

AssociationList

public interface AssociationListInterface

extends OrderedCollectionInterface, DictionaryInterface

AssociationListInterface combines the OrderedCollection interface and the DictionaryInterface interface, yielding a collection whose items may be accessed by either an index or a key. Items may be added in order or by an object key, or both. Items added by just key and not index are added to the end of the list. The items and keys Enumerations return items in the implicit order. Since this interface implements the collection interface, key/value pairs may be added multiple times. There is an ordered collection bias to this object; it's treated as an ordered collection that supports keys, rather than a dictionary that supports ordering.

Method Summary

void	add(int index, Object key, Object item) Add an item into this association list at the specified index.
void	applyToPairs(ApplyInterface action) Applies an action to all key/value pairs in the association list.
Object	clone() Clone the object.
Object	get(Object key, int index) Fetch the item corresponding to a key, starting at a specific location.
Object	getKey(int index) Get the key corresponding to a position.
Object	getKey(Object item, int start) Get the key corresponding to an item.
Enumeration	getPairs() Returns an enumeration of all the key/value pairs from an association list.
Enumeration	getPairs(int start, int end) Returns an enumeration of the key/value item pairs from an association list.
void	removeAllAt(Object key) Remove all items with the specified key.
void	set(int index, Object key, Object item) Put an item into this association list, replacing a previous item that was there by the same index/key (although such behavior is defined by the implementation).
void	setKey(int index, Object key) Set the key corresponding to a position.

Methods inherited from interface com.sas.collection.OrderedCollectionInterface

add, addItems, removeAt, set, setSize

Methods inherited from interface com.sas.collection.CollectionInterface

add, addItems, remove, removeAll, removeAll

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

Methods inherited from interface com.sas.collection.StaticOrderedCollectionInterface

equals, getIndex, getItems, getLastIndex

Methods inherited from interface com.sas.util.IndexedGetInterface

get

Methods inherited from interface com.sas.collection.Sortable

sort, sort

Methods inherited from interface com.sas.collection.DictionaryInterface

remove, removeAt, set

Methods inherited from interface com.sas.collection.StaticDictionaryInterface

containsKey, get, getKey, getKeys, getKeys

Method Detail

getPairs

public Enumeration getPairs()

Returns an enumeration of all the key/value pairs from an association list.

Returns:

an enumeration of Pair objects. This is a convenience for getPairs(0, count()) In each returned Pair, pair.getFirst() is the key; pair.getSecond() is the value

getPairs

public Enumeration getPairs(int start,
                            int end)

Returns an enumeration of the key/value item pairs from an association list.

Parameters:

start - the index of the first item, zero based.

end - one past the index of the last item to include in the enumeration, zero based.

Returns:

an enumeration of Pair objects of the requested elements. In each returned Pair, pair.getFirst() is the key; pair.getSecond() is the value

Throws:

IndexOutOfBoundsException - if start is not in the range [0, count()-1], or start >last or end is not in the range [0, count()]

See Also:

Pair

applyToPairs

public void applyToPairs(ApplyInterface action)

Applies an action to all key/value pairs in the association list.

Parameters:

action - An object that provides a function which takes an object as an argument and then does something to it. action.apply(pair) is excecuted on successive key/value pairs until all pairs in the this association list have been operated on, or until the method returns ApplyInterface.ABORT

See Also:

Pair

set

public void set(int index,
                Object key,
                Object item)

Put an item into this association list, replacing a previous item that was there by the same index/key (although such behavior is defined by the implementation).

Parameters:

index - where in the implicit order to store the item.

key - the key by which the item may be retrieved later.

item - the value to put into this association list

add

public void add(int index,
                Object key,
                Object item)

Add an item into this association list at the specified index. The item and key will be available via get(index) and getKey(index)

Parameters:

index - where in the implicit order to insert the item.

key - the key by which the item may be retrieved later.

item - the value to put into this association list

getKey

public Object getKey(Object item,
                     int start)

Get the key corresponding to an item. Note that an association list 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 association list, or the first one as found in the getItems() enumeration).

Parameters:

item - the item whose key you wish to find.

start - the index of where to start searching

Returns:

the key for the item, or null if the item is not found.

getKey

public Object getKey(int index)

Get the key corresponding to a position.

Parameters:

index - return the key corresponding to this index

Returns:

the key found at the specified index

Throws:

IndexOutOfBoundsException - if index is not in the range [0, count()-1]

setKey

public void setKey(int index,
                   Object key)

Set the key corresponding to a position.

Parameters:

index - replace the key at this index

key - the new key

Throws:

IndexOutOfBoundsException - if index is not in the range [0, count()-1]

get

public Object get(Object key,
                  int index)

Fetch the item corresponding to a key, starting at a specific location.

Parameters:

key - the Object key with which the item was added to this association list

index - start searching for the key at this index

Returns:

the item in this association list which corresponds to the given key. There may be only one item per key.

Throws:

NoSuchElementException - when there is no entry for the specified key. (Note that null is a valid value for a key.)

IndexOutOfBoundsException - if if the index is invalid

See Also:

StaticDictionaryInterface.get(java.lang.Object), IndexedGetInterface.get(int)

removeAllAt

public void removeAllAt(Object key)

Remove all items with the specified key.

Parameters:

key - remove all items with this key.

clone

public Object clone()
             throws CloneNotSupportedException

Clone the object.

Specified by:

clone in interface OrderedCollectionInterface

Returns:

a clone of this association list.

Throws:

CloneNotSupportedException - if the object could not be cloned.