org.zkoss.io

Class RepeatableReader

java.lang.Object

java.io.Reader

org.zkoss.io.RepeatableReader

All Implemented Interfaces:

Closeable, AutoCloseable, Readable, Repeatable

public class RepeatableReader
extends Reader
implements Repeatable

RepeatableReader adds functionality to another reader, the ability to read repeatedly. By repeatable-read we mean, after close(), the next invocation of read(char[], int, int) will re-open the reader.

RepeatableInputStream actually creates a temporary space to buffer the content, so it can be re-opened again after closed. Notice that the temporary space (a.k.a., the buffered reader) is never closed until garbage-collected.

If the content size of the given reader is smaller than the value specified in the system property called "org.zkoss.io.memoryLimitSize", the content will be buffered in the memory. If the size exceeds, the content will be buffered in a temporary file. By default, it is 512KB. Note: the maximal value is Integer.MAX_VALUE

If the content size of the given reader is larger than the value specified in the system property called "org.zkoss.io.bufferLimitSize", the content won't be buffered, and it means the read is not repeatable. By default, it is 20MB. Note: the maximal value is Integer.MAX_VALUE

Since:

3.0.4

Author:

tomyeh

Field Summary

Fields inherited from class java.io.Reader

lock

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes the current access, and the next call of read(char[], int, int) re-opens the buffered reader.
protected void	finalize()
static Reader	getInstance(File file) Returns a reader to read a file, encoded in UTF-8, that can be read repeatedly.
static Reader	getInstance(File file, String charset) Returns a reader to read a file that can be read repeatedly.
static Reader	getInstance(Reader rd) Returns a reader that can be read repeatedly, or null if the given reader is null.
static Reader	getInstance(String filename) Returns a reader to read a file, encoded in UTF-8, that can be read repeatedly.
static Reader	getInstance(String filename, String charset) Returns a reader to read a file that can be read repeatedly.
static Reader	getInstance(URL url) Returns a reader to read the resource of the specified URL, encoded in UTF-8.
static Reader	getInstance(URL url, String charset) Returns a reader to read the resource of the specified URL.
int	read(char[] cbuf, int off, int len)

Methods inherited from class java.io.Reader

mark, markSupported, read, read, read, ready, reset, skip

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static Reader getInstance(Reader rd)

Returns a reader that can be read repeatedly, or null if the given reader is null. Note: the returned reader encapsulates the given reader, rd (a.k.a., the buffered reader) to adds the functionality to re-opens the reader once close() is called.

By repeatable-read we mean, after close(), the next invocation of read(char[], int, int) will re-open the reader.

Use this method instead of instantiating RepeatableReader with the constructor.

See Also:

getInstance(File)

getInstance

public static Reader getInstance(File file,
                 String charset)
                          throws FileNotFoundException

Returns a reader to read a file that can be read repeatedly. Note: it assumes the file is text (rather than binary).

By repeatable-read we mean, after close(), the next invocation of read(char[], int, int) will re-open the reader.

Note: it is efficient since we don't have to buffer the content of the file to make it repeatable-read.

Parameters:

charset - the charset. If null, "UTF-8" is assumed.

Throws:

IllegalArgumentException - if file is null.

FileNotFoundException

Since:

3.0.8

See Also:

getInstance(Reader), getInstance(String, String)

getInstance

public static Reader getInstance(File file)
                          throws FileNotFoundException

Returns a reader to read a file, encoded in UTF-8, that can be read repeatedly. Note: it assumes the file is text (rather than binary).

By repeatable-read we mean, after close(), the next invocation of read(char[], int, int) will re-open the reader.

Note: it is efficient since we don't have to buffer the content of the file to make it repeatable-read.

Throws:

IllegalArgumentException - if file is null.

FileNotFoundException

See Also:

getInstance(Reader), getInstance(String)

getInstance

public static Reader getInstance(String filename,
                 String charset)
                          throws FileNotFoundException

Returns a reader to read a file that can be read repeatedly. Note: it assumes the file is text (rather than binary).

By repeatable-read we mean, after close(), the next invocation of read(char[], int, int) will re-open the reader.

Note: it is efficient since we don't have to buffer the content of the file to make it repeatable-read.

Parameters:

filename - the file name

charset - the charset. If null, "UTF-8" is assumed.

Throws:

IllegalArgumentException - if file is null.

FileNotFoundException - if file is not found.

Since:

3.0.8

See Also:

getInstance(Reader), getInstance(File, String)

getInstance

public static Reader getInstance(String filename)
                          throws FileNotFoundException

Returns a reader to read a file, encoded in UTF-8, that can be read repeatedly. Note: it assumes the file is text (rather than binary).

By repeatable-read we mean, after close(), the next invocation of read(char[], int, int) will re-open the reader.

Note: it is efficient since we don't have to buffer the content of the file to make it repeatable-read.

Parameters:

filename - the file name

Throws:

IllegalArgumentException - if file is null.

FileNotFoundException - if file is not found.

See Also:

getInstance(Reader), getInstance(File)

getInstance

public static Reader getInstance(URL url,
                 String charset)

Returns a reader to read the resource of the specified URL. The reader can be read repeatedly. Note: it assumes the resource is text (rather than binary).

By repeatable-read we mean, after close(), the next invocation of read(char[], int, int) will re-open the reader.

Note: it is efficient since we don't have to buffer the content of the file to make it repeatable-read.

Parameters:

charset - the charset. If null, "UTF-8" is assumed.

Throws:

IllegalArgumentException - if file is null.

Since:

3.0.8

See Also:

getInstance(Reader), getInstance(String, String)

getInstance

public static Reader getInstance(URL url)

Returns a reader to read the resource of the specified URL, encoded in UTF-8. The reader can be read repeatedly. Note: it assumes the resource is text (rather than binary).

By repeatable-read we mean, after close(), the next invocation of read(char[], int, int) will re-open the reader.

Note: it is efficient since we don't have to buffer the content of the file to make it repeatable-read.

Throws:

IllegalArgumentException - if file is null.

See Also:

getInstance(Reader), getInstance(String)

read

public int read(char[] cbuf,
       int off,
       int len)
         throws IOException

Specified by:

read in class Reader

Throws:

IOException

close

public void close()
           throws IOException

Closes the current access, and the next call of read(char[], int, int) re-opens the buffered reader.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Specified by:

close in class Reader

Throws:

IOException

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable