org.xshare.base.collections
Class SortedCollection

java.lang.Object
  |
  +--org.xshare.base.collections.SortedCollection

All Implemented Interfaces:

java.lang.Cloneable, java.util.Collection, java.io.Serializable

public class SortedCollection

extends java.lang.Object

implements java.util.Collection, java.io.Serializable, java.lang.Cloneable

Collection implementation which sorts its elements according to their natural order or according to the order specified by a custom Comparator. In contrast to java.util.TreeSet, this collection can contain duplicates.

Example

At first a example without a custom comparator:

  ...
  Collection c = new SortedCollection();
  c.add("B");
  c.add("C");
  c.add("A");
  c.add("A");

  System.out.println(c.toString());
 

Executing this code will print to following to stdout:

[A, A, B, C]

Notes On The Implementation

• Be aware of the small differences between remove(Object) and removeAll(Collection). remove(Object) removes a single element from the collection and removeAll(Collection) removes all elements from the collection which are equal to elements of the specified collection.
• The iterator returned by iterator() returns the elements according to their natural order (if they implement java.lang.Comparable) respectively according to the specification of the custom comparator.
• The iterator returned by iterator() supports the Iterator.remove() method.
• All elements added to this list must either implement the Comparable interface if the collection was created without a custom comparator or must be compatible to the custom comparator. If not, a ClassCastException will be thrown.
• This collection is not synchronized. If you need a thread-safe instance of this class, wrapped it using Collections.synchronizedCollection(Collection).
• The iterators returned by via iterator() are fail-fast and will throw an ConcurrentModificationException if the collection changes will the iterator is still in use.

Since:

0.10

Version:

$Revision: 1.8.2.1 $

Author:

Oliver Fischer

See Also:

http://developer.java.sun.com/developer/bugParade/bugs/4151747.html, Serialized Form

Constructor Summary

SortedCollection()
Constructs a new sorted collection of elements.

SortedCollection(java.util.Collection pMaster)

SortedCollection(java.util.Collection pMaster, java.util.Comparator pSorter)
Creates a new instance of this collection containing all the elements of another Collection sorted according to a given Comparator.

SortedCollection(java.util.Comparator pSorter)
Creates a new empty sorted collection.

SortedCollection(java.util.Iterator pSource)
Constructs a new sorted collection containing the elements referenced by a given iterator.

SortedCollection(java.util.Iterator pSource, java.util.Comparator pSorter)
Creates a new sorted collection containing all the elements of a given iteration sorted according to the specification of a custom comparator.

Method Summary

boolean	add(java.lang.Object pNewObj)
boolean	addAll(java.util.Collection c)
void	clear() Removes all references to the current referenced objects in this instance.
java.lang.Object	clone() Creates a copy of this instance.
boolean	contains(java.lang.Object o) Checks if a given Object is contained by this SortedCollection.
boolean	containsAll(java.util.Collection c)
protected org.xshare.base.collections.LinkedNode	findFirstGreater(java.lang.Object pCompareObj)
protected org.xshare.base.collections.LinkedNode	internalContains(java.lang.Object pToLookUp)
boolean	isEmpty() Checks if this instance is empty or not.
java.util.Iterator	iterator() Returns a Iterator over all elements in this collection starting from the first element.
boolean	remove(java.lang.Object o) Removes a single object instance from the collection.
boolean	removeAll(java.util.Collection c) Removes all elements from the collection which are equal to the elements of a given collection.
boolean	retainAll(java.util.Collection c)
int	size() Returns the number of elements in this collection.
java.lang.Object[]	toArray() Returns a array containing all objects of this collection.
java.lang.Object[]	toArray(java.lang.Object[] target) This method fullfills the specification of Collection.toArray(Object[]).
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Collection

equals, hashCode

Constructor Detail

SortedCollection

public SortedCollection()

Constructs a new sorted collection of elements. All elements added to this collection will be sorted according to their "natural" order. Hence they elements must implement the Comparable interface.

SortedCollection

public SortedCollection(java.util.Iterator pSource,
                        java.util.Comparator pSorter)

Creates a new sorted collection containing all the elements of a given iteration sorted according to the specification of a custom comparator.

Parameters:

pSource - a Iterator object pointing to all elements which should be contained by this sorted collection.

pSorter - a Comparator object specifing the order of the elements of this sorted collection.

Throws:

java.lang.NullPointerException - if one of both parameters is null.

SortedCollection

public SortedCollection(java.util.Iterator pSource)

Constructs a new sorted collection containing the elements referenced by a given iterator. All elements of this collection will be sorted according to their "natural" order. Hence they elements must implement the Comparable interface.

Parameters:

pSource - a Iterator object pointing to all elements which should be added to the collection.

Throws:

java.lang.NullPointerException - if the given Iterator is null.

java.lang.ClassCastException - if the elements provided by the given Iterator don't implement Comparable

SortedCollection

public SortedCollection(java.util.Comparator pSorter)

Creates a new empty sorted collection. All elements of this collection will be sorted according to the Comparator passed to the constructor.

Parameters:

pSorter - a Comparator object responsible for the sorting of the elements of this collection.

Throws:

java.lang.NullPointerException - if the given Comparator is null.

SortedCollection

public SortedCollection(java.util.Collection pMaster,
                        java.util.Comparator pSorter)

Creates a new instance of this collection containing all the elements of another Collection sorted according to a given Comparator.

Parameters:

pMaster - a Collection object containing all the elements which should be contained in this instance of the SortedCollection.

pSorter - a Comparator object used for sorting all the elements of this collection.

Throws:

java.lang.NullPointerException - if one of both parameters is null.

SortedCollection

public SortedCollection(java.util.Collection pMaster)

Throws:

java.lang.ClassCastException - if the objects contained in the given Collection don't implement the Comparable interface

java.lang.NullPointerException - if the given Collection is null.

Method Detail

clear

public void clear()

Removes all references to the current referenced objects in this instance.

Specified by:

clear in interface java.util.Collection

retainAll

public boolean retainAll(java.util.Collection c)

Specified by:

retainAll in interface java.util.Collection

removeAll

public boolean removeAll(java.util.Collection c)

Removes all elements from the collection which are equal to the elements of a given collection.

Specified by:

removeAll in interface java.util.Collection

Returns:

a boolean value which is true if the collection changed because of this method call.

See Also:

remove(Object)

addAll

public boolean addAll(java.util.Collection c)

Specified by:

addAll in interface java.util.Collection

Throws:

java.lang.ClassCastException - if one element of the given collection does't implement Comparable and this collection doesn't have a custom Comparator.

containsAll

public boolean containsAll(java.util.Collection c)

Specified by:

containsAll in interface java.util.Collection

See Also:

contains(Object)

remove

public boolean remove(java.lang.Object o)

Removes a single object instance from the collection. In other words: If you have a sorted collection which contains three times the string object A and you call instance.remove("A") one instance of A is removed and two are kept.

Specified by:

remove in interface java.util.Collection

Returns:

a boolean value which is true if the collection changed because of this method call.

See Also:

removeAll(Collection)

add

public boolean add(java.lang.Object pNewObj)

Specified by:

add in interface java.util.Collection

Throws:

java.lang.ClassCastException - if the element does't implement Comparable and this collection doesn't have a custom Comparator.

toArray

public java.lang.Object[] toArray(java.lang.Object[] target)

This method fullfills the specification of Collection.toArray(Object[]).

Specified by:

toArray in interface java.util.Collection

Returns:

a Object[] containing all elements of this collection in the same order as they are returned by the iterator of this collection.

toArray

public java.lang.Object[] toArray()

Returns a array containing all objects of this collection. The implementation guarantees that the returned array contains all elements contained in this collection and the the array has the same order as the collection itself.

Specified by:

toArray in interface java.util.Collection

Returns:

a Object[] containing all elements of this collection.

iterator

public java.util.Iterator iterator()

Returns a Iterator over all elements in this collection starting from the first element. The returned iterator works on the underlying collection directly.

Specified by:

iterator in interface java.util.Collection

Returns:

a Iterator over all elements in the collection with support for Iterator.remove() which is fail-fast.

contains

public boolean contains(java.lang.Object o)

Checks if a given Object is contained by this SortedCollection.

Specified by:

contains in interface java.util.Collection

Returns:

a boolean value which is true if at least one Object is containted by this list. This is true is one object fills in the condition ObjectFromList.equals(givenObject). Otherwise this method returns false.

internalContains

protected org.xshare.base.collections.LinkedNode internalContains(java.lang.Object pToLookUp)

findFirstGreater

protected org.xshare.base.collections.LinkedNode findFirstGreater(java.lang.Object pCompareObj)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

isEmpty

public boolean isEmpty()

Checks if this instance is empty or not.

Specified by:

isEmpty in interface java.util.Collection

Returns:

a boolean value which is true if the collections doesn't contain elements. Otherwise false is the expected return value.

size

public int size()

Returns the number of elements in this collection.

Specified by:

size in interface java.util.Collection

Returns:

an int value containing the current number of stored elements.

clone

public java.lang.Object clone()

Creates a copy of this instance.

Overrides:

clone in class java.lang.Object

Returns:

a Object object, which is a instance of SortedCollection and constains the same elements as this instance and uses the same comparator instance if a custom comparator has been provided at creationtime.