Return-Path: Delivered-To: apmail-jakarta-commons-dev-archive@apache.org Received: (qmail 82281 invoked from network); 4 Mar 2002 19:19:02 -0000 Received: from unknown (HELO nagoya.betaversion.org) (192.18.49.131) by daedalus.apache.org with SMTP; 4 Mar 2002 19:19:02 -0000 Received: (qmail 5449 invoked by uid 97); 4 Mar 2002 19:19:04 -0000 Delivered-To: qmlist-jakarta-archive-commons-dev@jakarta.apache.org Received: (qmail 5430 invoked by uid 97); 4 Mar 2002 19:19:03 -0000 Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Jakarta Commons Developers List" Reply-To: "Jakarta Commons Developers List" Delivered-To: mailing list commons-dev@jakarta.apache.org Received: (qmail 5419 invoked by uid 97); 4 Mar 2002 19:19:03 -0000 Date: 4 Mar 2002 19:18:56 -0000 Message-ID: <20020304191856.70461.qmail@icarus.apache.org> From: morgand@apache.org To: jakarta-commons-cvs@apache.org Subject: cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections/comparators ComparatorChain.java X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N morgand 02/03/04 11:18:56 Modified: collections/src/java/org/apache/commons/collections/comparators ComparatorChain.java Log: added complete JavaDocs, added isLocked() and size() methods, made checkLocked() method private Revision Changes Path 1.4 +105 -11 jakarta-commons/collections/src/java/org/apache/commons/collections/comparators/ComparatorChain.java Index: ComparatorChain.java =================================================================== RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/comparators/ComparatorChain.java,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- ComparatorChain.java 1 Mar 2002 23:48:59 -0000 1.3 +++ ComparatorChain.java 4 Mar 2002 19:18:56 -0000 1.4 @@ -1,7 +1,7 @@ /* - * $Header: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/comparators/ComparatorChain.java,v 1.3 2002/03/01 23:48:59 morgand Exp $ - * $Revision: 1.3 $ - * $Date: 2002/03/01 23:48:59 $ + * $Header: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/comparators/ComparatorChain.java,v 1.4 2002/03/04 19:18:56 morgand Exp $ + * $Revision: 1.4 $ + * $Date: 2002/03/04 19:18:56 $ * * ==================================================================== * @@ -87,7 +87,10 @@ * Object) has been called will result in an * UnsupportedOperationException.

* - *

Instances of ComparatorChain are not synchronized.

+ *

Instances of ComparatorChain are not synchronized. + * The class is not thread-safe at construction time, but + * it is thread-safe to perform multiple comparisons + * after all the setup operations are complete.

* * @author Morgan Delagrange */ @@ -101,10 +104,23 @@ // compare(Object,Object) is called) protected boolean isLocked = false; + /** + * Construct a ComparatorChain with a single Comparator, + * sorting in the forward order + * + * @param comparator First comparator in the Comparator chain + */ public ComparatorChain(Comparator comparator) { this(comparator,false); } + /** + * Construct a Comparator chain with a single Comparator, + * sorting in the given order + * + * @param comparator First Comparator in the ComparatorChain + * @param reverse false = forward sort; true = reverse sort + */ public ComparatorChain(Comparator comparator, boolean reverse) { comparatorChain = new ArrayList(); comparatorChain.add(comparator); @@ -115,8 +131,11 @@ } /** + * Construct a ComparatorChain from the Comparators in the + * List. All Comparators will default to the forward + * sort order. * - * @param list + * @param list List of Comparators * @see #ComparatorChain(List,BitSet) */ public ComparatorChain(List list) { @@ -124,11 +143,20 @@ } /** + * Construct a ComparatorChain from the Comparators in the + * given List. The sort order of each column will be + * drawn from the given BitSet. When determining the sort + * order for Comparator at index i in the List, + * the ComparatorChain will call BitSet.get(i). + * If that method returns false, the forward + * sort order is used; a return value of true + * indicates reverse sort order. * - * @param list NOTE: This constructor performs a defensive - * copy of the list elements into a new - * List. - * @param bits + * @param list List of Comparators. NOTE: This constructor performs a + * defensive copy of the list elements into a new + * List. + * @param bits Sort order for each Comparator. Extra bits are ignored, + * unless extra Comparators are added by another method. */ public ComparatorChain(List list, BitSet bits) { comparatorChain = new ArrayList(); @@ -136,10 +164,23 @@ orderingBits = bits; } + /** + * Add a Comparator to the end of the chain using the + * forward sort order + * + * @param comparator Comparator with the forward sort order + */ public void addComparator(Comparator comparator) { addComparator(comparator,false); } + /** + * Add a Comparator to the end of the chain using the + * given sort order + * + * @param comparator Comparator to add to the end of the chain + * @param reverse false = forward sort order; true = reverse sort order + */ public void addComparator(Comparator comparator, boolean reverse) { checkLocked(); @@ -149,10 +190,28 @@ } } - public void setComparator(int index, Comparator comparator) { + /** + * Replace the Comparator at the given index, maintaining + * the existing sort order. + * + * @param index index of the Comparator to replace + * @param comparator Comparator to place at the given index + * @exception IndexOutOfBoundsException + * if index < 0 or index > size() + */ + public void setComparator(int index, Comparator comparator) + throws IndexOutOfBoundsException { setComparator(index,comparator,false); } + /** + * Replace the Comparator at the given index in the + * ComparatorChain, using the given sort order + * + * @param index index of the Comparator to replace + * @param comparator Comparator to set + * @param reverse false = forward sort order; true = reverse sort order + */ public void setComparator(int index, Comparator comparator, boolean reverse) { checkLocked(); @@ -164,17 +223,52 @@ } } + + /** + * Change the sort order at the given index in the + * ComparatorChain to a forward sort. + * + * @param index Index of the ComparatorChain + */ public void setForwardSort(int index) { checkLocked(); orderingBits.clear(index); } + /** + * Change the sort order at the given index in the + * ComparatorChain to a reverse sort. + * + * @param index Index of the ComparatorChain + */ public void setReverseSort(int index) { checkLocked(); orderingBits.set(index); } - public void checkLocked() { + /** + * Number of Comparators in the current ComparatorChain. + * + * @return Comparator count + */ + public int size() { + return comparatorChain.size(); + } + + /** + * Determine if modifications can still be made to the + * ComparatorChain. ComparatorChains cannot be modified + * once they have performed a comparison. + * + * @return true = ComparatorChain cannot be modified; false = + * ComparatorChain can still be modified. + */ + public boolean isLocked() { + return isLocked; + } + + // throw an exception if the ComparatorChain is locked + private void checkLocked() { if (isLocked == true) { throw new UnsupportedOperationException("Comparator ordering cannot be changed after the first comparison is performed"); } -- To unsubscribe, e-mail: For additional commands, e-mail: