IO-142 Add facility to sort file lists/arrays to Comparator implementations

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/io/trunk@721626 13f79535-47bb-0310-9956-ffa450edef68

Author: Niall Pemberton

src/java/org/apache/commons/io/comparator/AbstractFileComparator.java

@@ -0,0 +1,64 @@
+/*
+ * 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.
+ */
+package org.apache.commons.io.comparator;
+
+import java.io.File;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.List;
+
+/**
+ * Abstract file {@link Comparator} which provides sorting for file arrays and lists.
+ *
+ * @version $Revision$ $Date$
+ * @since Commons IO 2.0
+ */
+abstract class AbstractFileComparator implements Comparator<File> {
+
+    /**
+     * Sort an array of files.
+     * <p>
+     * This method uses {@link Arrays#sort(File[], Comparator)}
+     * and returns the original array.
+     *
+     * @param files The files to sort, may be null
+     * @return The sorted array
+     */
+    public File[] sort(File... files) {
+        if (files != null) {
+            Arrays.sort(files, this);
+        }
+        return files;
+    }
+
+    /**
+     * Sort a List of files.
+     * <p>
+     * This method uses {@link Collections#sort(List, Comparator)}
+     * and returns the original list.
+     *
+     * @param files The files to sort, may be null
+     * @return The sorted list
+     */
+    public List<File> sort(List<File> files) {
+        if (files != null) {
+            Collections.sort(files, this);
+        }
+        return files;
+    }
+}

src/java/org/apache/commons/io/comparator/DefaultFileComparator.java

@@ -30,21 +30,21 @@
  * {@link #DEFAULT_COMPARATOR} singleton instance:
  * <pre>
  *       List&lt;File&gt; list = ...
- *       Collections.sort(list, DefaultFileComparator.DEFAULT_COMPARATOR);
+ *       DefaultFileComparator.DEFAULT_COMPARATOR.sort(list);
  * </pre>
  * <p>
  * Example of doing a <i>reverse</i> sort of an array of files using the
  * {@link #DEFAULT_REVERSE} singleton instance:
  * <pre>
  *       File[] array = ...
- *       Arrays.sort(array, DefaultFileComparator.DEFAULT_REVERSE);
+ *       DefaultFileComparator.DEFAULT_REVERSE.sort(array);
  * </pre>
  * <p>
  *
  * @version $Revision$ $Date$
  * @since Commons IO 1.4
  */
-public class DefaultFileComparator implements Comparator<File>, Serializable {
+public class DefaultFileComparator extends AbstractFileComparator implements Serializable {
 
     /** Singleton default comparator instance */
     public static final Comparator<File> DEFAULT_COMPARATOR = new DefaultFileComparator();

src/java/org/apache/commons/io/comparator/ExtensionFileComparator.java

@@ -37,21 +37,21 @@
  * {@link #EXTENSION_COMPARATOR} singleton instance:
  * <pre>
  *       List&lt;File&gt; list = ...
- *       Collections.sort(list, ExtensionFileComparator.EXTENSION_COMPARATOR);
+ *       ExtensionFileComparator.EXTENSION_COMPARATOR.sort(list);
  * </pre>
  * <p>
  * Example of a <i>reverse case-insensitive</i> file extension sort using the
  * {@link #EXTENSION_INSENSITIVE_REVERSE} singleton instance:
  * <pre>
  *       File[] array = ...
- *       Arrays.sort(array, ExtensionFileComparator.EXTENSION_INSENSITIVE_REVERSE);
+ *       ExtensionFileComparator.EXTENSION_INSENSITIVE_REVERSE.sort(array);
  * </pre>
  * <p>
  *
  * @version $Revision$ $Date$
  * @since Commons IO 1.4
  */
-public class ExtensionFileComparator implements Comparator<File>, Serializable {
+public class ExtensionFileComparator extends AbstractFileComparator implements Serializable {
 
     /** Case-sensitive extension comparator instance (see {@link IOCase#SENSITIVE}) */
     public static final Comparator<File> EXTENSION_COMPARATOR = new ExtensionFileComparator();

src/java/org/apache/commons/io/comparator/LastModifiedFileComparator.java

@@ -31,21 +31,21 @@
  * {@link #LASTMODIFIED_COMPARATOR} singleton instance:
  * <pre>
  *       List&lt;File&gt; list = ...
- *       Collections.sort(list, LastModifiedFileComparator.LASTMODIFIED_COMPARATOR);
+ *       LastModifiedFileComparator.LASTMODIFIED_COMPARATOR.sort(list);
  * </pre>
  * <p>
  * Example of doing a <i>reverse</i> sort of an array of files using the
  * {@link #LASTMODIFIED_REVERSE} singleton instance:
  * <pre>
  *       File[] array = ...
- *       Arrays.sort(array, LastModifiedFileComparator.LASTMODIFIED_REVERSE);
+ *       LastModifiedFileComparator.LASTMODIFIED_REVERSE.sort(array);
  * </pre>
  * <p>
  *
  * @version $Revision$ $Date$
  * @since Commons IO 1.4
  */
-public class LastModifiedFileComparator implements Comparator<File>, Serializable {
+public class LastModifiedFileComparator extends AbstractFileComparator implements Serializable {
 
     /** Last modified comparator instance */
     public static final Comparator<File> LASTMODIFIED_COMPARATOR = new LastModifiedFileComparator();

src/java/org/apache/commons/io/comparator/NameFileComparator.java

@@ -35,21 +35,21 @@
  * {@link #NAME_COMPARATOR} singleton instance:
  * <pre>
  *       List&lt;File&gt; list = ...
- *       Collections.sort(list, NameFileComparator.NAME_COMPARATOR);
+ *       NameFileComparator.NAME_COMPARATOR.sort(list);
  * </pre>
  * <p>
  * Example of a <i>reverse case-insensitive</i> file name sort using the
  * {@link #NAME_INSENSITIVE_REVERSE} singleton instance:
  * <pre>
  *       File[] array = ...
- *       Arrays.sort(array, NameFileComparator.NAME_INSENSITIVE_REVERSE);
+ *       NameFileComparator.NAME_INSENSITIVE_REVERSE.sort(array);
  * </pre>
  * <p>
  *
  * @version $Revision$ $Date$
  * @since Commons IO 1.4
  */
-public class NameFileComparator implements Comparator<File>, Serializable {
+public class NameFileComparator extends AbstractFileComparator implements Serializable {
 
     /** Case-sensitive name comparator instance (see {@link IOCase#SENSITIVE}) */
     public static final Comparator<File> NAME_COMPARATOR = new NameFileComparator();

src/java/org/apache/commons/io/comparator/PathFileComparator.java

@@ -35,21 +35,21 @@
  * {@link #PATH_COMPARATOR} singleton instance:
  * <pre>
  *       List&lt;File&gt; list = ...
- *       Collections.sort(list, PathFileComparator.PATH_COMPARATOR);
+ *       PathFileComparator.PATH_COMPARATOR.sort(list);
  * </pre>
  * <p>
  * Example of a <i>reverse case-insensitive</i> file path sort using the
  * {@link #PATH_INSENSITIVE_REVERSE} singleton instance:
  * <pre>
  *       File[] array = ...
- *       Arrays.sort(array, PathFileComparator.PATH_INSENSITIVE_REVERSE);
+ *       PathFileComparator.PATH_INSENSITIVE_REVERSE.sort(array);
  * </pre>
  * <p>
  *
  * @version $Revision$ $Date$
  * @since Commons IO 1.4
  */
-public class PathFileComparator implements Comparator<File>, Serializable {
+public class PathFileComparator extends AbstractFileComparator implements Serializable {
 
     /** Case-sensitive path comparator instance (see {@link IOCase#SENSITIVE}) */
     public static final Comparator<File> PATH_COMPARATOR = new PathFileComparator();

src/java/org/apache/commons/io/comparator/ReverseComparator.java

@@ -27,7 +27,7 @@
  * @version $Revision$ $Date$
  * @since Commons IO 1.4
  */
-class ReverseComparator implements Comparator<File>, Serializable {
+class ReverseComparator extends AbstractFileComparator implements Serializable {
 
     private final Comparator<File> delegate;
 

src/java/org/apache/commons/io/comparator/SizeFileComparator.java

@@ -33,14 +33,14 @@
  * {@link #SIZE_COMPARATOR} singleton instance:
  * <pre>
  *       List&lt;File&gt; list = ...
- *       Collections.sort(list, LengthFileComparator.LENGTH_COMPARATOR);
+ *       SizeFileComparator.SIZE_COMPARATOR.sort(list);
  * </pre>
  * <p>
  * Example of doing a <i>reverse</i> sort of an array of files using the
  * {@link #SIZE_REVERSE} singleton instance:
  * <pre>
  *       File[] array = ...
- *       Arrays.sort(array, LengthFileComparator.LENGTH_REVERSE);
+ *       SizeFileComparator.SIZE_REVERSE.sort(array);
  * </pre>
  * <p>
  * <strong>N.B.</strong> Directories are treated as <b>zero size</b> unless
@@ -49,7 +49,7 @@
  * @version $Revision$ $Date$
  * @since Commons IO 1.4
  */
-public class SizeFileComparator implements Comparator<File>, Serializable {
+public class SizeFileComparator extends AbstractFileComparator implements Serializable {
 
     /** Size comparator instance - directories are treated as zero size */
     public static final Comparator<File> SIZE_COMPARATOR = new SizeFileComparator();

src/test/org/apache/commons/io/comparator/ComparatorAbstractTestCase.java

@@ -17,7 +17,10 @@
 package org.apache.commons.io.comparator;
 
 import java.io.File;
+import java.util.ArrayList;
 import java.util.Comparator;
+import java.util.List;
+
 import org.apache.commons.io.testtools.FileBasedTestCase;
 
 /**
@@ -26,7 +29,7 @@
 public abstract class ComparatorAbstractTestCase extends FileBasedTestCase {
 
     /** comparator instance */
-    protected Comparator comparator;
+    protected AbstractFileComparator comparator;
 
     /** reverse comparator instance */
     protected Comparator reverse;
@@ -53,7 +56,7 @@ public ComparatorAbstractTestCase(String name) {
 
     /** @see junit.framework.TestCase#setUp() */
     protected void setUp() throws Exception {
-        comparator = DefaultFileComparator.DEFAULT_COMPARATOR;
+        comparator = (AbstractFileComparator)DefaultFileComparator.DEFAULT_COMPARATOR;
         reverse = DefaultFileComparator.DEFAULT_REVERSE;
     }
 
@@ -84,4 +87,32 @@ public void testReverseComparator() {
         assertTrue("less",  reverse.compare(moreFile, lessFile) < 0);
         assertTrue("more",  reverse.compare(lessFile, moreFile) > 0);
     }
+
+    /**
+     * Test the comparator array sort.
+     */
+    public void testSortArray() {
+    	File[] files = new File[3];
+    	files[0] = equalFile1;
+    	files[1] = moreFile;
+    	files[2] = lessFile;
+    	comparator.sort(files);
+        assertTrue("equal", files[0] == lessFile);
+        assertTrue("less",  files[1] == equalFile1);
+        assertTrue("more",  files[2] == moreFile);
+    }
+
+    /**
+     * Test the comparator array sort.
+     */
+    public void testSortList() {
+    	List<File> files = new ArrayList<File>();
+    	files.add(equalFile1);
+    	files.add(moreFile);
+    	files.add(lessFile);
+    	comparator.sort(files);
+        assertTrue("equal", files.get(0) == lessFile);
+        assertTrue("less",  files.get(1) == equalFile1);
+        assertTrue("more",  files.get(2) == moreFile);
+    }
 }

src/test/org/apache/commons/io/comparator/DefaultFileComparatorTest.java

@@ -56,11 +56,11 @@ public DefaultFileComparatorTest(String name) {
     /** @see junit.framework.TestCase#setUp() */
     protected void setUp() throws Exception {
         super.setUp();
-        comparator = DefaultFileComparator.DEFAULT_COMPARATOR;
+        comparator = (AbstractFileComparator)DefaultFileComparator.DEFAULT_COMPARATOR;
         reverse = DefaultFileComparator.DEFAULT_REVERSE;
-        equalFile1 = new File("same");
-        equalFile2 = new File("same");
+        equalFile1 = new File("foo");
+        equalFile2 = new File("foo");
         lessFile   = new File("ABC");
-        moreFile   = new File("DEF");
+        moreFile   = new File("XYZ");
     }
 }