Core Java

Apache Commons IO Tutorial: A beginner’s guide

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:

  1. Create a File object, that is a reference to the directory that we want to listen to for changes.
  2. Create a FileAlterationObserver object, that will observe for those changes.
  3. Add a FileAlterationListenerAdaptor to the observer using the addListener() 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).
  4. Create a FileAlterationMonitor and add the observers that you have, as well as the interval (in ms).
  5. Start the monitor using the start() method and stop it when necessary using the stop() 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:

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.inputorg.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!

Download
You can download the full source code of this example here: ApacheCommonsIOExample.rar

Ilias Koutsakis

Ilias has graduated from the Department of Informatics and Telecommunications of the National and Kapodistrian University of Athens. He is interested in all aspects of software engineering, particularly data mining, and loves the challenge of working with new technologies. He is pursuing the dream of clean and readable code on a daily basis.
Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

2 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Rahul
Rahul
9 years ago

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.

Karthikeyan M
Karthikeyan M
4 years ago

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

Back to top button