From 335f3c48020033d2e0407949690e9f409b660c1e Mon Sep 17 00:00:00 2001 From: Thomas Neidhart Date: Tue, 3 Jul 2012 21:13:33 +0000 Subject: [PATCH] Cleanup of comparators package. git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1356950 13f79535-47bb-0310-9956-ffa450edef68 --- .../comparators/BooleanComparator.java | 4 +- .../comparators/ComparableComparator.java | 54 ++++++++-------- .../comparators/ComparatorChain.java | 63 ++++++++++--------- .../comparators/FixedOrderComparator.java | 8 +-- .../comparators/NullComparator.java | 4 +- .../comparators/ReverseComparator.java | 4 +- .../comparators/TransformingComparator.java | 4 +- .../collections/comparators/package-info.java | 28 +++++++++ .../collections/comparators/package.html | 27 -------- 9 files changed, 94 insertions(+), 102 deletions(-) create mode 100644 src/main/java/org/apache/commons/collections/comparators/package-info.java delete mode 100644 src/main/java/org/apache/commons/collections/comparators/package.html diff --git a/src/main/java/org/apache/commons/collections/comparators/BooleanComparator.java b/src/main/java/org/apache/commons/collections/comparators/BooleanComparator.java index 8abfd7404..47881c9cc 100644 --- a/src/main/java/org/apache/commons/collections/comparators/BooleanComparator.java +++ b/src/main/java/org/apache/commons/collections/comparators/BooleanComparator.java @@ -28,9 +28,7 @@ import java.util.Comparator; * @see #booleanComparator(boolean) * * @since Commons Collections 3.0 - * @version $Revision$ - * - * @author Rodney Waldhoff + * @version $Id$ */ public final class BooleanComparator implements Comparator, Serializable { diff --git a/src/main/java/org/apache/commons/collections/comparators/ComparableComparator.java b/src/main/java/org/apache/commons/collections/comparators/ComparableComparator.java index 4e644b234..7ded59842 100644 --- a/src/main/java/org/apache/commons/collections/comparators/ComparableComparator.java +++ b/src/main/java/org/apache/commons/collections/comparators/ComparableComparator.java @@ -20,24 +20,23 @@ import java.io.Serializable; import java.util.Comparator; /** - * A {@link Comparator Comparator} that compares - * {@link Comparable Comparable} objects. - *

- * This Comparator is useful, for example, - * for enforcing the natural order in custom implementations - * of SortedSet and SortedMap. - *

- * Note: In the 2.0 and 2.1 releases of Commons Collections, - * this class would throw a {@link ClassCastException} if - * either of the arguments to {@link #compare(Object, Object) compare} - * were null, not {@link Comparable Comparable}, - * or for which {@link Comparable#compareTo(Object) compareTo} gave - * inconsistent results. This is no longer the case. See - * {@link #compare(Object, Object) compare} for details. - * + * A {@link Comparator Comparator} that compares {@link Comparable Comparable} + * objects. + *

+ * This Comparator is useful, for example, for enforcing the natural order in + * custom implementations of {@link SortedSet} and {@link SortedMap}. + *

+ * Note: In the 2.0 and 2.1 releases of Commons Collections, this class would + * throw a {@link ClassCastException} if either of the arguments to + * {@link #compare(Object, Object) compare} were null, not + * {@link Comparable Comparable}, or for which + * {@link Comparable#compareTo(Object) compareTo} gave inconsistent results. + * This is no longer the case. See {@link #compare(Object, Object) compare} for + * details. + * * @since Commons Collections 2.0 - * @version $Revision$ - * + * @version $Id$ + * * @see java.util.Collections#reverseOrder() */ public class ComparableComparator> implements Comparator, Serializable { @@ -57,6 +56,7 @@ public class ComparableComparator> implements Co * instead of constructing a new instance to reduce allocation and GC overhead * when multiple comparable comparators may be used in the same VM. * + * @param the element type * @return the singleton ComparableComparator */ @SuppressWarnings("unchecked") @@ -83,9 +83,9 @@ public class ComparableComparator> implements Co * @param obj1 the first object to compare * @param obj2 the second object to compare * @return negative if obj1 is less, positive if greater, zero if equal - * @throws NullPointerException when obj1 is null, + * @throws NullPointerException if obj1 is null, * or when ((Comparable)obj1).compareTo(obj2) does - * @throws ClassCastException when obj1 is not a Comparable, + * @throws ClassCastException if obj1 is not a Comparable, * or when ((Comparable)obj1).compareTo(obj2) does */ public int compare(E obj1, E obj2) { @@ -106,18 +106,16 @@ public class ComparableComparator> implements Co } /** - * Returns true iff that Object is - * is a {@link Comparator Comparator} whose ordering is - * known to be equivalent to mine. + * Returns {@code true} iff that Object is is a {@link Comparator Comparator} + * whose ordering is known to be equivalent to mine. *

- * This implementation returns true - * iff object.{@link Object#getClass() getClass()} - * equals this.getClass(). - * Subclasses may want to override this behavior to remain consistent - * with the {@link Comparator#equals(Object)} contract. + * This implementation returns {@code true} iff + * object.{@link Object#getClass() getClass()} equals + * this.getClass(). Subclasses may want to override this behavior to remain + * consistent with the {@link Comparator#equals(Object)} contract. * * @param object the object to compare with - * @return true if equal + * @return {@code true} if equal * @since Commons Collections 3.0 */ @Override diff --git a/src/main/java/org/apache/commons/collections/comparators/ComparatorChain.java b/src/main/java/org/apache/commons/collections/comparators/ComparatorChain.java index f438d5129..81210a71a 100644 --- a/src/main/java/org/apache/commons/collections/comparators/ComparatorChain.java +++ b/src/main/java/org/apache/commons/collections/comparators/ComparatorChain.java @@ -24,35 +24,28 @@ import java.util.Iterator; import java.util.List; /** - *

A ComparatorChain is a Comparator that wraps one or - * more Comparators in sequence. The ComparatorChain - * calls each Comparator in sequence until either 1) - * any single Comparator returns a non-zero result - * (and that result is then returned), - * or 2) the ComparatorChain is exhausted (and zero is - * returned). This type of sorting is very similar - * to multi-column sorting in SQL, and this class - * allows Java classes to emulate that kind of behaviour - * when sorting a List.

- * - *

To further facilitate SQL-like sorting, the order of - * any single Comparator in the list can be reversed.

- * - *

Calling a method that adds new Comparators or - * changes the ascend/descend sort after compare(Object, - * Object) has been called will result in an - * UnsupportedOperationException. However, take care - * to not alter the underlying List of Comparators - * or the BitSet that defines the sort order.

- * - *

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.

- * + * A ComparatorChain is a Comparator that wraps one or more Comparators in + * sequence. The ComparatorChain calls each Comparator in sequence until either + * 1) any single Comparator returns a non-zero result (and that result is then + * returned), or 2) the ComparatorChain is exhausted (and zero is returned). + * This type of sorting is very similar to multi-column sorting in SQL, and this + * class allows Java classes to emulate that kind of behaviour when sorting a + * List. + *

+ * To further facilitate SQL-like sorting, the order of any single Comparator in + * the list can be reversed. + *

+ * Calling a method that adds new Comparators or changes the ascend/descend sort + * after compare(Object, Object) has been called will result in an + * UnsupportedOperationException. However, take care to not alter the + * underlying List of Comparators or the BitSet that defines the sort order. + *

+ * 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. + * * @since Commons Collections 2.0 - * @author Morgan Delagrange - * @version $Revision$ + * @version $Id$ */ public class ComparatorChain implements Comparator, Serializable { @@ -237,13 +230,23 @@ public class ComparatorChain implements Comparator, Serializable { return isLocked; } - // throw an exception if the ComparatorChain is locked + /** + * Throws an exception if the {@link ComparatorChain} is locked. + * + * @throws UnsupportedOperationException if the {@link ComparatorChain} is locked + */ private void checkLocked() { if (isLocked == true) { - throw new UnsupportedOperationException("Comparator ordering cannot be changed after the first comparison is performed"); + throw new UnsupportedOperationException( + "Comparator ordering cannot be changed after the first comparison is performed"); } } + /** + * Throws an exception if the {@link ComparatorChain} is empty. + * + * @throws UnsupportedOperationException if the {@link ComparatorChain} is empty + */ private void checkChainIntegrity() { if (comparatorChain.size() == 0) { throw new UnsupportedOperationException("ComparatorChains must contain at least one Comparator"); diff --git a/src/main/java/org/apache/commons/collections/comparators/FixedOrderComparator.java b/src/main/java/org/apache/commons/collections/comparators/FixedOrderComparator.java index e49c7e919..b522fde6a 100644 --- a/src/main/java/org/apache/commons/collections/comparators/FixedOrderComparator.java +++ b/src/main/java/org/apache/commons/collections/comparators/FixedOrderComparator.java @@ -41,17 +41,13 @@ import java.util.Map; * multiple comparisons after all the setup operations are complete. * * @since Commons Collections 3.0 - * @version $Revision$ - * - * @author David Leppik - * @author Stephen Colebourne - * @author Janek Bogucki + * @version $Id$ */ public class FixedOrderComparator implements Comparator { /** * Unknown object behavior enum. - * @since Commons Collections 5 + * @since Commons Collections 4.0 */ public static enum UnknownObjectBehavior { BEFORE, AFTER, EXCEPTION; diff --git a/src/main/java/org/apache/commons/collections/comparators/NullComparator.java b/src/main/java/org/apache/commons/collections/comparators/NullComparator.java index 9d16f3987..5b8e28d6c 100644 --- a/src/main/java/org/apache/commons/collections/comparators/NullComparator.java +++ b/src/main/java/org/apache/commons/collections/comparators/NullComparator.java @@ -26,9 +26,7 @@ import org.apache.commons.collections.ComparatorUtils; * other objects. * * @since Commons Collections 2.0 - * @version $Revision$ - * - * @author Michael A. Smith + * @version $Id$ */ public class NullComparator implements Comparator, Serializable { diff --git a/src/main/java/org/apache/commons/collections/comparators/ReverseComparator.java b/src/main/java/org/apache/commons/collections/comparators/ReverseComparator.java index 82e45d5a7..7fdcc2cb1 100644 --- a/src/main/java/org/apache/commons/collections/comparators/ReverseComparator.java +++ b/src/main/java/org/apache/commons/collections/comparators/ReverseComparator.java @@ -26,9 +26,7 @@ import org.apache.commons.collections.ComparatorUtils; * to its {@link #compare(Object, Object) compare} method. * * @since Commons Collections 2.0 - * @version $Revision$ - * - * @author Michael A. Smith + * @version $Id$ * * @see java.util.Collections#reverseOrder() */ diff --git a/src/main/java/org/apache/commons/collections/comparators/TransformingComparator.java b/src/main/java/org/apache/commons/collections/comparators/TransformingComparator.java index cffb3e5af..77d9f3f49 100644 --- a/src/main/java/org/apache/commons/collections/comparators/TransformingComparator.java +++ b/src/main/java/org/apache/commons/collections/comparators/TransformingComparator.java @@ -26,8 +26,8 @@ import org.apache.commons.collections.Transformer; * return value from the transform operation will be passed to the decorated * {@link Comparator#compare(Object,Object) compare} method. * - * @since Commons Collections 2.0 (?) - * @version $Revision$ + * @since Commons Collections 2.1 + * @version $Id$ * * @see org.apache.commons.collections.Transformer * @see org.apache.commons.collections.comparators.ComparableComparator diff --git a/src/main/java/org/apache/commons/collections/comparators/package-info.java b/src/main/java/org/apache/commons/collections/comparators/package-info.java new file mode 100644 index 000000000..000df6636 --- /dev/null +++ b/src/main/java/org/apache/commons/collections/comparators/package-info.java @@ -0,0 +1,28 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + * This package contains implementations of the + * {@link java.util.Comparator Comparator} interface. + *

+ * You may also consider using + * {@link org.apache.commons.collections.ComparatorUtils ComparatorUtils}, + * which is a single class that uses static methods to construct instances + * of the classes in this package. + * + * @version $Id$ + */ +package org.apache.commons.collections.comparators; \ No newline at end of file diff --git a/src/main/java/org/apache/commons/collections/comparators/package.html b/src/main/java/org/apache/commons/collections/comparators/package.html deleted file mode 100644 index 9342f28c0..000000000 --- a/src/main/java/org/apache/commons/collections/comparators/package.html +++ /dev/null @@ -1,27 +0,0 @@ - - - -

-This package contains implementations of the -{@link java.util.Comparator Comparator} interface. -

-You may also consider using -{@link org.apache.commons.collections.ComparatorUtils ComparatorUtils}, -which is a single class that uses static methods to construct instances -of the classes in this package. -