Package ptolemy.kernel.util

Class 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 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

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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.
      Nameable remove​(java.lang.String name)
      Remove an element specified by name.
      void remove​(Nameable element)
      Remove the specified element.
      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

      • 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.

      • 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.