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, Returnstrueif they are equal andfalseif they are not. It has another variant to support InputStream objects. There is also another methodcontentEqualsIgnoreEOL(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
- 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. - 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 methodIOUtils.copyLarge()to support copying Large InputStream or Reader objects (more than 2GB). - 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,URIandURL, but for all these variations you are required to specify an encoding. - 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 thereadLines()method. - 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.
- 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.
- The
LineIteratorclass andlineIterator()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). - 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); - The
IOUtils.contentEqualsIgnoreEOL()methodfr=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. TheIOUtils.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 theIOUtils.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.
You can download the full source code of this example here : IOUtilsExample.zip
