All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Components |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sas.collection
Class SortedCollection

    com.sas.collection.SortedCollection

All Implemented Interfaces:
  com.sas.beans.PropertyChangeSource, com.sas.beans.VetoableChangeSource, CollectionInterface, com.sas.collection.ContentsChangedSource, SortedCollectionInterface, StaticCollectionInterface, StaticOrderedCollectionInterface, ComponentInterface, LinkPropertiesInterface, ModelInterface, com.sas.PublicClonable, com.sas.util.Countable, com.sas.util.Enumerable, com.sas.util.EventGateInterface, IndexedGetInterface, ViewInterface, MultipleValueEventSourceInterface, java.beans.PropertyChangeListener, java.io.ObjectInputValidation, java.io.Serializable, java.lang.Cloneable, java.util.EventListener

    public class SortedCollection

implements SortedCollectionInterface

`SortedCollection` is a collection which inserts items in a sort order defined by a `Comparator`. The sorted collection is constructed with a `Comparator` which is used to determine where new items added to the collection should be placed.

The behavior of a `SortedCollection` is undefined if the Comparator is null or if the comparator cannot compare two items (i.e. if the comparator ever returns `Comparator.INCOMPARABLE`)

See also `TreeMap` and `TreeSet` which provide alternate data structures for storing objects in sorted order.

Sample The example below shows constructing a `SortedCollection` which uses a `StringComparator` to keep the collection of strings sorted. A `BufferedReader` reader is used to read lines of text from a stream. The lines are added to the collection, which keeps them sorted. The enumeration will return the items in sorted order, as does the `get(int)` method.

      import com.sas.collection.SortedCollection;
      import com.sas.util.StringComparator;
      ...
      SortedCollection lines = new SortedCollection(StringComparator.defaultInstance);
      try {
         String line;
         while ( (line = reader.readLine()) != null)
            lines.add(line);
      }
      catch (IOException ioe) { }

      for (int i = 0, len = lines.count(); i < len; i++)
         System.out.println(lines.get(i));

      // Or, use an enumeration:
      for (Enumeration sortedLines = lines.getItems(); sortedLines.hasMoreElements(); )
         System.out.println(sortedLines.nextElement());

Merging Sorted Collections If you have two `SortedCollection`s which you wish to merge, simply call `addItems` on the first, passing an `Enumeration` of the items from the second:

       collection1.addItems(collection2.getItems());

Converting a Sorted Collection into an Ordered Collection If you have two `SortedCollection`s which you wish to convert into an Ordered Collection simply call `addItems` on a new OrderedCollection, passing an `Enumeration` of the items from the second:

       OrderedCollection oc = new OrderedCollection();
       oc.addItems(collection2.getItems());

See Also:
  `SortedCollection`, Serialized Form

Field Summary
`protected com.sas.collection.AVLTree` | `avlTree`
`static java.lang.String` | `RB_KEY`

Fields inherited from class com.sas.collection.BaseCollection
`allContentsChangedListeners, mappingObject`

Constructor Summary
`SortedCollection()` Create a default SortedCollection.
`SortedCollection(com.sas.util.Comparator comparator)` Create a `SortedCollection` which uses the specified comparator to maintain the sort order.
`SortedCollection(com.sas.util.Comparator comparator, boolean allowDuplicates)` Create a `SortedCollection` which uses the specified comparator to maintain the sort order.
`SortedCollection(java.util.Enumeration e, com.sas.util.Comparator comparator, boolean allowDuplicates)` Create a SortedCollection from the contents of an array.
`SortedCollection(java.lang.Object[] array, com.sas.util.Comparator comparator, boolean allowDuplicates)` Create a SortedCollection from the contents of an array.
`SortedCollection(StaticCollectionInterface items, com.sas.util.Comparator comparator, boolean allowDuplicates)` Create a SortedCollection from the contents of an array.
`SortedCollection(java.lang.String data, com.sas.util.Comparator comparator, boolean allowDuplicates)` Construct an `SortedCollection` from a string of comma delimited values

Method Summary
`void` | `add(java.lang.Object item)` Add an item to this collection.
`void` | `addItems(java.util.Enumeration items)` Add all elements of an enumeration to this collection.
`void` | `apply(com.sas.util.ApplyInterface action)` Applies the action to every item in the collection.
`java.lang.Object` | `clone()` Clone the object.
`boolean` | `contains(java.lang.Object element)` Test for the presence of an object in this collection
`int` | `count()` Returns the number of items in the collection
`boolean` | `equals(java.lang.Object object)` Compare to another object.
`boolean` | `equals(StaticOrderedCollectionInterface orderedCollection)` Compare the current items with those in another collection and tell whether the collections are identical.
`java.lang.Object` | `get(int index)` Get a value via an integer index.
`com.sas.util.Comparator` | `getComparator()` Return the comparator used to maintain the sort order.
`static com.sas.beans.ExtendedBeanInfo` | `getExtendedBeanInfo()`
`int` | `getIndex(java.lang.Object element, int startIndex)` Returns the index of the first occurrence of the item.
`java.util.Enumeration` | `getItems()` Return an enumeration of all the elements in this collection
`java.util.Enumeration` | `getItems(int start, int end)` Returns an enumeration of a subset of the items from a collection.
`int` | `getLastIndex(java.lang.Object element, int startIndex)` Returns the index of the last occurrence of the element.
`protected void` | `invalidate()` Marks the SortedCollection as modified -- done after adding or removing items.
`boolean` | `isDuplicatesAllowed()` Return the duplicatesAllowed setting
`protected com.sas.util.Comparator` | `newComparator()` A Factory Method for constructing the comparator.
`boolean` | `remove(java.lang.Object element)` Remove an item from this collection.
`void` | `removeAll()` Remove all items from this collection
`int` | `removeAll(java.lang.Object element)` Remove an all occurrences of an item from this collection.
`void` | `removeAt(int index)` Remove the item at the specificed position.
`void` | `setComparator(com.sas.util.Comparator newComparator)` Set the comparator used to maintain the sort order.
`void` | `setDuplicatesAllowed(boolean duplicatesAllowed)` Specify whether the sorted collection allows duplicates or not
`void` | `sort()` Re-sort the collection.
`java.lang.Object[]` | `toArray()` Return a new array of objects containing the contents of this collection.
`java.lang.String` | `toString()` Convert this ordered collection to a single string.

Methods inherited from class com.sas.collection.BaseCollection
`addContentsChangedListener, anyContentsChangedListeners, disableEvents, enableEvents, enableEvents, fireContentsChanged, map, removeContentsChangedListener, unmap`

Methods inherited from class com.sas.Component
`addLink, addPropertyChangeListener, addVetoableChangeListener, anyPropertyChangeListeners, attachModel, attachView, beansIsDesignTime, beansSetDesignTime, clone, detachModel, detachView, dumpComponent, firePropertyChange, firePropertyChange, fireVetoableChange, getComponentDescription, getComponentSupportInfo, getEventMethod, getEventValues, getLinkInfo, getModelInterface, getRequiredInterfaces, getResources, getStringResource, getViewInterfaceSupportInfo, initialize, initializeComponent, isDesignTime, isLinked, propertyChange, queryLinks, queryLinks, refresh, removeAllLinks, removeInterfaceTraps, removeLink, removePropertyChangeListener, removeVetoableChangeListener, setComponentDescription, setComponentSupportInfo, setDefaultValues, setLinkInfo, setModelInterface, setRequiredInterfaces, setViewInterfaceSupportInfo, supportsListenerInterface, supportsRequiredInterfaces, trapInterfaceEvents, validateObject`

Methods inherited from interface com.sas.collection.ContentsChangedSource
`addContentsChangedListener, removeContentsChangedListener`

Methods inherited from interface com.sas.beans.PropertyChangeSource
`addPropertyChangeListener, removePropertyChangeListener`

Field Detail

### avlTree

    protected com.sas.collection.AVLTree avlTree

### RB_KEY

    public static final java.lang.String RB_KEY

See Also:
  Constant Field Values

Constructor Detail

### SortedCollection

    public SortedCollection()

  Create a default SortedCollection. This will use the comparator returned by `newComparator()`, and allow duplicates.

### SortedCollection

    public SortedCollection(java.lang.Object[] array,
                            com.sas.util.Comparator comparator,
                            boolean allowDuplicates)

  Create a SortedCollection from the contents of an array.

  Parameters:
    `array` - a non-null array of elements.
    `comparator` - the comparator used to maintain the sort order. It is used whenever a new item is added to the collection, or when resorting the collection.
    `allowDuplicates` - if true, the collection allows insertion of duplicate values (i.e. values that are EQUALS according to the comparator. If false, this collection behaves like a sorted set.

### SortedCollection

    public SortedCollection(java.util.Enumeration e,
                            com.sas.util.Comparator comparator,
                            boolean allowDuplicates)

  Create a SortedCollection from the contents of an array.

  Parameters:
    `e` - a non-null enumeration of elements.
    `comparator` - the comparator used to maintain the sort order. It is used whenever a new item is added to the collection, or when resorting the collection.
    `allowDuplicates` - if true, the collection allows insertion of duplicate values (i.e. values that are EQUALS according to the comparator. If false, this collection behaves like a sorted set.

### SortedCollection

    public SortedCollection(StaticCollectionInterface items,
                            com.sas.util.Comparator comparator,
                            boolean allowDuplicates)

  Create a SortedCollection from the contents of an array.

  Parameters:
    `items` - a non-null collection of elements.
    `comparator` - the comparator used to maintain the sort order. It is used whenever a new item is added to the collection, or when resorting the collection.
    `allowDuplicates` - if true, the collection allows insertion of duplicate values (i.e. values that are EQUALS according to the comparator. If false, this collection behaves like a sorted set.

### SortedCollection

    public SortedCollection(java.lang.String data,
                            com.sas.util.Comparator comparator,
                            boolean allowDuplicates)

  Construct an `SortedCollection` from a string of comma delimited values

  Parameters:
    `data` - a string of values, separated by commas. Booleans, character literals and numbers are recognized and parsed into appropriate `java.lang.Boolean, java.lang.Character, java.lang.Integer, java.lang.Long,` or `java.lang.Double` objects (for either the or the value); everything else is parsed into a String.
    `comparator` - the comparator used to maintain the sort order. It is used whenever a new item is added to the collection, or when resorting the collection.
    `allowDuplicates` - if true, the collection allows insertion of duplicate values (i.e. values that are EQUALS according to the comparator. If false, this collection behaves like a sorted set.
  Throws:
    `java.lang.IllegalArgumentException` - if the data string is invalid

### SortedCollection

    public SortedCollection(com.sas.util.Comparator comparator)

  Create a `SortedCollection` which uses the specified comparator to maintain the sort order. The default allows duplicates.

  Parameters:
    `comparator` - the comparator used to maintain the sort order. It is used whenever a new item is added to the collection, or when resorting the collection.

### SortedCollection

    public SortedCollection(com.sas.util.Comparator comparator,
                            boolean allowDuplicates)

  Create a `SortedCollection` which uses the specified comparator to maintain the sort order.

  Parameters:
    `comparator` - the comparator used to maintain the sort order. It is used whenever a new item is added to the collection, or when resorting the collection.
    `allowDuplicates` - if true, the collection allows insertion of duplicate values (i.e. values that are EQUALS according to the comparator. If false, this collection behaves like a sorted set.

Method Detail

### newComparator

    protected com.sas.util.Comparator newComparator()

  A Factory Method for constructing the comparator. This version creates a `GenericComparator`. Subclasses may override this in order to define a different default comparator.

  Returns:
    a comparator that this collection uses to compare items.

### getExtendedBeanInfo

    public static com.sas.beans.ExtendedBeanInfo getExtendedBeanInfo()

### setDuplicatesAllowed

    public void setDuplicatesAllowed(boolean duplicatesAllowed)

  Specify whether the sorted collection allows duplicates or not

  Parameters:
    `duplicatesAllowed` - if true, duplicate values may be added. If false, adding an item that already exists in the collection will fail silently. Duplicates are two items such that the comparator returns EQUALS. Note: if this changes from true to false, the duplicates are removed from the collection.
  See Also:
    `sort()`, `Comparator.EQUALS`

### isDuplicatesAllowed

    public boolean isDuplicatesAllowed()

  Return the duplicatesAllowed setting

  Returns:
    true if duplicate values may be added, else false

### setComparator

    public void setComparator(com.sas.util.Comparator newComparator)

  Set the comparator used to maintain the sort order. Setting the comparator causes the collection to be resorted.

  Parameters:
    `newComparator` - the comparator used to maintain the sort order.
  See Also:
    `sort()`

### getComparator

    public com.sas.util.Comparator getComparator()

  Return the comparator used to maintain the sort order.

  Returns:
    the comparator used to maintain the sort order.

### sort

    public void sort()

  Re-sort the collection. This may be necessary if one or more of the items in the collection have changed in such a way that the collection is out of order. The collection will emit a ContentsChangedEvent.

  Specified by:
    `sort` in interface `SortedCollectionInterface`

### removeAt

    public void removeAt(int index)

  Remove the item at the specificed position. The sorted collection will emit a ContentsChangedEvent.

  Specified by:
    `removeAt` in interface `SortedCollectionInterface`
  Parameters:
    `index` - the index of the item to remove from the sorted collection.

### add

    public void add(java.lang.Object item)

  Add an item to this collection. The item is inserted into the collection according to the sort order defined by the Comparator.

  Specified by:
    `add` in interface `CollectionInterface`
  Parameters:
    `item` - an object to add to this collection.
  Throws:
    `java.lang.ClassCastException` - In some implementations, the objects that are stored may be restricted to a particular type (such as String). (a RuntimeException)

### addItems

    public void addItems(java.util.Enumeration items)

  Add all elements of an enumeration to this collection. Each item is inserted into the collection according to the sort order defined by the Comparator.

  Specified by:
    `addItems` in interface `CollectionInterface`
  Parameters:
    `items` - an Enumeration of items to add to this collection
  Throws:
    `java.lang.ClassCastException` - In some implementations, the objects that are stored may be restricted to a particular type (such as String). (a RuntimeException)

### remove

    public boolean remove(java.lang.Object element)

  Remove an item from this collection. If the element appears multiple times, only the first occurrence is removed.

  Specified by:
    `remove` in interface `CollectionInterface`
  Parameters:
    `element` - the item to remove
  Returns:
    true if item removed, false if not.
  Throws:
    `java.lang.ClassCastException` - In some implementations, the objects that are stored may be restricted to a particular type (such as String). (a RuntimeException)

### removeAll

    public void removeAll()

  Remove all items from this collection

  Specified by:
    `removeAll` in interface `CollectionInterface`

### removeAll

    public int removeAll(java.lang.Object element)

  Remove an all occurrences of an item from this collection.

  Specified by:
    `removeAll` in interface `CollectionInterface`
  Parameters:
    `element` - the item to remove
  Returns:
    the number of times the element occurred in this collection.

### equals

    public boolean equals(StaticOrderedCollectionInterface orderedCollection)

  Compare the current items with those in another collection and tell whether the collections are identical. The ``equals()`` method is used to compare collection items.

  Specified by:
    `equals` in interface `StaticOrderedCollectionInterface`
  Parameters:
    `orderedCollection` - Another ordered collection to be compared to.
  Returns:
    true if this collection has the same size and same elements as the other collection, false otherwise.

### equals

    public boolean equals(java.lang.Object object)

  Compare to another object.

  Overrides:
    `equals` in class `java.lang.Object`
  Parameters:
    `object` - another object
  Returns:
    if the other object implements `StaticOrderedCollectionInterface`, return `equals((StaticOrderedCollectionInterface) other)`, else return false

### getIndex

    public int getIndex(java.lang.Object element,
                        int startIndex)

  Returns the index of the first occurrence of the item. The comparator is used to find items which equals the object

  Specified by:
    `getIndex` in interface `StaticOrderedCollectionInterface`
  Parameters:
    `element` - item to search for
    `startIndex` - the position where the search should start
  Returns:
    the zero-based index where the list item was first found, or -1 if the item is not found.
  Throws:
    `java.lang.IndexOutOfBoundsException` - if the index is not in the range `[0..count()-1]`.
    `java.lang.ClassCastException` - In some implementations, the objects that are stored may be restricted to a particular type (such as String).

### getItems

    public java.util.Enumeration getItems(int start,
                                          int end)

  Returns an enumeration of a subset of the items from a collection.

  Specified by:
    `getItems` in interface `StaticOrderedCollectionInterface`
  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, or -1 to indicate the enumeration should include all remaining elements. Note that the range of elements returned in the Enumeration does not include the end item; this is consistent with ``String.substring(start, end)`` for example.
  Returns:
    an enumeration of the requested elements.
  Throws:
    `java.lang.IndexOutOfBoundsException` - if start is not in the range `[0, count()-1]`, or start > last or end is not in the range `[0, count()]`

### getLastIndex

    public int getLastIndex(java.lang.Object element,
                            int startIndex)

  Returns the index of the last occurrence of the element. The search proceeds from the end of the list (at `index == count()-1`) to the start of the list until an item is found.

  Specified by:
    `getLastIndex` in interface `StaticOrderedCollectionInterface`
  Parameters:
    `element` - the item to search for
    `startIndex` - the position where the search should start
  Returns:
    the zero-based index of the last item matching element, or -1 if the item is not found.
  Throws:
    `java.lang.IndexOutOfBoundsException` - if the index is not in the range [0..count()-1]
    `java.lang.ClassCastException` - In some implementations, the objects that are stored may be restricted to a particular type (such as String). (a RuntimeException)

### apply

    public void apply(com.sas.util.ApplyInterface action)

  Applies the action to every item in the collection. This is a general way to modify all the items in a collection. The collection does not monitor the items in the collection. If the action modifies the items in such a manner as to invalidate the sort relation, you should `sort()` this collection.

  Specified by:
    `apply` in interface `StaticCollectionInterface`
  Overrides:
    `apply` in class `BaseCollection`
  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 values in this collection until all values have been operated on, or until the method returns `ApplyInterface.ABORT`

### contains

    public boolean contains(java.lang.Object element)

  Test for the presence of an object in this collection

  Specified by:
    `contains` in interface `StaticCollectionInterface`
  Overrides:
    `contains` in class `BaseCollection`
  Parameters:
    `element` - the item to search for
  Returns:
    True if and only if the item exists
  Throws:
    `java.lang.ClassCastException` - In some implementations, the objects that are stored may be restricted to a particular type (such as String). (a RuntimeException)
  See Also:
    `StaticCollectionInterface.contains(java.lang.Object)`

### clone

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

  Clone the object.

  Specified by:
    `clone` in interface `CollectionInterface`
  Specified by:
    `clone` in interface `StaticCollectionInterface`
  Specified by:
    `clone` in interface `StaticOrderedCollectionInterface`
  Specified by:
    `clone` in interface `com.sas.PublicClonable`
  Overrides:
    `clone` in class `BaseCollection`
  Returns:
    a clone of this collection.
  Throws:
    `java.lang.CloneNotSupportedException` - if the clone fails.

### invalidate

    protected void invalidate()

  Marks the SortedCollection as modified -- done after adding or removing items. It is necessary to call invalidate() after each changed in order to keep the get(int) method working corrctly and efficiently. The existing methods in com.sas.collection.SortedCollection call invalidate when necessary. Any new methods added in a subclass should call invalidate if they modify the collection in some way other than the existing methods.

### get

    public java.lang.Object get(int index)

  Get a value via an integer index. This is like an array reference.

  Specified by:
    `get` in interface `IndexedGetInterface`
  Parameters:
    `index` - the index of the item to fetch.
  Returns:
    Object the object associated with the index.
  Throws:
    `java.lang.IndexOutOfBoundsException` - The implementor of this interface may throw this RuntimeException if the index is not valid.

### count

    public int count()

  Returns the number of items in the collection

  Specified by:
    `count` in interface `com.sas.util.Countable`
  Specified by:
    `count` in class `BaseCollection`
  Returns:
    the number of items in the collection

### getItems

    public java.util.Enumeration getItems()

  Description copied from class: `BaseCollection`
  Return an enumeration of all the elements in this collection

  Specified by:
    `getItems` in interface `com.sas.util.Enumerable`
  Specified by:
    `getItems` in class `BaseCollection`
  Returns:
    an enumeration of the items. If the specific collection does not support enumerations, the getItems() method returns null. An empty collection still returns an Enumeration, but the first call to `hasMoreElements()` returns false.
  See Also:
    `Enumerable.getItems()`

### toString

    public java.lang.String toString()

  Convert this ordered collection to a single string.

  Overrides:
    `toString` in class `java.lang.Object`
  Returns:
    a string consisting of the comma separated values in this collection

### toArray

    public java.lang.Object[] toArray()

  Return a new array of objects containing the contents of this collection.

  Returns:
    an Object array; the array length will be count(). May contain `null` items. The array may have 0 length if this collection is empty.

All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Components |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2009 SAS Institute Inc. All Rights Reserved.