Save This Page
Home » commons-io-current-src » org.apache.commons » io » [javadoc | source]
org.apache.commons.io
public class: IOUtils [javadoc | source]
java.lang.Object
   org.apache.commons.io.IOUtils
General IO stream manipulation utilities.

This class provides static utility methods for input/output operations.

The byte-to-char methods and char-to-byte methods involve a conversion step. Two methods are provided in each case, one that uses the platform default encoding and the other which allows you to specify an encoding. You are encouraged to always specify an encoding because relying on the platform default can lead to unexpected results, for example when moving from development to production.

All the methods in this class that read a stream are buffered internally. This means that there is no cause to use a BufferedInputStream or BufferedReader. The default buffer size of 4K has been shown to be efficient in tests.

Wherever possible, the methods in this class do not flush or close the stream. This is to avoid making non-portable assumptions about the streams' origin and further use. Thus the caller is still responsible for closing streams after use.

Origin of code: Excalibur.

Field Summary
public static final  char DIR_SEPARATOR_UNIX    The Unix directory separator character. 
public static final  char DIR_SEPARATOR_WINDOWS    The Windows directory separator character. 
public static final  char DIR_SEPARATOR    The system directory separator character. 
public static final  String LINE_SEPARATOR_UNIX    The Unix line separator string. 
public static final  String LINE_SEPARATOR_WINDOWS    The Windows line separator string. 
public static final  String LINE_SEPARATOR    The system line separator string. 
Constructor:
 public IOUtils() 
Method from org.apache.commons.io.IOUtils Summary:
closeQuietly,   closeQuietly,   closeQuietly,   closeQuietly,   contentEquals,   contentEquals,   copy,   copy,   copy,   copy,   copy,   copy,   copyLarge,   copyLarge,   lineIterator,   lineIterator,   readLines,   readLines,   readLines,   toByteArray,   toByteArray,   toByteArray,   toByteArray,   toCharArray,   toCharArray,   toCharArray,   toInputStream,   toInputStream,   toString,   toString,   toString,   toString,   toString,   write,   write,   write,   write,   write,   write,   write,   write,   write,   write,   write,   write,   writeLines,   writeLines,   writeLines
Methods from java.lang.Object:
equals,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.apache.commons.io.IOUtils Detail:
 public static  void closeQuietly(Reader input) 
    Unconditionally close an Reader.

    Equivalent to Reader#close() , except any exceptions will be ignored. This is typically used in finally blocks.

 public static  void closeQuietly(Writer output) 
    Unconditionally close a Writer.

    Equivalent to Writer#close() , except any exceptions will be ignored. This is typically used in finally blocks.

 public static  void closeQuietly(InputStream input) 
    Unconditionally close an InputStream.

    Equivalent to InputStream#close() , except any exceptions will be ignored. This is typically used in finally blocks.

 public static  void closeQuietly(OutputStream output) 
    Unconditionally close an OutputStream.

    Equivalent to OutputStream#close() , except any exceptions will be ignored. This is typically used in finally blocks.

 public static boolean contentEquals(InputStream input1,
    InputStream input2) throws IOException 
    Compare the contents of two Streams to determine if they are equal or not.

    This method buffers the input internally using BufferedInputStream if they are not already buffered.

 public static boolean contentEquals(Reader input1,
    Reader input2) throws IOException 
    Compare the contents of two Readers to determine if they are equal or not.

    This method buffers the input internally using BufferedReader if they are not already buffered.

 public static int copy(InputStream input,
    OutputStream output) throws IOException 
    Copy bytes from an InputStream to an OutputStream.

    This method buffers the input internally, so there is no need to use a BufferedInputStream.

    Large streams (over 2GB) will return a bytes copied value of -1 after the copy has completed since the correct number of bytes cannot be returned as an int. For large streams use the copyLarge(InputStream, OutputStream) method.

 public static  void copy(InputStream input,
    Writer output) throws IOException 
    Copy bytes from an InputStream to chars on a Writer using the default character encoding of the platform.

    This method buffers the input internally, so there is no need to use a BufferedInputStream.

    This method uses InputStreamReader .

 public static int copy(Reader input,
    Writer output) throws IOException 
    Copy chars from a Reader to a Writer.

    This method buffers the input internally, so there is no need to use a BufferedReader.

    Large streams (over 2GB) will return a chars copied value of -1 after the copy has completed since the correct number of chars cannot be returned as an int. For large streams use the copyLarge(Reader, Writer) method.

 public static  void copy(Reader input,
    OutputStream output) throws IOException 
    Copy chars from a Reader to bytes on an OutputStream using the default character encoding of the platform, and calling flush.

    This method buffers the input internally, so there is no need to use a BufferedReader.

    Due to the implementation of OutputStreamWriter, this method performs a flush.

    This method uses OutputStreamWriter .

 public static  void copy(InputStream input,
    Writer output,
    String encoding) throws IOException 
    Copy bytes from an InputStream to chars on a Writer using the specified character encoding.

    This method buffers the input internally, so there is no need to use a BufferedInputStream.

    Character encoding names can be found at IANA.

    This method uses InputStreamReader .

 public static  void copy(Reader input,
    OutputStream output,
    String encoding) throws IOException 
    Copy chars from a Reader to bytes on an OutputStream using the specified character encoding, and calling flush.

    This method buffers the input internally, so there is no need to use a BufferedReader.

    Character encoding names can be found at IANA.

    Due to the implementation of OutputStreamWriter, this method performs a flush.

    This method uses OutputStreamWriter .

 public static long copyLarge(InputStream input,
    OutputStream output) throws IOException 
    Copy bytes from a large (over 2GB) InputStream to an OutputStream.

    This method buffers the input internally, so there is no need to use a BufferedInputStream.

 public static long copyLarge(Reader input,
    Writer output) throws IOException 
    Copy chars from a large (over 2GB) Reader to a Writer.

    This method buffers the input internally, so there is no need to use a BufferedReader.

 public static LineIterator lineIterator(Reader reader) 
    Return an Iterator for the lines in a Reader.

    LineIterator holds a reference to the open Reader specified here. When you have finished with the iterator you should close the reader to free internal resources. This can be done by closing the reader directly, or by calling LineIterator#close() or LineIterator#closeQuietly(LineIterator) .

    The recommended usage pattern is:

    try {
    LineIterator it = IOUtils.lineIterator(reader);
    while (it.hasNext()) {
    String line = it.nextLine();
    /// do something with line
    }
    } finally {
    IOUtils.closeQuietly(reader);
    }
    
 public static LineIterator lineIterator(InputStream input,
    String encoding) throws IOException 
    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. This can be done by closing the stream directly, or by calling LineIterator#close() or LineIterator#closeQuietly(LineIterator) .

    The recommended usage pattern is:

    try {
    LineIterator it = IOUtils.lineIterator(stream, "UTF-8");
    while (it.hasNext()) {
    String line = it.nextLine();
    /// do something with line
    }
    } finally {
    IOUtils.closeQuietly(stream);
    }
    
 public static List readLines(InputStream input) throws IOException 
    Get the contents of an InputStream as a list of Strings, one entry per line, using the default character encoding of the platform.

    This method buffers the input internally, so there is no need to use a BufferedInputStream.

 public static List readLines(Reader input) throws IOException 
    Get the contents of a Reader as a list of Strings, one entry per line.

    This method buffers the input internally, so there is no need to use a BufferedReader.

 public static List readLines(InputStream input,
    String encoding) throws IOException 
    Get the contents of an InputStream as a list of Strings, one entry per line, using the specified character encoding.

    Character encoding names can be found at IANA.

    This method buffers the input internally, so there is no need to use a BufferedInputStream.

 public static byte[] toByteArray(InputStream input) throws IOException 
    Get the contents of an InputStream as a byte[].

    This method buffers the input internally, so there is no need to use a BufferedInputStream.

 public static byte[] toByteArray(Reader input) throws IOException 
    Get the contents of a Reader as a byte[] using the default character encoding of the platform.

    This method buffers the input internally, so there is no need to use a BufferedReader.

 public static byte[] toByteArray(String input) throws IOException 
Deprecated! Use - String#getBytes()

    Get the contents of a String as a byte[] using the default character encoding of the platform.

    This is the same as String#getBytes() .

 public static byte[] toByteArray(Reader input,
    String encoding) throws IOException 
    Get the contents of a Reader as a byte[] using the specified character encoding.

    Character encoding names can be found at IANA.

    This method buffers the input internally, so there is no need to use a BufferedReader.

 public static char[] toCharArray(InputStream is) throws IOException 
    Get the contents of an InputStream as a character array using the default character encoding of the platform.

    This method buffers the input internally, so there is no need to use a BufferedInputStream.

 public static char[] toCharArray(Reader input) throws IOException 
    Get the contents of a Reader as a character array.

    This method buffers the input internally, so there is no need to use a BufferedReader.

 public static char[] toCharArray(InputStream is,
    String encoding) throws IOException 
    Get the contents of an InputStream as a character array using the specified character encoding.

    Character encoding names can be found at IANA.

    This method buffers the input internally, so there is no need to use a BufferedInputStream.

 public static InputStream toInputStream(String input) 
    Convert the specified string to an input stream, encoded as bytes using the default character encoding of the platform.
 public static InputStream toInputStream(String input,
    String encoding) throws IOException 
    Convert the specified string to an input stream, encoded as bytes using the specified character encoding.

    Character encoding names can be found at IANA.

 public static String toString(InputStream input) throws IOException 
    Get the contents of an InputStream as a String using the default character encoding of the platform.

    This method buffers the input internally, so there is no need to use a BufferedInputStream.

 public static String toString(Reader input) throws IOException 
    Get the contents of a Reader as a String.

    This method buffers the input internally, so there is no need to use a BufferedReader.

 public static String toString(byte[] input) throws IOException 
Deprecated! Use - String#String(byte[])

    Get the contents of a byte[] as a String using the default character encoding of the platform.
 public static String toString(InputStream input,
    String encoding) throws IOException 
    Get the contents of an InputStream as a String using the specified character encoding.

    Character encoding names can be found at IANA.

    This method buffers the input internally, so there is no need to use a BufferedInputStream.

 public static String toString(byte[] input,
    String encoding) throws IOException 
Deprecated! Use - String#String(byte[],String)

    Get the contents of a byte[] as a String using the specified character encoding.

    Character encoding names can be found at IANA.

 public static  void write(byte[] data,
    OutputStream output) throws IOException 
    Writes bytes from a byte[] to an OutputStream.
 public static  void write(byte[] data,
    Writer output) throws IOException 
    Writes bytes from a byte[] to chars on a Writer using the default character encoding of the platform.

    This method uses String#String(byte[]) .

 public static  void write(char[] data,
    Writer output) throws IOException 
    Writes chars from a char[] to a Writer using the default character encoding of the platform.
 public static  void write(char[] data,
    OutputStream output) throws IOException 
 public static  void write(String data,
    Writer output) throws IOException 
    Writes chars from a String to a Writer.
 public static  void write(String data,
    OutputStream output) throws IOException 
    Writes chars from a String to bytes on an OutputStream using the default character encoding of the platform.

    This method uses String#getBytes() .

 public static  void write(StringBuffer data,
    Writer output) throws IOException 
    Writes chars from a StringBuffer to a Writer.
 public static  void write(StringBuffer data,
    OutputStream output) throws IOException 
    Writes chars from a StringBuffer to bytes on an OutputStream using the default character encoding of the platform.

    This method uses String#getBytes() .

 public static  void write(byte[] data,
    Writer output,
    String encoding) throws IOException 
    Writes bytes from a byte[] to chars on a Writer using the specified character encoding.

    Character encoding names can be found at IANA.

    This method uses String#String(byte[], String) .

 public static  void write(char[] data,
    OutputStream output,
    String encoding) throws IOException 
 public static  void write(String data,
    OutputStream output,
    String encoding) throws IOException 
    Writes chars from a String to bytes on an OutputStream using the specified character encoding.

    Character encoding names can be found at IANA.

    This method uses String#getBytes(String) .

 public static  void write(StringBuffer data,
    OutputStream output,
    String encoding) throws IOException 
    Writes chars from a StringBuffer to bytes on an OutputStream using the specified character encoding.

    Character encoding names can be found at IANA.

    This method uses String#getBytes(String) .

 public static  void writeLines(Collection lines,
    String lineEnding,
    OutputStream output) throws IOException 
    Writes the toString() value of each item in a collection to an OutputStream line by line, using the default character encoding of the platform and the specified line ending.
 public static  void writeLines(Collection lines,
    String lineEnding,
    Writer writer) throws IOException 
    Writes the toString() value of each item in a collection to a Writer line by line, using the specified line ending.
 public static  void writeLines(Collection lines,
    String lineEnding,
    OutputStream output,
    String encoding) throws IOException 
    Writes the toString() value of each item in a collection to an OutputStream line by line, using the specified character encoding and the specified line ending.

    Character encoding names can be found at IANA.