Package org.zkoss.io

## Class RepeatableReader

- java.lang.Object
- - java.io.Reader
  - - org.zkoss.io.RepeatableReader

- All Implemented Interfaces:
    `java.io.Closeable`, `java.io.Serializable`, `java.lang.AutoCloseable`, `java.lang.Readable`, `Repeatable`

      public class RepeatableReader
      extends java.io.Reader
      implements Repeatable, java.io.Serializable

  `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
  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class java.io.Reader

      `lock`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | 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 java.io.Reader` | `getInstance​(java.io.File file)` | Returns a reader to read a file, encoded in UTF-8, that can be read repeatedly.
    `static java.io.Reader` | `getInstance​(java.io.File file, java.lang.String charset)` | Returns a reader to read a file that can be read repeatedly.
    `static java.io.Reader` | `getInstance​(java.io.Reader rd)` | Returns a reader that can be read repeatedly, or null if the given reader is null.
    `static java.io.Reader` | `getInstance​(java.lang.String filename)` | Returns a reader to read a file, encoded in UTF-8, that can be read repeatedly.
    `static java.io.Reader` | `getInstance​(java.lang.String filename, java.lang.String charset)` | Returns a reader to read a file that can be read repeatedly.
    `static java.io.Reader` | `getInstance​(java.net.URL url)` | Returns a reader to read the resource of the specified URL, encoded in UTF-8.
    `static java.io.Reader` | `getInstance​(java.net.URL url, java.lang.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, nullReader, read, read, read, ready, reset, skip, transferTo`

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### getInstance

          public static java.io.Reader getInstance​(java.io.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 java.io.Reader getInstance​(java.io.File file,
                                                   java.lang.String charset)
                                            throws java.io.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:
        `java.lang.IllegalArgumentException` - if file is null.
        `java.io.FileNotFoundException`
      Since:
        3.0.8
      See Also:
        `getInstance(Reader)`, `getInstance(String, String)`

    - #### getInstance

          public static java.io.Reader getInstance​(java.io.File file)
                                            throws java.io.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:
        `java.lang.IllegalArgumentException` - if file is null.
        `java.io.FileNotFoundException`
      See Also:
        `getInstance(Reader)`, `getInstance(String)`

    - #### getInstance

          public static java.io.Reader getInstance​(java.lang.String filename,
                                                   java.lang.String charset)
                                            throws java.io.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:
        `java.lang.IllegalArgumentException` - if file is null.
        `java.io.FileNotFoundException` - if file is not found.
      Since:
        3.0.8
      See Also:
        `getInstance(Reader)`, `getInstance(File, String)`

    - #### getInstance

          public static java.io.Reader getInstance​(java.lang.String filename)
                                            throws java.io.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:
        `java.lang.IllegalArgumentException` - if file is null.
        `java.io.FileNotFoundException` - if file is not found.
      See Also:
        `getInstance(Reader)`, `getInstance(File)`

    - #### getInstance

          public static java.io.Reader getInstance​(java.net.URL url,
                                                   java.lang.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:
        `java.lang.IllegalArgumentException` - if file is null.
      Since:
        3.0.8
      See Also:
        `getInstance(Reader)`, `getInstance(String, String)`

    - #### getInstance

          public static java.io.Reader getInstance​(java.net.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:
        `java.lang.IllegalArgumentException` - if file is null.
      See Also:
        `getInstance(Reader)`, `getInstance(String)`

    - #### read

          public int read​(char[] cbuf,
                          int off,
                          int len)
                   throws java.io.IOException

      Specified by:
        `read` in class `java.io.Reader`
      Throws:
        `java.io.IOException`

    - #### close

          public void close()
                     throws java.io.IOException

      Closes the current access, and the next call of `read(char[], int, int)` re-opens the buffered reader.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in class `java.io.Reader`
      Throws:
        `java.io.IOException`

    - #### finalize

          protected void finalize()
                           throws java.lang.Throwable

      Overrides:
        `finalize` in class `java.lang.Object`
      Throws:
        `java.lang.Throwable`