IOUtils

org.apache.commons.io.IOUtils Example

In this example we are going to elaborate the use of the IOUtils class in the package: ‘org.apache.commons.io’, as the package name says it is a part of Apache Commons IO. All members functions of this class deals with Input – Output streams Manipulations, and it really helps to write programs which deals with such matters. The methods of this class as other classes of Apache Commons are wrappers for very important tasks regarding IO Manipulation so the code which implemented those methods becomes significantly smaller, cleaner and understandable comparing to other programs where those functionalities are written manually.

1. The IOUtils Class Overview, Fields and Methods

All the Member Fields and Methods of the IOUtils class is static, so you are never required to create an object of the IOUtils class in standard programming, rather you will use it by the class name and appropiate method names. Such as: IOUtils.method1().

1.1 IOUtils Fields

  • static char DIR_SEPARATOR: This field contains the system directory separator character.
  • static char DIR_SEPARATOR_UNIX : This field contains the Unix directory separator character.
  • static char DIR_SEPARATOR_WINDOWS : This field contains the Windows directory separator character.
  • static String LINE_SEPARATOR : This field contains the System Line separator String.
  • static String LINE_SEPARATOR_UNIX : This field contains the Unix Line separator String.
  • static String LINE_SEPARATOR_WINDOWS : This field contains the Windows Line separator String.

1.2 IOUtils Methods Summary

Here we will discuss with some of the very important methods found inside the IOUtils class. All the methods in this class that deals with an InputStream are buffered internally, so we need not to use a BufferedReader or a BufferedInputStream. The default buffer size is 4K, however in some cases we can provide our self-defined buffer size.

  • static void closeQuietly(Closeable closeable) : It closes a closable object unconditionally (Whether let it be null), without any exception. It also has many variations to support all the InputStreams, OutputStream Reader and Writer to close.
  • static boolean contentEquals(Reader inp1,Reader inp2) : This method checks the equality between the contents of the two Reader objects, Returns true if they are equal and false if they are not. It has another variant to support InputStream objects. There is also another method contentEqualsIgnoreEOL(Reader r1,Rrader r2) which compares the equality without looking at the Line Ending String.
  • static int copy(InputStream inp,OutputStream outp) : This method copies the contents (bytes) from an InputStream object to an OutputStream object. Returns the number of bytes copied. It has many other variants to support Reader and Writer objects.
  • static LineIterator lineIterator(InputStream input,String enc) : This method Return an Iterator for the lines in an InputStream, using the character encoding specified (or default encoding if null). LineIterator holds a reference to the open InputStream specified here. When you have finished with the iterator you should close the stream to free internal resources. The encoding can also be passed as a Charset object. It also has a variant for the Reader objects.
  • static List<String> readLines(InputStream inp,String enc) : This method returns the contents of the provided InputStream as a list of Strings, one entry per line. It internally converts the bytes of the InputStream into List of Strings using the specified character encoding. The encoding can also be passed as a Charset object.
  • static List<String> readLines(Reader inp) : This method returns the contents of the provided Reader as a list of Strings, one entry per line.
  • static BufferedReader toBufferedReader(Reader rdr, int size) : This method returns a BufferedReader object for the provided Reader object. The size parameter can be skipped.
  • static InputStream toInputStream(CharSequence inp, String enc) : This method creates an InputStream object by converting the specified CharSequence using the specified encoding. It also has a variant to support String as the 1st parameter(inp). The encoding can also be passed as a Charset object.
  • static String toString(Reader inp) : Returns the contents of the Reader object as a String. It has other variants to support the InputStream, URI and URL objects, in tht case encoding should also be passed as the second argument.
  • static void write(String data,Writer outp) : This method writes the data in the char array to the specified Writer object. This method also has two variants to support the CharSequence and char[] as the 1st parameter (data) and OutputStream as the second one (in that case we also have to specify the encoding).
  • static void writeLines(Collection<?> lines,String lineEnding,Writer outp) : This method writes the toString() value for each item in the collection to the Writer object line by line (blank line if an entry is null), using the specified lineEnding String (LINE_SEPARATOR String, uses the default if null is passed).

 

1.3 Methods Usage

  1. The IOUtils.toInputStream() method
    //We can create an InputStream object from a String as follows
    InputStream is=IOUtils.toInputStream("This is a String","utf-8");
    

    The IOUtils.toInputStream() method creates an InputStream for the String "This is a String" and returns the object.

  2. The IOUtils.copy() method
    //We can copy the contents of an InputStream object to an OutputStream object as follows
    OutputStream o=new FileOutputStream("D:\\Java_Workspace\\IOUtilsExample\\abc.txt");
    int bytes=IOUtils.copy(is, o);
    out.println("File Written with "+bytes+" bytes");
    IOUtils.closeQuietly(o);
    

    Note: The IOUtils.copy() method has many variations, here I am showing the most usefull and common one. Also there is a method IOUtils.copyLarge() to support copying Large InputStream or Reader objects (more than 2GB).

  3. The IOUtils.toString() method
    //We can convert a Reader object to a String using IOUtils.toString(Reader r) as below
    FileReader fr3=new FileReader("D:\\Java_Workspace\\IOUtilsExample\\abc.txt");
    String st=IOUtils.toString(fr3);
    

    Note: As stated before the toString() method in IOUtils class has many other variations to support InputStream, URI and URL, but for all these variations you are required to specify an encoding.

  4. The IOUtils.read() method
    This method reads bytes from an input stream ino the provided buffer (byte[]).

    //We can get the contents of an InputStream as a byte array as below
    FileInputStream fin=new FileInputStream("D:\\Java_Workspace\\IOUtilsExample\\abc.txt");
    byte[] buf=new byte[100]
    int len=IOUtils.read(fin,buf);
    out.println("The Length of Input Stream : "+len);
    

    Output will be like that: The Length of Input Stream : 82
    After that we may perform our regular operations on the byte array.
    Note: however in some cases this method may be useful though in most cases I would suggest the readLines() method.

  5. The IOUtils.readLines() method
    //We can get the contents of an InputStream as a list of Strings as below
    FileInputStream fin=new FileInputStream("D:\\Java_Workspace\\IOUtilsExample\\abc.txt");
    List ls=IOUtils.readLines(fin,"utf-8");
    

    After that we may perform our regular operations on the list.

  6. The IOUtils.writeLines() method
    //We write lines from a collection to a Writer object as follows
    Writer swr=new StringWriter();
    IOUtils.writeLines(ls, IOUtils.LINE_SEPARATOR_WINDOWS, swr);   
    

    Note: Here I have used the IOUtils.LINE_SEPARATOR_WINDOWS string as the lineEnding string as I am working in Windows enviroment, you should specify the proper line separator String for your platform pass null to use System default line separator String.

  7. The LineIterator class and lineIterator() method
    //We can get the LineIterator for an InputStream as below
    FileInputStream fin=new FileInputStream("D:\\Java_Workspace\\IOUtilsExample\\abc.txt");
    LineIterator lt=IOUtils.lineIterator(fin, "utf-8");
    while(lt.hasNext())
    {
    	   String line=lt.nextLine();
     	   //Perform the Regular Processing with the String
    }
    //When you are done you have to close either the LineIterator object
    lt.close();
    //or the InputStream / Reader object.
    

    Note: you can also close a LineIterator object using LineIterator.closeQuietly(LineIterator li).

  8. The IOUtils.write() method
    //We can use  the IOUtils.write() method to write String to a Writer or OutputStream object
    FileWriter fw=new FileWriter("D:\\Java_Workspace\\IOUtilsExample\\abc2.txt");
    IOUtils.write("This String\n Will be written on the file", fw);
    
  9. The IOUtils.contentEqualsIgnoreEOL() method
    fr=new FileReader("D:\\Java_Workspace\\IOUtilsExample\\abc.txt");
    fr2=new FileReader("D:\\Java_Workspace\\IOUtilsExample\\abc2.txt");
    	       
          if(IOUtils.contentEqualsIgnoreEOL(fr, fr2))
    	    	   out.println("File Copied Successfully");
          else
    	    	   out.println("There Must be an Error in Copying the Files");
    	       
    

    Note: While using InputStream objects you will use the IOUtils.contentEquals() method as this one without any doubt. The IOUtils.contentEquals() method for Reader objects may produce unstable outputs if the lineEnding Strings are different for the two objects, so while using Reader objects my recomendation is to use the IOUtils.contentEqualsIgnoreEOL() method, unless you really bother for the lineEnding Strings.

2 IOUtils Example

The Complete code IOUtilsExample.java

 
package IOUtilsExample;


import java.io.*;
import java.util.List;

import org.apache.commons.io.IOUtils;
import org.apache.commons.io.LineIterator;

public class IOUtilsExample {
	public static void main(String args[]){
		//Declaring all Objects
		
		BufferedReader in = null;
		PrintWriter out = null;
		InputStream is = null;
		FileInputStream fin=null,fin2=null;
		StringWriter swr=null;
		LineIterator lt=null;
		FileWriter fw=null;
		FileReader fr=null,fr2=null;
		
	   try {
	       in=IOUtils.toBufferedReader(new InputStreamReader(System.in));
		   out = new PrintWriter(System.out,true);
	       
		   
		   //Creating InputStream from String.
		   out.println("Enter Something. Enter stop to stop");
	       String s="";
	       String s1;
	       do{
	    	   s1=in.readLine();
	    	   if((s1.compareToIgnoreCase("stop"))!=0)
	    		   s+=s1+"\n";
	       }while((s1.compareToIgnoreCase("stop"))!=0);
	       is=IOUtils.toInputStream(s,"utf-8");
	       
	       //Writing to file by Copying the Contents of 
		   //InputStream to FileOutputStream
	       OutputStream o=new FileOutputStream("D:\\Java_Workspace\\IOUtilsExample\\abc.txt");
	       int bytes=IOUtils.copy(is, o);
	       out.println("File Written with "+bytes+" bytes");
	       IOUtils.closeQuietly(o);
	       
	       //Printing the File Containings
	       //by using the LineIterator
	       out.println("\n Printing The Containings:-");
	       fin=new FileInputStream("D:\\Java_Workspace\\IOUtilsExample\\abc.txt");
	       lt=IOUtils.lineIterator(fin, "utf-8");
	       while(lt.hasNext())
	       {
	    	   String line=lt.nextLine();
	    	   out.println(line);
	       }
	       lt.close();
	       
	       //Another way to print the file containings (Using StringWriter)
	       out.println("\n Printing The Containings 2nd Way (Using StringWriter):-");
	       fin2=new FileInputStream("D:\\Java_Workspace\\IOUtilsExample\\abc.txt");
	       List ls=IOUtils.readLines(fin2,"utf-8");
	       swr=new StringWriter();
	       IOUtils.writeLines(ls, IOUtils.LINE_SEPARATOR_WINDOWS, swr);   
	       	       
	       String fcontain=swr.toString();
	       out.println(fcontain);
	       //3rd way to print the file containings (using IOUtils.toString() )
	       out.println("\n Printing The Containings 3rd Way (Using IOUtils.toString()):-");
	       FileReader fr3=new FileReader("D:\\Java_Workspace\\IOUtilsExample\\abc.txt");
	       String st=IOUtils.toString(fr3);
	       IOUtils.closeQuietly(fr3);
	       out.println(st);
	       //Copying the File
	       fw=new FileWriter("D:\\Java_Workspace\\IOUtilsExample\\abc2.txt");
	       IOUtils.write(fcontain, fw);
	       
	       
	       IOUtils.closeQuietly(fw);
	       
	       //Checking the Equality of newly created File with the Older One
	       fr2=new FileReader("D:\\Java_Workspace\\IOUtilsExample\\abc2.txt");
	       fr=new FileReader("D:\\Java_Workspace\\IOUtilsExample\\abc.txt");
	       
	       if(IOUtils.contentEqualsIgnoreEOL(fr, fr2))
	    	   out.println("File Copied Successfully");
	       else
	    	   out.println("There Must be an Error in Copying the Files");
	       
	       
	       //We may try to close all Objects here
	       //or Skip to the finally block.
	   } catch (Exception e) {
	       e.printStackTrace(out);
	   } finally {
	       
		   //The closeQuetly() method doesn't throw any exceptions.
		   
		   IOUtils.closeQuietly(in);
	       IOUtils.closeQuietly(is);
	       IOUtils.closeQuietly(fin);
		   IOUtils.closeQuietly(out);
		   IOUtils.closeQuietly(fr);
		   IOUtils.closeQuietly(swr);
		   IOUtils.closeQuietly(fin2);
		   IOUtils.closeQuietly(fr2);
	   }
	}
}

Output

Enter Something. Enter stop to stop
Writing for abc.txt file...
while running IOUtilsExample.java
by Rivu Chakraborty
stop
File Written with 82 bytes

 Printing The Containings:-
Writing for abc.txt file...
while running IOUtilsExample.java
by Rivu Chakraborty

 Printing The Containings 2nd Way (Using StringWriter):-
Writing for abc.txt file...
while running IOUtilsExample.java
by Rivu Chakraborty


 Printing The Containings 3rd Way (Using IOUtils.toString()):-
Writing for abc.txt file...
while running IOUtilsExample.java
by Rivu Chakraborty

File Copied Successfully

2.1 Explanation

In the code above what I have done is that: Declared all objects at the very start before the try block (to make the objects available to the finally block), but also declared and used some of the objects inside the try block which we don’t need in the finally block. Initialised and used the objects wherever required.

Then I have created the BufferedReader object (required for console input) using the IOUtils.toBufferedReader(Reader reader) method.

After that I took some lines of input from the console read it as String and then converted it to the InputStream using IOUtils.toInputStream(String inp,String enc) method.

After this what I did is to copy the contents of the InputStream to an OutputStream (FileOutputStream) using IOUtils.copy(InputStream in,OutputStream op), in that way a file had been created with the InputStream’s contents.

Then I printed the contents of the file in three separate ways, i.e. by using the LineIterator, by using the ReadLines and WriteLines methods and lastly by using the toString() method. I also created another file with same containings using the IOUtils.write(String data,Writer outp) method, and then checked the equality using the IOUtils.contentEqualsIgnoreEOL(Reader inp1,Reader inp2) method.

In this approach I tried to use the most of the important methods of the IOUtils class.

3 Download The Example

This was an example for IOUtils in Apache Commons IO.

Download
You can download the full source code of this example here : IOUtilsExample.zip

Rivu Chakraborty

Rivu Chakraborty is a Google Certified Android Developer, Sr. Tech Member of Institute of Engineers (India), he also have certifications on Scrum. He is also an author of multiple books on Kotlin, Reactive Programming, Functional Programming and Android Development, published by renowned publication houses. Having total 5+ years of experience he is presently working as a Sr. Software Engineer (Android) at Indus Net Technologies Pvt. Ltd. Rivu Chakraborty considers himself a Kotlin and Android enthusiast and a Kotlin evangelist. He has been using Kotlin since December 2015, so he has around 2 years' experience in Kotlin. As part of his mission to expand the use and knowledge of the Kotlin Language as much as possible, he created the KotlinKolkata User Group, one of the most active Kotlin user groups throughout the world and he is a Founder Organizer of KotlinKolkata. He is also an active member of GDG Kolkata and gives talks at GDG Kolkata Meetups.
Subscribe
Notify of
guest

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

0 Comments
Inline Feedbacks
View all comments
Back to top button