org.pfsw.util

Class IOUtil

java.lang.Object

org.pfsw.util.IOUtil

public class IOUtil
extends java.lang.Object

Various well-tested and reusable utility methods that help to reduce large amount of boilerplate code in the area of I/O (stream and reader/writer processing).

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_BUFFER_SIZE
static IProgressListener	IGNORING_PROGRESS_LISTENER
static java.lang.String	LINE_SEPARATOR
protected static java.lang.Long	NO_LIMIT

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	IOUtil() Protected constructor allows subclassing!

Method Summary

Modifier and Type	Method and Description
protected void	assertArgumentNotNull(java.lang.String argName, java.lang.Object arg)
java.io.InputStream	asStream(java.lang.String string, java.nio.charset.Charset charset) Returns an input stream containing the given string using the provided charset for encoding.
protected java.lang.String[]	basicReadTextLinesFrom(java.io.Reader reader, IStringFilter filter) Reads all text lines that match the filter from the specified reader into a String array.
boolean	close(java.io.Closeable closeable) Close the given closeable ignoring any exception and checking for null before closing.
long	copyStream(java.io.InputStream inStream, java.io.OutputStream outStream) Copies all data from the input stream to the output stream using a buffer with the default size (4096 bytes).
long	copyStream(java.io.InputStream inStream, java.io.OutputStream outStream, int bufSize) Copies all data from the input stream to the output stream using a buffer of the given size in bytes.
long	copyStream(java.io.InputStream inStream, java.io.OutputStream outStream, int bufSize, IProgressListener listener) Copies all data from the input stream to the output stream using a buffer of the given size in bytes.
long	copyStream(java.io.InputStream inStream, java.io.OutputStream outStream, int bufSize, java.lang.Long limit) Copies all data from the input stream to the output stream using a buffer of the given size in bytes.
long	copyStream(java.io.InputStream inStream, java.io.OutputStream outStream, int bufSize, java.lang.Long limit, IProgressListener listener) Copies all data from the input stream to the output stream using a buffer of the given size in bytes.
long	copyStream(java.io.InputStream inStream, java.io.OutputStream outStream, IProgressListener listener) Copies all data from the input stream to the output stream using a buffer with the default size (4096 bytes).
protected void	copyText(java.io.InputStream inStream, java.nio.charset.Charset charset, java.io.StringWriter writer)
void	copyText(java.io.Reader reader, java.io.Writer writer) Copies all text lines from the specified reader to the given writer.
void	copyText(java.io.Reader reader, java.io.Writer writer, IProgressListener progressListener) Copies all text lines from the specified reader to the given writer.
static IOUtil	current() Returns the only instance this class supports (design pattern "Singleton")
void	processTextLines(java.io.InputStream inStream, java.nio.charset.Charset charset, ILineProcessor processor) Reads all text lines from the specified input stream and passes them one by one to the given line processor.
void	processTextLines(java.io.InputStream inStream, ICheckedCharset charsetName, ILineProcessor processor) Reads all text lines from the specified input stream and passes them one by one to the given line processor.
void	processTextLines(java.io.InputStream inStream, ILineProcessor processor) Reads all text lines from the specified input stream and passes them one by one to the given line processor.
void	processTextLines(java.io.Reader reader, ILineProcessor processor) Reads all text lines from the specified reader and passes them one by one to the given line processor.
java.lang.String	readTextFrom(java.io.InputStream inStream) Reads the whole content of the given input stream and returns it as a string.
java.lang.String	readTextFrom(java.io.InputStream inStream, java.nio.charset.Charset charset) Reads the whole content of the given input stream and returns it as a string.
java.lang.String	readTextFrom(java.io.InputStream inStream, ICheckedCharset charsetName) Reads the whole content of the given input stream and returns it as a string.
java.lang.String	readTextFrom(java.io.Reader reader) Reads all text from the given reader and returns it as a single string.
java.lang.String[]	readTextLinesFrom(java.io.InputStream inStream) Reads all text lines from the specified stream into a String array.
java.lang.String[]	readTextLinesFrom(java.io.InputStream inStream, java.nio.charset.Charset charset) Reads all text lines from the specified stream into a String array.
java.lang.String[]	readTextLinesFrom(java.io.InputStream inStream, java.nio.charset.Charset charset, IStringFilter filter) Reads all text lines matching the filter from the specified stream into a String array using the specified character encoding.
java.lang.String[]	readTextLinesFrom(java.io.InputStream inStream, ICheckedCharset charsetName, IStringFilter filter) Reads all text lines matching the filter from the specified stream into a String array using the specified character encoding.
java.lang.String[]	readTextLinesFrom(java.io.InputStream inStream, IStringFilter filter) Reads all text lines matching the filter from the specified stream into a String array.
java.lang.String[]	readTextLinesFrom(java.io.Reader reader) Reads all text lines from the specified reader into a String array.
java.lang.String[]	readTextLinesFrom(java.io.Reader reader, IStringFilter filter) Reads all text lines that match the filter from the specified reader into a String array.
java.lang.String	urlDecode(java.lang.String str) Returns the given string with all %xx placeholders decoded.
java.lang.String	urlDecode(java.lang.String str, java.nio.charset.Charset charset) Returns the given string with all %xx placeholders decoded using the specified charset encoding.
java.lang.String	urlEncode(java.lang.String str) Returns the given string with all characters that are not allowed directly in URLs encoded as %xx placeholders.
java.lang.String	urlEncode(java.lang.String str, java.nio.charset.Charset charset) Returns the given string with all characters that are not allowed directly in URLs encoded as %xx placeholders.

Methods inherited from class java.lang.Object

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

Field Detail

LINE_SEPARATOR

public static final java.lang.String LINE_SEPARATOR

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

See Also:

Constant Field Values

IGNORING_PROGRESS_LISTENER

public static final IProgressListener IGNORING_PROGRESS_LISTENER

NO_LIMIT

protected static final java.lang.Long NO_LIMIT

Constructor Detail

IOUtil

protected IOUtil()

Protected constructor allows subclassing!

Method Detail

current

public static IOUtil current()

Returns the only instance this class supports (design pattern "Singleton")

close

public boolean close(java.io.Closeable closeable)

Close the given closeable ignoring any exception and checking for null before closing. Returns true, if the object was closed successfully, false otherwise.

processTextLines

public void processTextLines(java.io.InputStream inStream,
                             ILineProcessor processor)
                      throws java.io.IOException

Reads all text lines from the specified input stream and passes them one by one to the given line processor. The processing will be terminated, if the end of the text is reached or if the processor returns false.
The given input stream will be closed after the execution of this method. Even if an exception occurred. The character encoding is the JVM default encoding.

Parameters:

inStream - The input stream that contains the text

processor - The processor that receives the lines from the text

Throws:

java.io.IOException

processTextLines

public void processTextLines(java.io.InputStream inStream,
                             ICheckedCharset charsetName,
                             ILineProcessor processor)
                      throws java.io.IOException

Reads all text lines from the specified input stream and passes them one by one to the given line processor. The processing will be terminated, if the end of the text is reached or if the processor returns false.
The given input stream will be closed after the execution of this method. Even if an exception occurred.

Parameters:

inStream - The input stream that contains the text (must not be null).

charsetName - A charset name already checked to be supported (must not be null).

processor - The processor that receives the lines from the text (must not be null).

Throws:

java.io.IOException

processTextLines

public void processTextLines(java.io.InputStream inStream,
                             java.nio.charset.Charset charset,
                             ILineProcessor processor)
                      throws java.io.IOException

Reads all text lines from the specified input stream and passes them one by one to the given line processor. The processing will be terminated, if the end of the text is reached or if the processor returns false.
The given input stream will be closed after the execution of this method. Even if an exception occurred.

Parameters:

inStream - The input stream that contains the text (must not be null).

charset - A character set defining the encoding of the stream (must not be null).

processor - The processor that receives the lines from the text (must not be null).

Throws:

java.io.IOException

processTextLines

public void processTextLines(java.io.Reader reader,
                             ILineProcessor processor)
                      throws java.io.IOException

Reads all text lines from the specified reader and passes them one by one to the given line processor. The processing will be terminated, if the end of the text is reached or if the processor returns false.

Parameters:

reader - The reader that contains a text stream

processor - The processor that receives the lines from the text

Throws:

java.io.IOException

readTextLinesFrom

public java.lang.String[] readTextLinesFrom(java.io.Reader reader)
                                     throws java.io.IOException

Reads all text lines from the specified reader into a String array. After that the reader will be closed. Even if an exception occurs.

Parameters:

reader - The reader which provides the text

Throws:

java.io.IOException

readTextLinesFrom

public java.lang.String[] readTextLinesFrom(java.io.InputStream inStream)
                                     throws java.io.IOException

Reads all text lines from the specified stream into a String array. After that the stream will be closed. Even if an exception occurs. The character encoding is the JVM default encoding.

Parameters:

inStream - The stream from which to read the text lines

Throws:

java.io.IOException

readTextLinesFrom

public java.lang.String[] readTextLinesFrom(java.io.InputStream inStream,
                                            IStringFilter filter)
                                     throws java.io.IOException

Reads all text lines matching the filter from the specified stream into a String array. After that the stream will be closed. Even if an exception occurs. The character encoding is the JVM default encoding.

Parameters:

inStream - The stream from which to read the text lines

filter - A filter that defines which lines to return (may be null -> all lines)

Throws:

java.io.IOException

readTextLinesFrom

public java.lang.String[] readTextLinesFrom(java.io.InputStream inStream,
                                            ICheckedCharset charsetName,
                                            IStringFilter filter)
                                     throws java.io.IOException

Reads all text lines matching the filter from the specified stream into a String array using the specified character encoding. After that the stream will be closed. Even if an exception occurs.

Parameters:

inStream - The stream from which to read the text lines.

charsetName - A charset name already checked to be supported (must not be null).

filter - A filter that defines which lines to return (may be null -> all lines).

Throws:

java.io.IOException

readTextLinesFrom

public java.lang.String[] readTextLinesFrom(java.io.InputStream inStream,
                                            java.nio.charset.Charset charset)
                                     throws java.io.IOException

Reads all text lines from the specified stream into a String array. After that the stream will be closed. Even if an exception occurs.

Parameters:

inStream - The stream from which to read the text lines (must not be null).

charset - A character set defining the encoding of the stream (must not be null).

Throws:

java.io.IOException

readTextLinesFrom

public java.lang.String[] readTextLinesFrom(java.io.InputStream inStream,
                                            java.nio.charset.Charset charset,
                                            IStringFilter filter)
                                     throws java.io.IOException

Reads all text lines matching the filter from the specified stream into a String array using the specified character encoding. After that the stream will be closed. Even if an exception occurs.

Parameters:

inStream - The stream from which to read the text lines (must not be null).

charset - A character set defining the encoding of the input stream (must not be null).

filter - A filter that defines which lines to return (may be null -> all lines).

Throws:

java.io.IOException

readTextLinesFrom

public java.lang.String[] readTextLinesFrom(java.io.Reader reader,
                                            IStringFilter filter)
                                     throws java.io.IOException

Reads all text lines that match the filter from the specified reader into a String array. If the filter is null all lines will be returned. After that the reader will be closed. Even if an exception occurs.

Parameters:

reader - The reader which provides the text

filter - A filter that defines which lines to return (may be null -> all lines)

Throws:

java.io.IOException

readTextFrom

public java.lang.String readTextFrom(java.io.Reader reader)
                              throws java.io.IOException

Reads all text from the given reader and returns it as a single string.

Parameters:

reader - The reader from which to get the content (must not be null).

Returns:

The whole content of the provided reader as a string.

Throws:

java.io.IOException - Any open/read problem.

copyText

public void copyText(java.io.Reader reader,
                     java.io.Writer writer)
              throws java.io.IOException

Copies all text lines from the specified reader to the given writer. After that the reader will be closed. Even if an exception occurs.
The writer stays open!

Parameters:

reader - The reader which provides the text to copy (must not be null).

writer - The writer to which the text will be copied (must not be null).

Throws:

java.io.IOException - If reading or writing fails.

copyText

public void copyText(java.io.Reader reader,
                     java.io.Writer writer,
                     IProgressListener progressListener)
              throws java.io.IOException

Copies all text lines from the specified reader to the given writer. After that the reader will be closed. Even if an exception occurs.
The writer stays open!

Parameters:

reader - The reader which provides the text to copy (must not be null).

writer - The writer to which the text will be copied (must not be null).

progressListener - A listener that will be called during the copy process before each line gets actually written and once at the very end. The listener gets the current line number as argument and the IProgressListener.UNDEFINED_SIZE for the total lines. The listener can be used to monitor the progress as well as stopping copying by returning false. A null listener will be ignored.

Throws:

java.io.IOException - If reading or writing fails.

readTextFrom

public java.lang.String readTextFrom(java.io.InputStream inStream)
                              throws java.io.IOException

Reads the whole content of the given input stream and returns it as a string. The stream will be closed after calling this method. Even if an exception occurred! The stream character encoding is the JVM default encoding.

Parameters:

inStream - The input stream to read.

Returns:

The text content of the given stream.

Throws:

java.io.IOException

readTextFrom

public java.lang.String readTextFrom(java.io.InputStream inStream,
                                     ICheckedCharset charsetName)
                              throws java.io.IOException

Reads the whole content of the given input stream and returns it as a string. The stream will be closed after calling this method. Even if an exception occurred!

Parameters:

inStream - The input stream to read (must not be null).

charsetName - A charset name already checked to be supported (must not be null).

Returns:

The text content of the given stream

Throws:

java.io.IOException

readTextFrom

public java.lang.String readTextFrom(java.io.InputStream inStream,
                                     java.nio.charset.Charset charset)
                              throws java.io.IOException

Reads the whole content of the given input stream and returns it as a string. The stream will be closed after calling this method. Even if an exception occurred!

Parameters:

inStream - The input stream to read (must not be null).

charset - A character set defining the encoding of the stream (must not be null).

Returns:

The text content of the given stream.

Throws:

java.io.IOException

copyStream

public long copyStream(java.io.InputStream inStream,
                       java.io.OutputStream outStream)
                throws java.io.IOException

Copies all data from the input stream to the output stream using a buffer with the default size (4096 bytes). After all data is copied both streams will be closed !

Parameters:

inStream - The source stream.

outStream - The target stream.

Returns:

The number of bytes copied.

Throws:

java.io.IOException

copyStream

public long copyStream(java.io.InputStream inStream,
                       java.io.OutputStream outStream,
                       IProgressListener listener)
                throws java.io.IOException

Copies all data from the input stream to the output stream using a buffer with the default size (4096 bytes). After all data is copied both streams will be closed !

Parameters:

inStream - The source stream.

outStream - The target stream.

listener - A listener that will be called during the copy process before each chunk of data (see bufferSize) gets actually processed and once at the very end. The listener can be used to monitor the progress as well as stopping copying by returning false. A null listener will be ignored.

Returns:

The number of bytes copied.

Throws:

java.io.IOException

copyStream

public long copyStream(java.io.InputStream inStream,
                       java.io.OutputStream outStream,
                       int bufSize)
                throws java.io.IOException

Copies all data from the input stream to the output stream using a buffer of the given size in bytes. After all data has been copied both streams will be closed!

Parameters:

inStream - The source stream.

outStream - The target stream.

bufSize - The size of the buffer that is used for the transfer of byte chunks (must be positive value).

Returns:

The number of bytes copied.

Throws:

java.io.IOException

copyStream

public long copyStream(java.io.InputStream inStream,
                       java.io.OutputStream outStream,
                       int bufSize,
                       IProgressListener listener)
                throws java.io.IOException

Copies all data from the input stream to the output stream using a buffer of the given size in bytes. After all data has been copied both streams will be closed!

Parameters:

inStream - The source stream.

outStream - The target stream.

bufSize - The size of the buffer that is used for the transfer of byte chunks (must be positive value).

listener - A listener that will be called during the copy process before each chunk of data (see bufferSize) gets actually processed and once at the very end. The listener can be used to monitor the progress as well as stopping copying by returning false. A null listener will be ignored.

Returns:

The number of bytes copied.

Throws:

java.io.IOException

copyStream

public long copyStream(java.io.InputStream inStream,
                       java.io.OutputStream outStream,
                       int bufSize,
                       java.lang.Long limit)
                throws java.io.IOException

Copies all data from the input stream to the output stream using a buffer of the given size in bytes. After all data has been copied both streams will be closed!

Parameters:

inStream - The source stream.

outStream - The target stream.

bufSize - The size of the buffer that is used for the transfer of byte chunks (must be positive value).

limit - The maximum number of bytes that will be copied. If exceeded an IOException will be thrown. Setting this parameter to null, zero or a negative value will specify no limit.

Returns:

The number of bytes copied.

Throws:

java.io.IOException

copyStream

public long copyStream(java.io.InputStream inStream,
                       java.io.OutputStream outStream,
                       int bufSize,
                       java.lang.Long limit,
                       IProgressListener listener)
                throws java.io.IOException

Copies all data from the input stream to the output stream using a buffer of the given size in bytes. After all data has been copied both streams will be closed!

Parameters:

inStream - The source stream.

outStream - The target stream.

bufSize - The size of the buffer that is used for the transfer of byte chunks (must be positive value).

limit - The maximum number of bytes that will be copied. If exceeded an IOException will be thrown. Setting this parameter to null, zero or a negative value will specify no limit.

listener - A listener that will be called during the copy process before each chunk of data (see bufferSize) gets actually processed and once at the very end. The listener can be used to monitor the progress as well as stopping copying by returning false. A null listener will be ignored.

Returns:

The number of bytes copied.

Throws:

java.io.IOException

asStream

public java.io.InputStream asStream(java.lang.String string,
                                    java.nio.charset.Charset charset)

Returns an input stream containing the given string using the provided charset for encoding.

Parameters:

string - The string to convert to a stream (must not be null).

charset - The character encoding to convert the string to bytes. If null, the default platform encoding will be used.

Returns:

An input stream containing the provided string data.

urlDecode

public java.lang.String urlDecode(java.lang.String str,
                                  java.nio.charset.Charset charset)

Returns the given string with all %xx placeholders decoded using the specified charset encoding.

Parameters:

str - The string to decode.

charset - The charset to be used for decoding.

Returns:

A string with all %xx placeholders decoded according to the specified charset.

urlDecode

public java.lang.String urlDecode(java.lang.String str)

Returns the given string with all %xx placeholders decoded.

Parameters:

str - The string to decode

Returns:

A string with all %xx placeholders decoded (using UTF-8)

urlEncode

public java.lang.String urlEncode(java.lang.String str,
                                  java.nio.charset.Charset charset)

Returns the given string with all characters that are not allowed directly in URLs encoded as %xx placeholders. In particular it replaces spaces by " %20" rather than '+'! That is reasonable in cases where files in the local file system contain spaces. Such URLs (staring with "file:") cannot open a stream if the URL contains a '+' because the '+' would not be decoded back to a space. That is a bug (or at least an inconsistency) in the URL class implementation.

Parameters:

str - The string to encode.

charset - The charset to be used for encoding.

Returns:

A string with %xx encodings for all invalid URL characters.

urlEncode

public java.lang.String urlEncode(java.lang.String str)

Returns the given string with all characters that are not allowed directly in URLs encoded as %xx placeholders. In particular it replaces spaces by " %20" rather than '+'! That is reasonable in cases where files in the local file system contain spaces. Such URLs (staring with "file:") cannot open a stream if the URL contains a '+' because the '+' would not be decoded back to a space. That is a bug (or at least an inconsistency) in the URL class implementation.

Parameters:

str - The string to encode.

Returns:

A string with %xx (UTF-8) encodings for all invalid URL characters.

basicReadTextLinesFrom

protected java.lang.String[] basicReadTextLinesFrom(java.io.Reader reader,
                                                    IStringFilter filter)
                                             throws java.io.IOException

Reads all text lines that match the filter from the specified reader into a String array. If the filter is null all lines will be returned. After that the reader will be closed. Even if an exception occurs.

Parameters:

reader - The reader which provides the text

filter - A filter that defines which lines to return (may be null -> all lines)

Throws:

java.io.IOException

copyText

protected void copyText(java.io.InputStream inStream,
                        java.nio.charset.Charset charset,
                        java.io.StringWriter writer)
                 throws java.io.IOException

Throws:

java.io.IOException

assertArgumentNotNull

protected void assertArgumentNotNull(java.lang.String argName,
                                     java.lang.Object arg)