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$

Author:

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

See Also:

Nameable, Serialized Form

Pt.AcceptedRating:

Green (cxh)

Pt.ProposedRating:

Green (eal)

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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.
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.
java.lang.String	toString() Return a string description of the list.

Methods inherited from class java.lang.Object

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

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

@Deprecated
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.

toString

public java.lang.String toString()

Return a string description of the list.

Overrides:

toString in class java.lang.Object

Returns:

A string description of the list.