IO-145 - add new package of File Comparator implementations

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

Author: Niall Pemberton

RELEASE-NOTES.txt

@@ -79,6 +79,14 @@ Enhancements from 1.3.2
 - IOCase
   - Add a compare method to IOCase [IO-144]
 
+- Add a package of java.util.Comparator implementations for files [IO-145]
+  - DefaultFileComparator - compare files using the default File.compareTo(File) method.
+  - ExtensionFileComparator - compares files using file name extensions.
+  - LastModifiedFileComparator - compares files using the last modified date/time.
+  - NameFileComparator - compares files using file names.
+  - PathFileComparator - compares files using file paths.
+  - SizeFileComparator - compares files using file sizes.
+
 
 Feedback
 --------

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

@@ -0,0 +1,68 @@
+/*
+ * 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.io.Serializable;
+import java.util.Comparator;
+
+/**
+ * Compare two files using the <b>default</b> {@link File#compareTo(File)} method.
+ * <p>
+ * This comparator can be used to sort lists or arrays of files
+ * by using the default file comparison.
+ * <p>
+ * Example of sorting a list of files using the
+ * {@link #DEFAULT_COMPARATOR} singleton instance:
+ * <pre>
+ *       List&lt;File&gt; list = ...
+ *       Collections.sort(list, DefaultFileComparator.DEFAULT_COMPARATOR);
+ * </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);
+ * </pre>
+ * <p>
+ *
+ * @version $Revision$ $Date$
+ * @since Commons IO 1.4
+ */
+public class DefaultFileComparator implements Comparator, Serializable {
+
+    /** Singleton default comparator instance */
+    public static final Comparator DEFAULT_COMPARATOR = new DefaultFileComparator();
+
+    /** Singleton reverse default comparator instance */
+    public static final Comparator DEFAULT_REVERSE = new ReverseComparator(DEFAULT_COMPARATOR);
+
+    /**
+     * Compare the two files using the {@link File#compareTo(File)} method.
+     * 
+     * @param obj1 The first file to compare
+     * @param obj2 The second file to compare
+     * @return the result of calling file1's
+     * {@link File#compareTo(File)} with file2 as the parameter.
+     */
+    public int compare(Object obj1, Object obj2) {
+        File file1 = (File)obj1;
+        File file2 = (File)obj2;
+        return file1.compareTo(file2);
+    }
+}

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

@@ -0,0 +1,112 @@
+/*
+ * 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.io.Serializable;
+import java.util.Comparator;
+
+import org.apache.commons.io.FilenameUtils;
+import org.apache.commons.io.IOCase;
+
+/**
+ * Compare the file name <b>extensions</b> for order
+ * (see {@link FilenameUtils#getExtension(String)}).
+ * <p>
+ * This comparator can be used to sort lists or arrays of files
+ * by their file extension either in a case-sensitive, case-insensitive or
+ * system dependant case sensitive way. A number of singleton instances
+ * are provided for the various case sensitivity options (using {@link IOCase})
+ * and the reverse of those options.
+ * <p>
+ * Example of a <i>case-sensitive</i> file extension sort using the
+ * {@link #EXTENSION_COMPARATOR} singleton instance:
+ * <pre>
+ *       List&lt;File&gt; list = ...
+ *       Collections.sort(list, ExtensionFileComparator.EXTENSION_COMPARATOR);
+ * </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);
+ * </pre>
+ * <p>
+ *
+ * @version $Revision$ $Date$
+ * @since Commons IO 1.4
+ */
+public class ExtensionFileComparator implements Comparator, Serializable {
+
+    /** Case-sensitive extension comparator instance (see {@link IOCase#SENSITIVE}) */
+    public static final Comparator EXTENSION_COMPARATOR = new ExtensionFileComparator();
+
+    /** Reverse case-sensitive extension comparator instance (see {@link IOCase#SENSITIVE}) */
+    public static final Comparator EXTENSION_REVERSE = new ReverseComparator(EXTENSION_COMPARATOR);
+
+    /** Case-insensitive extension comparator instance (see {@link IOCase#INSENSITIVE}) */
+    public static final Comparator EXTENSION_INSENSITIVE_COMPARATOR = new ExtensionFileComparator(IOCase.INSENSITIVE);
+
+    /** Reverse case-insensitive extension comparator instance (see {@link IOCase#INSENSITIVE}) */
+    public static final Comparator EXTENSION_INSENSITIVE_REVERSE
+                                                = new ReverseComparator(EXTENSION_INSENSITIVE_COMPARATOR);
+
+    /** System sensitive extension comparator instance (see {@link IOCase#SYSTEM}) */
+    public static final Comparator EXTENSION_SYSTEM_COMPARATOR = new ExtensionFileComparator(IOCase.SYSTEM);
+
+    /** Reverse system sensitive path comparator instance (see {@link IOCase#SYSTEM}) */
+    public static final Comparator EXTENSION_SYSTEM_REVERSE = new ReverseComparator(EXTENSION_SYSTEM_COMPARATOR);
+
+    /** Whether the comparison is case sensitive. */
+    private final IOCase caseSensitivity;
+
+    /**
+     * Construct a case sensitive file extension comparator instance.
+     */
+    public ExtensionFileComparator() {
+        this.caseSensitivity = IOCase.SENSITIVE;
+    }
+
+    /**
+     * Construct a file extension comparator instance with the specified case-sensitivity.
+     *
+     * @param caseSensitivity how to handle case sensitivity, null means case-sensitive
+     */
+    public ExtensionFileComparator(IOCase caseSensitivity) {
+        this.caseSensitivity = caseSensitivity == null ? IOCase.SENSITIVE : caseSensitivity;
+    }
+
+    /**
+     * Compare the extensions of two files the specified case sensitivity.
+     * 
+     * @param obj1 The first file to compare
+     * @param obj2 The second file to compare
+     * @return a negative value if the first file's extension
+     * is less than the second, zero if the extensions are the
+     * same and a positive value if the first files extension
+     * is greater than the second file.
+     * 
+     */
+    public int compare(Object obj1, Object obj2) {
+        File file1 = (File)obj1;
+        File file2 = (File)obj2;
+        String suffix1 = FilenameUtils.getExtension(file1.getName());
+        String suffix2 = FilenameUtils.getExtension(file2.getName());
+        return caseSensitivity.checkCompareTo(suffix1, suffix2);
+    }
+}

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

@@ -0,0 +1,79 @@
+/*
+ * 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.io.Serializable;
+import java.util.Comparator;
+
+/**
+ * Compare the <b>last modified date/time</b> of two files for order 
+ * (see {@link File#lastModified()}).
+ * <p>
+ * This comparator can be used to sort lists or arrays of files
+ * by their last modified date/time.
+ * <p>
+ * Example of sorting a list of files using the
+ * {@link #LASTMODIFIED_COMPARATOR} singleton instance:
+ * <pre>
+ *       List&lt;File&gt; list = ...
+ *       Collections.sort(list, LastModifiedFileComparator.LASTMODIFIED_COMPARATOR);
+ * </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);
+ * </pre>
+ * <p>
+ *
+ * @version $Revision$ $Date$
+ * @since Commons IO 1.4
+ */
+public class LastModifiedFileComparator implements Comparator, Serializable {
+
+    /** Last modified comparator instance */
+    public static final Comparator LASTMODIFIED_COMPARATOR = new LastModifiedFileComparator();
+
+    /** Reverse last modified comparator instance */
+    public static final Comparator LASTMODIFIED_REVERSE = new ReverseComparator(LASTMODIFIED_COMPARATOR);
+
+    /**
+     * Compare the last the last modified date/time of two files.
+     * 
+     * @param obj1 The first file to compare
+     * @param obj2 The second file to compare
+     * @return a negative value if the first file's lastmodified date/time
+     * is less than the second, zero if the lastmodified date/time are the
+     * same and a positive value if the first files lastmodified date/time
+     * is greater than the second file.
+     * 
+     */
+    public int compare(Object obj1, Object obj2) {
+        File file1 = (File)obj1;
+        File file2 = (File)obj2;
+        long result = file1.lastModified() - file2.lastModified();
+        if (result < 0) {
+            return -1;
+        } else if (result > 0) {
+            return 1;
+        } else {
+            return 0;
+        }
+    }
+}

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

@@ -0,0 +1,106 @@
+/*
+ * 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.io.Serializable;
+import java.util.Comparator;
+
+import org.apache.commons.io.IOCase;
+
+/**
+ * Compare the <b>names</b> of two files for order (see {@link File#getName()}).
+ * <p>
+ * This comparator can be used to sort lists or arrays of files
+ * by their name either in a case-sensitive, case-insensitive or
+ * system dependant case sensitive way. A number of singleton instances
+ * are provided for the various case sensitivity options (using {@link IOCase})
+ * and the reverse of those options.
+ * <p>
+ * Example of a <i>case-sensitive</i> file name sort using the
+ * {@link #NAME_COMPARATOR} singleton instance:
+ * <pre>
+ *       List&lt;File&gt; list = ...
+ *       Collections.sort(list, NameFileComparator.NAME_COMPARATOR);
+ * </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);
+ * </pre>
+ * <p>
+ *
+ * @version $Revision$ $Date$
+ * @since Commons IO 1.4
+ */
+public class NameFileComparator implements Comparator, Serializable {
+
+    /** Case-sensitive name comparator instance (see {@link IOCase#SENSITIVE}) */
+    public static final Comparator NAME_COMPARATOR = new NameFileComparator();
+
+    /** Reverse case-sensitive name comparator instance (see {@link IOCase#SENSITIVE}) */
+    public static final Comparator NAME_REVERSE = new ReverseComparator(NAME_COMPARATOR);
+
+    /** Case-insensitive name comparator instance (see {@link IOCase#INSENSITIVE}) */
+    public static final Comparator NAME_INSENSITIVE_COMPARATOR = new NameFileComparator(IOCase.INSENSITIVE);
+
+    /** Reverse case-insensitive name comparator instance (see {@link IOCase#INSENSITIVE}) */
+    public static final Comparator NAME_INSENSITIVE_REVERSE = new ReverseComparator(NAME_INSENSITIVE_COMPARATOR);
+
+    /** System sensitive name comparator instance (see {@link IOCase#SYSTEM}) */
+    public static final Comparator NAME_SYSTEM_COMPARATOR = new NameFileComparator(IOCase.SYSTEM);
+
+    /** Reverse system sensitive name comparator instance (see {@link IOCase#SYSTEM}) */
+    public static final Comparator NAME_SYSTEM_REVERSE = new ReverseComparator(NAME_SYSTEM_COMPARATOR);
+
+    /** Whether the comparison is case sensitive. */
+    private final IOCase caseSensitivity;
+
+    /**
+     * Construct a case sensitive file name comparator instance.
+     */
+    public NameFileComparator() {
+        this.caseSensitivity = IOCase.SENSITIVE;
+    }
+
+    /**
+     * Construct a file name comparator instance with the specified case-sensitivity.
+     *
+     * @param caseSensitivity  how to handle case sensitivity, null means case-sensitive
+     */
+    public NameFileComparator(IOCase caseSensitivity) {
+        this.caseSensitivity = caseSensitivity == null ? IOCase.SENSITIVE : caseSensitivity;
+    }
+
+    /**
+     * Compare the names of two files with the specified case sensitivity.
+     * 
+     * @param obj1 The first file to compare
+     * @param obj2 The second file to compare
+     * @return a negative value if the first file's name
+     * is less than the second, zero if the names are the
+     * same and a positive value if the first files name
+     * is greater than the second file.
+     */
+    public int compare(Object obj1, Object obj2) {
+        File file1 = (File)obj1;
+        File file2 = (File)obj2;
+        return caseSensitivity.checkCompareTo(file1.getName(), file2.getName());
+    }
+}