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