User guide – Apache Commons IO (original) (raw)

Commons-IO containsutility classes,endian classes,line iterator,file filters,file comparators andstream implementations.

For a more detailed descriptions, take a look at theJavadocs.

Utility classes

IOUtils

IOUtils contains utility methods dealing with reading, writing and copying. The methods work on InputStream, OutputStream, Reader and Writer.

As an example, consider the task of reading bytes from a URL, and printing them. This would typically be done like this:


 InputStream in = new URL("https://commons.apache.org").openStream();
 try {
   InputStreamReader inR = new InputStreamReader(in);
   BufferedReader buf = new BufferedReader(inR);
   String line;
   while ((line = buf.readLine()) != null) {
     System.out.println(line);
   }
 } finally {
   in.close();
 }

With the IOUtils class, that could be done with:


 InputStream in = new URL("https://commons.apache.org").openStream();
 try {
   System.out.println(IOUtils.toString(in));
 } finally {
   IOUtils.closeQuietly(in);
 }

In certain application domains, such IO operations are common, and this class can save a great deal of time. And you can rely on well-tested code.

For utility code such as this, flexibility and speed are of primary importance. However you should also understand the limitations of this approach. Using the above technique to read a 1GB file would result in an attempt to create a 1GB String object!

FileUtils

The FileUtils class contains utility methods for working with File objects. These include reading, writing, copying and comparing files.

For example to read an entire file line by line you could use:


 File file = new File("/commons/io/project.properties");
 List lines = FileUtils.readLines(file, "UTF-8");

FilenameUtils

The FilenameUtils class contains utility methods for working with filenames without using File objects. The class aims to be consistent between Unix and Windows, to aid transitions between these environments (such as moving from development to production).

For example to normalize a filename removing double dot segments:


 String filename = "C:/commons/io/../lang/project.xml";
 String normalized = FilenameUtils.normalize(filename);
 // result is "C:/commons/lang/project.xml"

FileSystemUtils

The FileSystemUtils class contains utility methods for working with the file system to access functionality not supported by the JDK. Currently, the only method is to get the free space on a drive. Note that this uses the command line, not native code.

For example to find the free space on a drive:


 long freeSpace = FileSystemUtils.freeSpace("C:/");

Endian classes

Different computer architectures adopt different conventions for byte ordering. In so-called "Little Endian" architectures (eg Intel), the low-order byte is stored in memory at the lowest address, and subsequent bytes at higher addresses. For "Big Endian" architectures (eg Motorola), the situation is reversed.

There are two classes in this package of relevance:

For more information, seehttps://www.cs.umass.edu/~verts/cs32/endian.html

Line iterator

The org.apache.commons.io.LineIterator class provides a flexible way for working with a line-based file. An instance can be created directly, or via factory methods onFileUtils or IOUtils. The recommended usage pattern is:


 LineIterator it = FileUtils.lineIterator(file, "UTF-8");
 try {
   while (it.hasNext()) {
     String line = it.nextLine();
     /// do something with line
   }
 } finally {
   LineIterator.closeQuietly(iterator);
 }

File filters

The org.apache.commons.io.filefilter package defines an interface (IOFileFilter) that combines both java.io.FileFilter andjava.io.FilenameFilter. Besides that the package offers a series of ready-to-use implementations of the IOFileFilter interface including implementation that allow you to combine other such filters. These filters can be used to list files or in FileDialog, for example.

See thefilefilter package Javadoc for more details.

File comparators

The org.apache.commons.io.comparator package provides a number of java.util.Comparator implementations for java.io.File. These comparators can be used to sort lists and arrays of files, for example.

See thecomparator package Javadoc for more details.

Safe Deserialization

You can safely deserialize any input using a ValidatingObjectInputStream.

Here is the only way to safely read a HashMap of String keys and Integer values:


        ValidatingObjectInputStream vois = ValidatingObjectInputStream.builder()
          .setPath(Paths.get("MyFile.ser"))
          .get();
        vois.accept(HashMap.class, Number.class, Integer.class);
        HashMap<String, Integer> map2 = (HashMap<String, Integer>) vois.readObject();

Here is an example that performs a roundtrip:


        // Data
        final HashMap<String, Integer> map1 = new HashMap<>();
        map1.put("1", 1);
        // Write
        final byte[] byteArray;
        try (ByteArrayOutputStream baos = new ByteArrayOutputStream();
                final ObjectOutputStream oos = new ObjectOutputStream(baos)) {
            oos.writeObject(map1);
            oos.flush();
            byteArray = baos.toByteArray();
        }
        // Read
        try (ByteArrayInputStream bais = new ByteArrayInputStream(byteArray);
                ValidatingObjectInputStream vois = ValidatingObjectInputStream.builder().setInputStream(bais).get()) {
            // String.class is automatically accepted
            vois.accept(HashMap.class, Number.class, Integer.class);
            final HashMap<String, Integer> map2 = (HashMap<String, Integer>) vois.readObject();
            assertEquals(map1, map2);
        }
        // Reusing a configuration
        final ObjectStreamClassPredicate predicate = new ObjectStreamClassPredicate()
                .accept(HashMap.class, Number.class, Integer.class);
        try (ByteArrayInputStream bais = new ByteArrayInputStream(byteArray);
                ValidatingObjectInputStream vois = ValidatingObjectInputStream.builder()
                        .setPredicate(predicate)
                        .setInputStream(bais)
                        .get()) {
            // String.class is automatically accepted
            final HashMap<String, Integer> map2 = (HashMap<String, Integer>) vois.readObject();
            assertEquals(map1, map2);
        }

Streams

The org.apache.commons.io.input andorg.apache.commons.io.output packages contain various useful implementations of streams. These include:

See theinput oroutput package Javadoc for more details.