You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by tn...@apache.org on 2012/07/03 23:13:35 UTC
svn commit: r1356950 -
/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/
Author: tn
Date: Tue Jul 3 21:13:33 2012
New Revision: 1356950
URL: http://svn.apache.org/viewvc?rev=1356950&view=rev
Log:
Cleanup of comparators package.
Added:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/package-info.java
- copied, changed from r1356878, commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/package.html
Removed:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/package.html
Modified:
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/BooleanComparator.java
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ComparableComparator.java
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ComparatorChain.java
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/FixedOrderComparator.java
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/NullComparator.java
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ReverseComparator.java
commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/TransformingComparator.java
Modified: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/BooleanComparator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/BooleanComparator.java?rev=1356950&r1=1356949&r2=1356950&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/BooleanComparator.java (original)
+++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/BooleanComparator.java Tue Jul 3 21:13:33 2012
@@ -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<Boolean>, Serializable {
Modified: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ComparableComparator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ComparableComparator.java?rev=1356950&r1=1356949&r2=1356950&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ComparableComparator.java (original)
+++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ComparableComparator.java Tue Jul 3 21:13:33 2012
@@ -20,24 +20,23 @@ import java.io.Serializable;
import java.util.Comparator;
/**
- * A {@link Comparator Comparator} that compares
- * {@link Comparable Comparable} objects.
- * <p />
- * This Comparator is useful, for example,
- * for enforcing the natural order in custom implementations
- * of SortedSet and SortedMap.
- * <p />
- * 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 <code>null</code>, 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.
+ * <p>
+ * This Comparator is useful, for example, for enforcing the natural order in
+ * custom implementations of {@link SortedSet} and {@link SortedMap}.
+ * <p>
+ * 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 <code>null</code>, 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<E extends Comparable<? super E>> implements Comparator<E>, Serializable {
@@ -57,6 +56,7 @@ public class ComparableComparator<E exte
* instead of constructing a new instance to reduce allocation and GC overhead
* when multiple comparable comparators may be used in the same VM.
*
+ * @param <E> the element type
* @return the singleton ComparableComparator
*/
@SuppressWarnings("unchecked")
@@ -83,9 +83,9 @@ public class ComparableComparator<E exte
* @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 <i>obj1</i> is <code>null</code>,
+ * @throws NullPointerException if <i>obj1</i> is <code>null</code>,
* or when <code>((Comparable)obj1).compareTo(obj2)</code> does
- * @throws ClassCastException when <i>obj1</i> is not a <code>Comparable</code>,
+ * @throws ClassCastException if <i>obj1</i> is not a <code>Comparable</code>,
* or when <code>((Comparable)obj1).compareTo(obj2)</code> does
*/
public int compare(E obj1, E obj2) {
@@ -106,18 +106,16 @@ public class ComparableComparator<E exte
}
/**
- * Returns <code>true</code> iff <i>that</i> Object is
- * is a {@link Comparator Comparator} whose ordering is
- * known to be equivalent to mine.
+ * Returns {@code true} iff <i>that</i> Object is is a {@link Comparator Comparator}
+ * whose ordering is known to be equivalent to mine.
* <p>
- * This implementation returns <code>true</code>
- * iff <code><i>object</i>.{@link Object#getClass() getClass()}</code>
- * equals <code>this.getClass()</code>.
- * Subclasses may want to override this behavior to remain consistent
- * with the {@link Comparator#equals(Object)} contract.
+ * This implementation returns {@code true} iff
+ * <code><i>object</i>.{@link Object#getClass() getClass()}</code> equals
+ * <code>this.getClass()</code>. 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
Modified: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ComparatorChain.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ComparatorChain.java?rev=1356950&r1=1356949&r2=1356950&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ComparatorChain.java (original)
+++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ComparatorChain.java Tue Jul 3 21:13:33 2012
@@ -24,35 +24,28 @@ import java.util.Iterator;
import java.util.List;
/**
- * <p>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.</p>
- *
- * <p>To further facilitate SQL-like sorting, the order of
- * any single Comparator in the list can be reversed.</p>
- *
- * <p>Calling a method that adds new Comparators or
- * changes the ascend/descend sort <i>after compare(Object,
- * Object) has been called</i> will result in an
- * UnsupportedOperationException. However, <i>take care</i>
- * to not alter the underlying List of Comparators
- * or the BitSet that defines the sort order.</p>
- *
- * <p>Instances of ComparatorChain are not synchronized.
- * The class is not thread-safe at construction time, but
- * it <i>is</i> thread-safe to perform multiple comparisons
- * after all the setup operations are complete.</p>
- *
+ * 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.
+ * <p>
+ * To further facilitate SQL-like sorting, the order of any single Comparator in
+ * the list can be reversed.
+ * <p>
+ * Calling a method that adds new Comparators or changes the ascend/descend sort
+ * <i>after compare(Object, Object) has been called</i> will result in an
+ * UnsupportedOperationException. However, <i>take care</i> to not alter the
+ * underlying List of Comparators or the BitSet that defines the sort order.
+ * <p>
+ * Instances of ComparatorChain are not synchronized. The class is not
+ * thread-safe at construction time, but it <i>is</i> 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<E> implements Comparator<E>, Serializable {
@@ -237,13 +230,23 @@ public class ComparatorChain<E> implemen
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");
Modified: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/FixedOrderComparator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/FixedOrderComparator.java?rev=1356950&r1=1356949&r2=1356950&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/FixedOrderComparator.java (original)
+++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/FixedOrderComparator.java Tue Jul 3 21:13:33 2012
@@ -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<T> implements Comparator<T> {
/**
* Unknown object behavior enum.
- * @since Commons Collections 5
+ * @since Commons Collections 4.0
*/
public static enum UnknownObjectBehavior {
BEFORE, AFTER, EXCEPTION;
Modified: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/NullComparator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/NullComparator.java?rev=1356950&r1=1356949&r2=1356950&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/NullComparator.java (original)
+++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/NullComparator.java Tue Jul 3 21:13:33 2012
@@ -26,9 +26,7 @@ import org.apache.commons.collections.Co
* other objects.
*
* @since Commons Collections 2.0
- * @version $Revision$
- *
- * @author Michael A. Smith
+ * @version $Id$
*/
public class NullComparator<E> implements Comparator<E>, Serializable {
Modified: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ReverseComparator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ReverseComparator.java?rev=1356950&r1=1356949&r2=1356950&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ReverseComparator.java (original)
+++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/ReverseComparator.java Tue Jul 3 21:13:33 2012
@@ -26,9 +26,7 @@ import org.apache.commons.collections.Co
* 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()
*/
Modified: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/TransformingComparator.java
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/TransformingComparator.java?rev=1356950&r1=1356949&r2=1356950&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/TransformingComparator.java (original)
+++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/TransformingComparator.java Tue Jul 3 21:13:33 2012
@@ -26,8 +26,8 @@ import org.apache.commons.collections.Tr
* 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
Copied: commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/package-info.java (from r1356878, commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/package.html)
URL: http://svn.apache.org/viewvc/commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/package-info.java?p2=commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/package-info.java&p1=commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/package.html&r1=1356878&r2=1356950&rev=1356950&view=diff
==============================================================================
--- commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/package.html (original)
+++ commons/proper/collections/trunk/src/main/java/org/apache/commons/collections/comparators/package-info.java Tue Jul 3 21:13:33 2012
@@ -1,27 +1,28 @@
-<!-- $Id$ -->
- <!--
- 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.
- -->
-<BODY>
-<p>
-This package contains implementations of the
-{@link java.util.Comparator Comparator} interface.
-<p>
-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.
-</BODY>
+/*
+ * 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.
+ * <p>
+ * 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