Apache Commons IO is a Java library created and maintained by the Apache Foundation. It provides a multitude of classes that enable developers to do common tasks easily and with much less boiler-plate code, that needs to be written over and over again for every single project.The importance of libraries like that is huge, because they are mature and maintained by experienced developers, who have thought of every possible edge-case, or fixed the various bugs when they appeared.
In this example, we are going to present some methods with varying functionality, depending on the package of org.apache.commons.io that they belong to. We are not going to delve too deep inside the library, as it is enormous, but we are going to provide examples for some common usage that can definitely come in handy for every developer, beginner or not.
1. Apache Commons IO Example
The code for this example will be broken into several classes, and each of them will be representative of a particular area that Apache Commons IO covers. These areas are:
- Utility classes
- Input
- Output
- Filters
- Comparators
- File Monitor
To make things even clearer, we are going to break down the output in chunks, one for each of the classes that we have created. We have also created a directory inside the project folder (named ExampleFolder) which will contain the various files that will be used in this example to show the functionality of the various classes.
NOTE: In order to use org.apache.commons.io, you need to download the jar files (found here) and add them to the build path of your Eclipse project, by right clicking on the project folder -> Build Path -> Add external archives.
ApacheCommonsExampleMain.java
public class ApacheCommonsExampleMain {
public static void main(String[] args) {
UtilityExample.runExample();
FileMonitorExample.runExample();
FiltersExample.runExample();
InputExample.runExample();
OutputExample.runExample();
ComparatorExample.runExample();
}
}
This is the main class that will be used to run the methods from the other classes of our example. You can comment certain classes in order to see the output that you want to.
1.1 Utility Classes
There are various Utility classes, inside the package org.apache.commons.io, most of which have to do with file manipulation and String comparison. We have used some of the most important ones here:
FilenameUtils: This class has methods that work with file names, and the main point is to make life easier in every OS (works equally well in Unix and Windows systems).FileUtils: It provides methods for file manipulation (moving, opening and reading a file, checking if a file exists, etc).IOCase: String manipulation and comparison methods.FileSystemUtils: Its methods return the free space of a designated drive.
UtilityExample.java
import java.io.File;
import java.io.IOException;
import org.apache.commons.io.FileSystemUtils;
import org.apache.commons.io.FileUtils;
import org.apache.commons.io.FilenameUtils;
import org.apache.commons.io.LineIterator;
import org.apache.commons.io.IOCase;
public final class UtilityExample {
// We are using the file exampleTxt.txt in the folder ExampleFolder,
// and we need to provide the full path to the Utility classes.
private static final String EXAMPLE_TXT_PATH =
"C:\\Users\\Lilykos\\workspace\\ApacheCommonsExample\\ExampleFolder\\exampleTxt.txt";
private static final String PARENT_DIR =
"C:\\Users\\Lilykos\\workspace\\ApacheCommonsExample";
public static void runExample() throws IOException {
System.out.println("Utility Classes example...");
// FilenameUtils
System.out.println("Full path of exampleTxt: " +
FilenameUtils.getFullPath(EXAMPLE_TXT_PATH));
System.out.println("Full name of exampleTxt: " +
FilenameUtils.getName(EXAMPLE_TXT_PATH));
System.out.println("Extension of exampleTxt: " +
FilenameUtils.getExtension(EXAMPLE_TXT_PATH));
System.out.println("Base name of exampleTxt: " +
FilenameUtils.getBaseName(EXAMPLE_TXT_PATH));
// FileUtils
// We can create a new File object using FileUtils.getFile(String)
// and then use this object to get information from the file.
File exampleFile = FileUtils.getFile(EXAMPLE_TXT_PATH);
LineIterator iter = FileUtils.lineIterator(exampleFile);
System.out.println("Contents of exampleTxt...");
while (iter.hasNext()) {
System.out.println("\t" + iter.next());
}
iter.close();
// We can check if a file exists somewhere inside a certain directory.
File parent = FileUtils.getFile(PARENT_DIR);
System.out.println("Parent directory contains exampleTxt file: " +
FileUtils.directoryContains(parent, exampleFile));
// IOCase
String str1 = "This is a new String.";
String str2 = "This is another new String, yes!";
System.out.println("Ends with string (case sensitive): " +
IOCase.SENSITIVE.checkEndsWith(str1, "string."));
System.out.println("Ends with string (case insensitive): " +
IOCase.INSENSITIVE.checkEndsWith(str1, "string."));
System.out.println("String equality: " +
IOCase.SENSITIVE.checkEquals(str1, str2));
// FileSystemUtils
System.out.println("Free disk space (in KB): " + FileSystemUtils.freeSpaceKb("C:"));
System.out.println("Free disk space (in MB): " + FileSystemUtils.freeSpaceKb("C:") / 1024);
}
}
Output
Utility Classes example... Full path of exampleTxt: C:\Users\Lilykos\workspace\ApacheCommonsExample\ExampleFolder\ Full name of exampleTxt: exampleTxt.txt Extension of exampleTxt: txt Base name of exampleTxt: exampleTxt Contents of exampleTxt... This is an example text file. We will use it for experimenting with Apache Commons IO. Parent directory contains exampleTxt file: true Ends with string (case sensitive): false Ends with string (case insensitive): true String equality: false Free disk space (in KB): 32149292 Free disk space (in MB): 31395
1.2 File Monitor
The org.apache.commons.io.monitor package contains methods that can get specific information about a File, but more importantly, it can create handlers that can be used to track changes in a specific file or folder and take action depending on the changes. Let’s take a look on the code:
FileMonitorExample.java
import java.io.File;
import java.io.IOException;
import org.apache.commons.io.FileDeleteStrategy;
import org.apache.commons.io.FileUtils;
import org.apache.commons.io.monitor.FileAlterationListenerAdaptor;
import org.apache.commons.io.monitor.FileAlterationMonitor;
import org.apache.commons.io.monitor.FileAlterationObserver;
import org.apache.commons.io.monitor.FileEntry;
public final class FileMonitorExample {
private static final String EXAMPLE_PATH =
"C:\\Users\\Lilykos\\workspace\\ApacheCommonsExample\\ExampleFolder\\exampleFileEntry.txt";
private static final String PARENT_DIR =
"C:\\Users\\Lilykos\\workspace\\ApacheCommonsExample\\ExampleFolder";
private static final String NEW_DIR =
"C:\\Users\\Lilykos\\workspace\\ApacheCommonsExample\\ExampleFolder\\newDir";
private static final String NEW_FILE =
"C:\\Users\\Lilykos\\workspace\\ApacheCommonsExample\\ExampleFolder\\newFile.txt";
public static void runExample() {
System.out.println("File Monitor example...");
// FileEntry
// We can monitor changes and get information about files
// using the methods of this class.
FileEntry entry = new FileEntry(FileUtils.getFile(EXAMPLE_PATH));
System.out.println("File monitored: " + entry.getFile());
System.out.println("File name: " + entry.getName());
System.out.println("Is the file a directory?: " + entry.isDirectory());
// File Monitoring
// Create a new observer for the folder and add a listener
// that will handle the events in a specific directory and take action.
File parentDir = FileUtils.getFile(PARENT_DIR);
FileAlterationObserver observer = new FileAlterationObserver(parentDir);
observer.addListener(new FileAlterationListenerAdaptor() {
@Override
public void onFileCreate(File file) {
System.out.println("File created: " + file.getName());
}
@Override
public void onFileDelete(File file) {
System.out.println("File deleted: " + file.getName());
}
@Override
public void onDirectoryCreate(File dir) {
System.out.println("Directory created: " + dir.getName());
}
@Override
public void onDirectoryDelete(File dir) {
System.out.println("Directory deleted: " + dir.getName());
}
});
// Add a monior that will check for events every x ms,
// and attach all the different observers that we want.
FileAlterationMonitor monitor = new FileAlterationMonitor(500, observer);
try {
monitor.start();
// After we attached the monitor, we can create some files and directories
// and see what happens!
File newDir = new File(NEW_DIR);
File newFile = new File(NEW_FILE);
newDir.mkdirs();
newFile.createNewFile();
Thread.sleep(1000);
FileDeleteStrategy.NORMAL.delete(newDir);
FileDeleteStrategy.NORMAL.delete(newFile);
Thread.sleep(1000);
monitor.stop();
} catch (IOException e) {
e.printStackTrace();
} catch (InterruptedException e) {
e.printStackTrace();
} catch (Exception e) {
e.printStackTrace();
}
}
}Output
File Monitor example... File monitored: C:\Users\Lilykos\workspace\ApacheCommonsExample\ExampleFolder\exampleFileEntry.txt File name: exampleFileEntry.txt Is the file a directory?: false Directory created: newDir File created: newFile.txt Directory deleted: newDir File deleted: newFile.txt
Let’s take a look on what happened here. We used some classes of the org.apache.commons.io.monitor package, that enable us to create handlers that listen to specific events (in our case, everything that has to do with files, folders, directories etc). In order to achieve that, there are certain steps that need to be taken:
- Create a
Fileobject, that is a reference to the directory that we want to listen to for changes. - Create a
FileAlterationObserverobject, that will observe for those changes. - Add a
FileAlterationListenerAdaptorto the observer using theaddListener()method. You can create the adaptor using various ways, but in our example we used a nested class that implements only some of the methods (the ones we need for the example requirements). - Create a
FileAlterationMonitorand add the observers that you have, as well as the interval (in ms). - Start the monitor using the
start()method and stop it when necessary using thestop()method.
1.3 Filters
Filters can be used in a variety of combinations and ways. Their job is to allow us to easily make distinctions between files and get the ones that satisfy certain criteria. We can also combine filters to perform logical comparisons and get our files much more precisely, without using tedious String comparisons afterwards.
FiltersExample.java
import java.io.File;
import org.apache.commons.io.FileUtils;
import org.apache.commons.io.IOCase;
import org.apache.commons.io.filefilter.AndFileFilter;
import org.apache.commons.io.filefilter.NameFileFilter;
import org.apache.commons.io.filefilter.NotFileFilter;
import org.apache.commons.io.filefilter.OrFileFilter;
import org.apache.commons.io.filefilter.PrefixFileFilter;
import org.apache.commons.io.filefilter.SuffixFileFilter;
import org.apache.commons.io.filefilter.WildcardFileFilter;
public final class FiltersExample {
private static final String PARENT_DIR =
"C:\\Users\\Lilykos\\workspace\\ApacheCommonsExample\\ExampleFolder";
public static void runExample() {
System.out.println("File Filter example...");
// NameFileFilter
// Right now, in the parent directory we have 3 files:
// directory example
// file exampleEntry.txt
// file exampleTxt.txt
// Get all the files in the specified directory
// that are named "example".
File dir = FileUtils.getFile(PARENT_DIR);
String[] acceptedNames = {"example", "exampleTxt.txt"};
for (String file: dir.list(new NameFileFilter(acceptedNames, IOCase.INSENSITIVE))) {
System.out.println("File found, named: " + file);
}
//WildcardFileFilter
// We can use wildcards in order to get less specific results
// ? used for 1 missing char
// * used for multiple missing chars
for (String file: dir.list(new WildcardFileFilter("*ample*"))) {
System.out.println("Wildcard file found, named: " + file);
}
// PrefixFileFilter
// We can also use the equivalent of startsWith
// for filtering files.
for (String file: dir.list(new PrefixFileFilter("example"))) {
System.out.println("Prefix file found, named: " + file);
}
// SuffixFileFilter
// We can also use the equivalent of endsWith
// for filtering files.
for (String file: dir.list(new SuffixFileFilter(".txt"))) {
System.out.println("Suffix file found, named: " + file);
}
// OrFileFilter
// We can use some filters of filters.
// in this case, we use a filter to apply a logical
// or between our filters.
for (String file: dir.list(new OrFileFilter(
new WildcardFileFilter("*ample*"), new SuffixFileFilter(".txt")))) {
System.out.println("Or file found, named: " + file);
}
// And this can become very detailed.
// Eg, get all the files that have "ample" in their name
// but they are not text files (so they have no ".txt" extension.
for (String file: dir.list(new AndFileFilter( // we will match 2 filters...
new WildcardFileFilter("*ample*"), // ...the 1st is a wildcard...
new NotFileFilter(new SuffixFileFilter(".txt"))))) { // ...and the 2nd is NOT .txt.
System.out.println("And/Not file found, named: " + file);
}
}
}
Output
File Filter example... File found, named: example File found, named: exampleTxt.txt Wildcard file found, named: example Wildcard file found, named: exampleFileEntry.txt Wildcard file found, named: exampleTxt.txt Prefix file found, named: example Prefix file found, named: exampleFileEntry.txt Prefix file found, named: exampleTxt.txt Suffix file found, named: exampleFileEntry.txt Suffix file found, named: exampleTxt.txt Or file found, named: example Or file found, named: exampleFileEntry.txt Or file found, named: exampleTxt.txt And/Not file found, named: example
1.4 Comparators
The org.apache.commons.io.comparator package contains classes that allow us to easily compare and sort files and directories. We just need to provide a list of files and, depending on the class, compare them in various ways.
ComparatorExample.java
import java.io.File;
import java.util.Date;
import org.apache.commons.io.FileUtils;
import org.apache.commons.io.IOCase;
import org.apache.commons.io.comparator.LastModifiedFileComparator;
import org.apache.commons.io.comparator.NameFileComparator;
import org.apache.commons.io.comparator.SizeFileComparator;
public final class ComparatorExample {
private static final String PARENT_DIR =
"C:\\Users\\Lilykos\\workspace\\ApacheCommonsExample\\ExampleFolder";
private static final String FILE_1 =
"C:\\Users\\Lilykos\\workspace\\ApacheCommonsExample\\ExampleFolder\\example";
private static final String FILE_2 =
"C:\\Users\\Lilykos\\workspace\\ApacheCommonsExample\\ExampleFolder\\exampleTxt.txt";
public static void runExample() {
System.out.println("Comparator example...");
//NameFileComparator
// Let's get a directory as a File object
// and sort all its files.
File parentDir = FileUtils.getFile(PARENT_DIR);
NameFileComparator comparator = new NameFileComparator(IOCase.SENSITIVE);
File[] sortedFiles = comparator.sort(parentDir.listFiles());
System.out.println("Sorted by name files in parent directory: ");
for (File file: sortedFiles) {
System.out.println("\t"+ file.getAbsolutePath());
}
// SizeFileComparator
// We can compare files based on their size.
// The boolean in the constructor is about the directories.
// true: directory's contents count to the size.
// false: directory is considered zero size.
SizeFileComparator sizeComparator = new SizeFileComparator(true);
File[] sizeFiles = sizeComparator.sort(parentDir.listFiles());
System.out.println("Sorted by size files in parent directory: ");
for (File file: sizeFiles) {
System.out.println("\t"+ file.getName() + " with size (kb): " + file.length());
}
// LastModifiedFileComparator
// We can use this class to find which file was more recently modified.
LastModifiedFileComparator lastModified = new LastModifiedFileComparator();
File[] lastModifiedFiles = lastModified.sort(parentDir.listFiles());
System.out.println("Sorted by last modified files in parent directory: ");
for (File file: lastModifiedFiles) {
Date modified = new Date(file.lastModified());
System.out.println("\t"+ file.getName() + " last modified on: " + modified);
}
// Or, we can also compare 2 specific files and find which one was last modified.
// returns > 0 if the first file was last modified.
// returns 0)
System.out.println("File " + file1.getName() + " was modified last because...");
else
System.out.println("File " + file2.getName() + "was modified last because...");
System.out.println("\t"+ file1.getName() + " last modified on: " +
new Date(file1.lastModified()));
System.out.println("\t"+ file2.getName() + " last modified on: " +
new Date(file2.lastModified()));
}
}
Output
Comparator example... Sorted by name files in parent directory: C:\Users\Lilykos\workspace\ApacheCommonsExample\ExampleFolder\comparator1.txt C:\Users\Lilykos\workspace\ApacheCommonsExample\ExampleFolder\comperator2.txt C:\Users\Lilykos\workspace\ApacheCommonsExample\ExampleFolder\example C:\Users\Lilykos\workspace\ApacheCommonsExample\ExampleFolder\exampleFileEntry.txt C:\Users\Lilykos\workspace\ApacheCommonsExample\ExampleFolder\exampleTxt.txt Sorted by size files in parent directory: example with size (kb): 0 exampleTxt.txt with size (kb): 87 exampleFileEntry.txt with size (kb): 503 comperator2.txt with size (kb): 1458 comparator1.txt with size (kb): 4436 Sorted by last modified files in parent directory: exampleTxt.txt last modified on: Sun Oct 26 14:02:22 EET 2014 example last modified on: Sun Oct 26 23:42:55 EET 2014 comparator1.txt last modified on: Tue Oct 28 14:48:28 EET 2014 comperator2.txt last modified on: Tue Oct 28 14:48:52 EET 2014 exampleFileEntry.txt last modified on: Tue Oct 28 14:53:50 EET 2014 File example was modified last because... example last modified on: Sun Oct 26 23:42:55 EET 2014 exampleTxt.txt last modified on: Sun Oct 26 14:02:22 EET 2014
Let’s see what classes were used here:
NameFileComparator: Compares files according to their name.SizeFileComparator: Compares files according to their size.LastModifiedFileComparator: Compares files according to the date they were last modified.
You should also take notice here, that the comparisons can happen either in whole directories (were they are sorted using the sort() method), or separately for 2 files specifically (using compare()).
1.5 Input
There are various implementations of InputStream in the org.apache.commons.io.input package. We are going to examine one of the most useful, TeeInputStream, which takes as arguments both an InputStream and an OutputStream, and automatically copies the read bytes from the input, to the output. Moreover, by using a third, boolean argument, by closing just the TeeInputStream in the end, the two additional streams close as well.
InputExample.java
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.IOException;
import org.apache.commons.io.FileUtils;
import org.apache.commons.io.input.TeeInputStream;
import org.apache.commons.io.input.XmlStreamReader;
public final class InputExample {
private static final String XML_PATH =
"C:\\Users\\Lilykos\\workspace\\ApacheCommonsExample\\InputOutputExampleFolder\\web.xml";
private static final String INPUT = "This should go to the output.";
public static void runExample() {
System.out.println("Input example...");
XmlStreamReader xmlReader = null;
TeeInputStream tee = null;
try {
// XmlStreamReader
// We can read an xml file and get its encoding.
File xml = FileUtils.getFile(XML_PATH);
xmlReader = new XmlStreamReader(xml);
System.out.println("XML encoding: " + xmlReader.getEncoding());
// TeeInputStream
// This very useful class copies an input stream to an output stream
// and closes both using only one close() method (by defining the 3rd
// constructor parameter as true).
ByteArrayInputStream in = new ByteArrayInputStream(INPUT.getBytes("US-ASCII"));
ByteArrayOutputStream out = new ByteArrayOutputStream();
tee = new TeeInputStream(in, out, true);
tee.read(new byte[INPUT.length()]);
System.out.println("Output stream: " + out.toString());
} catch (IOException e) {
e.printStackTrace();
} finally {
try { xmlReader.close(); }
catch (IOException e) { e.printStackTrace(); }
try { tee.close(); }
catch (IOException e) { e.printStackTrace(); }
}
}
}
Output
Input example... XML encoding: UTF-8 Output stream: This should go to the output.
1.6 Output
Similar to the org.apache.commons.io.input, org.apache.commons.io.output has implementations of OutputStream, that can be used in many situations. A very interesting one is TeeOutputStream, which allows an output stream to be branched, or in other words, we can send an input stream to 2 different outputs.
OutputExample.java
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import org.apache.commons.io.input.TeeInputStream;
import org.apache.commons.io.output.TeeOutputStream;
public final class OutputExample {
private static final String INPUT = "This should go to the output.";
public static void runExample() {
System.out.println("Output example...");
TeeInputStream teeIn = null;
TeeOutputStream teeOut = null;
try {
// TeeOutputStream
ByteArrayInputStream in = new ByteArrayInputStream(INPUT.getBytes("US-ASCII"));
ByteArrayOutputStream out1 = new ByteArrayOutputStream();
ByteArrayOutputStream out2 = new ByteArrayOutputStream();
teeOut = new TeeOutputStream(out1, out2);
teeIn = new TeeInputStream(in, teeOut, true);
teeIn.read(new byte[INPUT.length()]);
System.out.println("Output stream 1: " + out1.toString());
System.out.println("Output stream 2: " + out2.toString());
} catch (IOException e) {
e.printStackTrace();
} finally {
// No need to close teeOut. When teeIn closes, it will also close its
// Output stream (which is teeOut), which will in turn close the 2
// branches (out1, out2).
try { teeIn.close(); }
catch (IOException e) { e.printStackTrace(); }
}
}
}
Output
Output example... Output stream 1: This should go to the output. Output stream 2: This should go to the output.
2. Download the Complete Example
This was an introduction to Apache Commons IO, covering most of the important classes that provide easy solutions to developers. There are many other capabilities in this vast package,but using this intro you get the general idea and a handful of useful tools for your future projects!
You can download the full source code of this example here: ApacheCommonsIOExample.rar
Nice examples
I have a problem where I have to copy 100 million files from one directory to another. Would Commons IO work in such cases?
Thank You.
Very useful examples.
Can we use wildcard in parent directory? if can’t. any other way to use?
FiltersExample.PARENT_DIR =
“C:\\Users\\Lilykos\\*\\ApacheCommonsExample\\*”;
Thanks,
MS