Package org.apache.directory.api.util

Class IOUtils

java.lang.Object

org.apache.directory.api.util.IOUtils

public final class IOUtils
extends Object

This code comes from Apache commons.io library. Origin of code: Excalibur, Alexandria, Tomcat, Commons-Utils.

Author:

Apache Directory Project

Method Summary

Modifier and Type	Method	Description
static void	closeQuietly(Closeable closeable)	Closes a Closeable unconditionally.
static void	closeQuietly(Closeable... closeables)	Closes a Closeable unconditionally.
static void	closeQuietly(InputStream input)	Closes an InputStream unconditionally.
static int	copy(InputStream input, OutputStream output)	Copies bytes from an InputStream to an OutputStream.
static long	copy(InputStream input, OutputStream output, int bufferSize)	Copies bytes from an InputStream to an OutputStream using an internal buffer of the given size.
static void	copy(InputStream input, Writer output, Charset inputEncoding)	Copies bytes from an InputStream to chars on a Writer using the specified character encoding.
static int	copy(Reader input, Writer output)	Copies chars from a Reader to a Writer.
static long	copyLarge(InputStream input, OutputStream output)	Copies bytes from a large (over 2GB) InputStream to an OutputStream.
static long	copyLarge(InputStream input, OutputStream output, byte[] buffer)	Copies bytes from a large (over 2GB) InputStream to an OutputStream.
static long	copyLarge(Reader input, Writer output)	Copies chars from a large (over 2GB) Reader to a Writer.
static long	copyLarge(Reader input, Writer output, char[] buffer)	Copies chars from a large (over 2GB) Reader to a Writer.
static List<String>	readLines(InputStream input, Charset encoding)	Gets the contents of an InputStream as a list of Strings, one entry per line, using the specified character encoding.
static List<String>	readLines(Reader input)	Gets the contents of a Reader as a list of Strings, one entry per line.
static BufferedReader	toBufferedReader(Reader reader)	Returns the given reader if it is a BufferedReader, otherwise creates a BufferedReader from the given reader.
static byte[]	toByteArray(InputStream input, int size)	Gets the contents of an InputStream as a byte[].
static byte[]	toByteArray(InputStream input, long size)	Gets contents of an InputStream as a byte[].
static Charset	toCharset(String charset)	Returns a Charset for the named charset.
static Charset	toCharset(Charset charset)	Returns the given Charset or the default Charset if the given Charset is null.
static String	toString(InputStream input, Charset encoding)	Gets the contents of an InputStream as a String using the specified character encoding.
static void	write(String data, OutputStream output, Charset encoding)	Writes chars from a String to bytes on an OutputStream using the specified character encoding.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

closeQuietly

public static void closeQuietly(InputStream input)

Closes an InputStream unconditionally.

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

Example code:

   byte[] data = new byte[1024];
   InputStream in = null;
   try {
       in = new FileInputStream("foo.txt");
       in.read(data);
       in.close(); //close errors are handled
   } catch (Exception e) {
       // error handling
   } finally {
       IOUtils.closeQuietly(in);
   }
 

Parameters:

input - the InputStream to close, may be null or already closed

closeQuietly

public static void closeQuietly(Closeable... closeables)

Closes a Closeable unconditionally.

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

Example code:

 Closeable closeable = null;
 try {
     closeable = new FileReader("foo.txt");
     // process closeable
     closeable.close();
 } catch (Exception e) {
     // error handling
 } finally {
     IOUtils.closeQuietly(closeable);
 }
 

Closing all streams:

 try {
     return IOUtils.copy(inputStream, outputStream);
 } finally {
     IOUtils.closeQuietly(inputStream);
     IOUtils.closeQuietly(outputStream);
 }
 

Parameters:

closeables - the objects to close, may be null or already closed

Since:

2.5

closeQuietly

public static void closeQuietly(Closeable closeable)

Closes a Closeable unconditionally.

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

Example code:

 Closeable closeable = null;
 try {
     closeable = new FileReader("foo.txt");
     // process closeable
     closeable.close();
 } catch (Exception e) {
     // error handling
 } finally {
     IOUtils.closeQuietly(closeable);
 }
 

Closing all streams:

 try {
     return IOUtils.copy(inputStream, outputStream);
 } finally {
     IOUtils.closeQuietly(inputStream);
     IOUtils.closeQuietly(outputStream);
 }
 

Parameters:

closeable - the objects to close, may be null or already closed

Since:

2.0

toString

public static String toString(InputStream input,
                              Charset encoding)
                       throws IOException

Gets the contents of an InputStream as a String using the specified character encoding.

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

Parameters:

input - the InputStream to read from

encoding - the encoding to use, null means platform default

Returns:

the requested String

Throws:

NullPointerException - if the input is null

IOException - if an I/O error occurs

Since:

2.3

toCharset

public static Charset toCharset(Charset charset)

Returns the given Charset or the default Charset if the given Charset is null.

Parameters:

charset - A charset or null.

Returns:

the given Charset or the default Charset if the given Charset is null

toCharset

public static Charset toCharset(String charset)

Returns a Charset for the named charset. If the name is null, return the default Charset.

Parameters:

charset - The name of the requested charset, may be null.

Returns:

a Charset for the named charset

copy

public static void copy(InputStream input,
                        Writer output,
                        Charset inputEncoding)
                 throws IOException

Copies 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.

This method uses InputStreamReader.

Parameters:

input - the InputStream to read from

output - the Writer to write to

inputEncoding - the encoding to use for the input stream, null means platform default

Throws:

NullPointerException - if the input or output is null

IOException - if an I/O error occurs

Since:

2.3

copy

public static int copy(Reader input,
                       Writer output)
                throws IOException

Copies 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.

Parameters:

input - the Reader to read from

output - the Writer to write to

Returns:

the number of characters copied, or -1 if > Integer.MAX_VALUE

Throws:

NullPointerException - if the input or output is null

IOException - if an I/O error occurs

Since:

1.1

copy

public static int copy(InputStream input,
                       OutputStream output)
                throws IOException

Copies 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.

Parameters:

input - the InputStream to read from

output - the OutputStream to write to

Returns:

the number of bytes copied, or -1 if > Integer.MAX_VALUE

Throws:

NullPointerException - if the input or output is null

IOException - if an I/O error occurs

Since:

1.1

copy

public static long copy(InputStream input,
                        OutputStream output,
                        int bufferSize)
                 throws IOException

Copies bytes from an InputStream to an OutputStream using an internal buffer of the given size.

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

Parameters:

input - the InputStream to read from

output - the OutputStream to write to

bufferSize - the bufferSize used to copy from the input to the output

Returns:

the number of bytes copied

Throws:

NullPointerException - if the input or output is null

IOException - if an I/O error occurs

Since:

2.5

copyLarge

public static long copyLarge(Reader input,
                             Writer output)
                      throws IOException

Copies 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.

The buffer size is given by #DEFAULT_BUFFER_SIZE.

Parameters:

input - the Reader to read from

output - the Writer to write to

Returns:

the number of characters copied

Throws:

NullPointerException - if the input or output is null

IOException - if an I/O error occurs

Since:

1.3

copyLarge

public static long copyLarge(InputStream input,
                             OutputStream output)
                      throws IOException

Copies 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.

The buffer size is given by #DEFAULT_BUFFER_SIZE.

Parameters:

input - the InputStream to read from

output - the OutputStream to write to

Returns:

the number of bytes copied

Throws:

NullPointerException - if the input or output is null

IOException - if an I/O error occurs

Since:

1.3

copyLarge

public static long copyLarge(InputStream input,
                             OutputStream output,
                             byte[] buffer)
                      throws IOException

Copies bytes from a large (over 2GB) InputStream to an OutputStream.

This method uses the provided buffer, so there is no need to use a BufferedInputStream.

Parameters:

input - the InputStream to read from

output - the OutputStream to write to

buffer - the buffer to use for the copy

Returns:

the number of bytes copied

Throws:

NullPointerException - if the input or output is null

IOException - if an I/O error occurs

Since:

2.2

copyLarge

public static long copyLarge(Reader input,
                             Writer output,
                             char[] buffer)
                      throws IOException

Copies chars from a large (over 2GB) Reader to a Writer.

This method uses the provided buffer, so there is no need to use a BufferedReader.

Parameters:

input - the Reader to read from

output - the Writer to write to

buffer - the buffer to be used for the copy

Returns:

the number of characters copied

Throws:

NullPointerException - if the input or output is null

IOException - if an I/O error occurs

Since:

2.2

write

public static void write(String data,
                         OutputStream output,
                         Charset encoding)
                  throws IOException

Writes chars from a String to bytes on an OutputStream using the specified character encoding.

This method uses String.getBytes(String).

Parameters:

data - the String to write, null ignored

output - the OutputStream to write to

encoding - the encoding to use, null means platform default

Throws:

NullPointerException - if output is null

IOException - if an I/O error occurs

Since:

2.3

toByteArray

public static byte[] toByteArray(InputStream input,
                                 int size)
                          throws IOException

Gets the contents of an InputStream as a byte[]. Use this method instead of toByteArray(InputStream) when InputStream size is known

Parameters:

input - the InputStream to read from

size - the size of InputStream

Returns:

the requested byte array

Throws:

IOException - if an I/O error occurs or InputStream size differ from parameter size

IllegalArgumentException - if size is less than zero

Since:

2.1

toByteArray

public static byte[] toByteArray(InputStream input,
                                 long size)
                          throws IOException

Gets contents of an InputStream as a byte[]. Use this method instead of toByteArray(InputStream) when InputStream size is known. NOTE: the method checks that the length can safely be cast to an int without truncation before using toByteArray(java.io.InputStream, int) to read into the byte array. (Arrays can have no more than Integer.MAX_VALUE entries anyway)

Parameters:

input - the InputStream to read from

size - the size of InputStream

Returns:

the requested byte array

Throws:

IOException - if an I/O error occurs or InputStream size differ from parameter size

IllegalArgumentException - if size is less than zero or size is greater than Integer.MAX_VALUE

Since:

2.1

See Also:

toByteArray(java.io.InputStream, int)

readLines

public static List<String> readLines(InputStream input,
                                     Charset encoding)
                              throws IOException

Gets the contents of an InputStream as a list of Strings, one entry per line, using the specified character encoding.

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

Parameters:

input - the InputStream to read from, not null

encoding - the encoding to use, null means platform default

Returns:

the list of Strings, never null

Throws:

NullPointerException - if the input is null

IOException - if an I/O error occurs

Since:

2.3

readLines

public static List<String> readLines(Reader input)
                              throws IOException

Gets 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.

Parameters:

input - the Reader to read from, not null

Returns:

the list of Strings, never null

Throws:

NullPointerException - if the input is null

IOException - if an I/O error occurs

Since:

1.1

toBufferedReader

public static BufferedReader toBufferedReader(Reader reader)

Returns the given reader if it is a BufferedReader, otherwise creates a BufferedReader from the given reader.

Parameters:

reader - the reader to wrap or return (not null)

Returns:

the given reader or a new BufferedReader for the given reader

Throws:

NullPointerException - if the input parameter is null

Since:

2.2