ptolemy.kernel.util
Class NamedList

java.lang.Object
  ptolemy.kernel.util.NamedList

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public final class NamedList
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

An ordered list of objects with names. The objects must implement the Nameable interface. The names are required to be unique and non-null.

This class is biased towards sequential accesses. If it is used with name lookups, the list should be small. It is implemented as a linked list rather than hash table to preserve ordering information, and thus would not provide efficient name lookup for large lists. Also, it permits the name of an object in the list to change without this list being informed.

An instance of this class may have a container, but that container is only used for error reporting.

Since:

Ptolemy II 0.2

Version:

$Id: NamedList.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Mudit Goel, Edward A. Lee, Contributor: Jason E. Smith

See Also:

Nameable, Serialized Form

Accepted Rating:

Green (cxh)

Proposed Rating:

Green (eal)

Field Summary

private Nameable	_container
private java.util.HashMap<java.lang.String,Nameable>	_hashedList
private boolean	_hashEnabled
private java.util.LinkedList<Nameable>	_namedList
private static java.lang.String	_NULL_NAME_EXCEPTION_STRING
private static int	_threshhold

Constructor Summary

NamedList()
Construct an empty NamedList with no container.

NamedList(Nameable container)
Construct an empty list with a Nameable container.

NamedList(NamedList original)
Copy constructor.

Method Summary

private int	_getIndexOf(java.lang.String name)
private void	_insertAt(int index, Nameable element)
void	append(Nameable element) Add an element to the end of the list.
java.lang.Object	clone() Build an independent copy of the list.
java.util.List	elementList() Return an unmodifiable list with the contents of this named list.
java.util.Enumeration	elements() Deprecated. Use elementList() instead.
private void	enableHash()
Nameable	first() Get the first element.
Nameable	get(java.lang.String name) Get an element by name.
boolean	includes(Nameable element) Return true if the specified object is on the list.
void	insertAfter(java.lang.String name, Nameable element) Insert a new element after the specified element.
void	insertBefore(java.lang.String name, Nameable element) Insert a new element before the specified element.
Nameable	last() Get the last element.
int	moveDown(Nameable element) Move the specified element down by one in the list.
int	moveToFirst(Nameable element) Move the specified element to the beginning of the list.
int	moveToIndex(Nameable element, int index) Move the specified element to the specified position in the list.
int	moveToLast(Nameable element) Move the specified element to the end of the list.
int	moveUp(Nameable element) Move the specified element up by one in the list.
void	prepend(Nameable element) Add an element to the beginning of the list.
void	remove(Nameable element) Remove the specified element.
Nameable	remove(java.lang.String name) Remove an element specified by name.
void	removeAll() Remove all elements from the list.
int	size() Return the number of elements in the list.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_container

private Nameable _container

_threshhold

private static final int _threshhold

See Also:

Constant Field Values

_namedList

private java.util.LinkedList<Nameable> _namedList

_hashedList

private java.util.HashMap<java.lang.String,Nameable> _hashedList

_hashEnabled

private boolean _hashEnabled

_NULL_NAME_EXCEPTION_STRING

private static final java.lang.String _NULL_NAME_EXCEPTION_STRING

See Also:

Constant Field Values

Constructor Detail

NamedList

public NamedList()

Construct an empty NamedList with no container.

NamedList

public NamedList(Nameable container)

Construct an empty list with a Nameable container.

Parameters:

container - The container (for error reporting).

NamedList

public NamedList(NamedList original)

Copy constructor. Create a copy of the specified list, but with no container. This is useful to permit enumerations over a list while the list continues to be modified. If the argument list is null, then the resulting copy will be an empty named list.

Parameters:

original - The list to copy.

Method Detail

append

public void append(Nameable element)
            throws IllegalActionException,
                   NameDuplicationException

Add an element to the end of the list. The element is required to have a name that does not coincide with that of an element already on the list.

Parameters:

element - Element to be added to the list.

Throws:

IllegalActionException - If the argument has no name.

NameDuplicationException - If the name coincides with an element already on the list.

clone

public java.lang.Object clone()

Build an independent copy of the list. The elements themselves are not cloned.

Overrides:

clone in class java.lang.Object

Returns:

A new instance of NamedList.

elementList

public java.util.List elementList()

Return an unmodifiable list with the contents of this named list.

Returns:

A list of Nameable objects.

elements

public java.util.Enumeration elements()

Deprecated. Use elementList() instead.

Enumerate the elements of the list.

Returns:

An enumeration of Nameable objects.

first

public Nameable first()
               throws java.util.NoSuchElementException

Get the first element.

Returns:

The specified element.

Throws:

java.util.NoSuchElementException - If the list is empty.

get

public Nameable get(java.lang.String name)

Get an element by name.

Parameters:

name - The name of the desired element.

Returns:

The requested element if it is found, and null otherwise.

includes

public boolean includes(Nameable element)

Return true if the specified object is on the list.

Parameters:

element - Element to be searched for in the list.

Returns:

A boolean indicating whether the element is on the list.

insertAfter

public void insertAfter(java.lang.String name,
                        Nameable element)
                 throws IllegalActionException,
                        NameDuplicationException

Insert a new element after the specified element. If there is no such element, then append the new element to the end of the list.

Parameters:

name - The element after which to insert the new element.

element - The element to insert.

Throws:

IllegalActionException - If the element to insert has no name.

NameDuplicationException - If the element to insert has a name that coincides with one already on the list.

insertBefore

public void insertBefore(java.lang.String name,
                         Nameable element)
                  throws IllegalActionException,
                         NameDuplicationException

Insert a new element before the specified element. If there is no such element, then the insert the new element at the beginning of the list.

Parameters:

name - The element before which to insert the new element.

element - The element to insert.

Throws:

IllegalActionException - If the element to insert has no name.

NameDuplicationException - If the element to insert has a name that coincides with one already on the list.

last

public Nameable last()
              throws java.util.NoSuchElementException

Get the last element.

Returns:

The last element.

Throws:

java.util.NoSuchElementException - If the list is empty.

moveDown

public int moveDown(Nameable element)
             throws IllegalActionException

Move the specified element down by one in the list. If the specified element is not in the list, then throw an exception. If the element is already at the end of the list, the leave it where it is.

Parameters:

element - Element to move down in the list.

Returns:

The index of the specified object prior to moving it, or -1 if it was not moved (it is already last).

Throws:

IllegalActionException - If the argument is not on the list.

moveToFirst

public int moveToFirst(Nameable element)
                throws IllegalActionException

Move the specified element to the beginning of the list. If the specified element is not in the list, then throw an exception.

Parameters:

element - Element to move to the top of the list.

Returns:

The index of the specified object prior to moving it, or -1 if it was not moved (it is already first).

Throws:

IllegalActionException - If the argument is not on the list.

moveToIndex

public int moveToIndex(Nameable element,
                       int index)
                throws IllegalActionException

Move the specified element to the specified position in the list. If the specified element is not in the list, then throw an exception.

Parameters:

element - Element to move.

index - The position to which to move it.

Returns:

The index of the specified object prior to moving it, or -1 if it was not moved (it is already at the specified position).

Throws:

IllegalActionException - If the argument is not on the list, or if the specified position is out of range.

moveToLast

public int moveToLast(Nameable element)
               throws IllegalActionException

Move the specified element to the end of the list. If the specified element is not in the list, then throw an exception.

Parameters:

element - Element to move to the end of the list.

Returns:

The index of the specified object prior to moving it, or -1 if it was not moved (it is already last).

Throws:

IllegalActionException - If the argument is not on the list.

moveUp

public int moveUp(Nameable element)
           throws IllegalActionException

Move the specified element up by one in the list. If the specified element is not in the list, then throw an exception.

Parameters:

element - Element to move up in the list.

Returns:

The index of the specified object prior to moving it, or -1 if it was not moved (it is already first).

Throws:

IllegalActionException - If the argument is not on the list.

prepend

public void prepend(Nameable element)
             throws IllegalActionException,
                    NameDuplicationException

Add an element to the beginning of the list. The element is required to have a name that does not coincide with that of an element already on the list.

Parameters:

element - Element to be added to the list.

Throws:

IllegalActionException - If the argument is not on the list.

IllegalActionException - If the argument has no name.

NameDuplicationException - If the name coincides with an element already on the list.

remove

public void remove(Nameable element)

Remove the specified element. If the element is not on the list, do nothing.

Parameters:

element - Element to be removed.

remove

public Nameable remove(java.lang.String name)

Remove an element specified by name. If no such element exists on the list, do nothing.

Parameters:

name - Name of the element to be removed.

Returns:

A reference to the removed object, or null if no object with the specified name is found.

removeAll

public void removeAll()

Remove all elements from the list.

size

public int size()

Return the number of elements in the list.

Returns:

A non-negative integer.

_getIndexOf

private int _getIndexOf(java.lang.String name)

_insertAt

private void _insertAt(int index,
                       Nameable element)
                throws IllegalActionException,
                       NameDuplicationException

Throws:

IllegalActionException

NameDuplicationException

enableHash

private void enableHash()