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