Package org.zkoss.io

## Class RepeatableInputStream

- java.lang.Object
- - java.io.InputStream
  - - org.zkoss.io.RepeatableInputStream

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

      public class RepeatableInputStream
      extends java.io.InputStream
      implements Repeatable, java.io.Serializable

  `RepeatableInputStream` adds functionality to another input stream, the ability to read repeatedly. By repeatable-read we mean, after `close()`, the next invocation of `read()` will re-open the input stream.

  `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 input stream) is never closed until garbage-collected.

  If the content size of the given input stream 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 input stream 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:
    jumperchen, tomyeh
  See Also:
    Serialized Form

- - ### 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 `close()` re-opens the buffered input stream.
    `static java.io.InputStream` | `getInstance​(java.io.File file)` | Returns an input stream of a file that can be read repeatedly.
    `static java.io.InputStream` | `getInstance​(java.io.InputStream is)` | Returns an input stream that can be read repeatedly, or null if the given input stream is null.
    `static java.io.InputStream` | `getInstance​(java.lang.String filename)` | Returns an input stream of a file that can be read repeatedly.
    `static java.io.InputStream` | `getInstance​(java.net.URL url)` | Returns an input stream of the resource of the given URL that can be read repeatedly.
    `int` | `read()` |
    `int` | `read​(byte[] b, int off, int len)` |

    - ### Methods inherited from class java.io.InputStream

      `available, mark, markSupported, nullInputStream, read, readAllBytes, readNBytes, readNBytes, reset, skip, transferTo`

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

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

- - ### Method Detail

    - #### getInstance

          public static java.io.InputStream getInstance​(java.io.InputStream is)

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

      By repeatable-read we mean, after `close()`, the next invocation of `read()` will re-open the input stream.

      Use this method instead of instantiating `RepeatableInputStream` with the constructor.

      See Also:
        `getInstance(File)`

    - #### getInstance

          public static java.io.InputStream getInstance​(java.io.File file)
                                                 throws java.io.FileNotFoundException

      Returns an input stream of a file that can be read repeatedly. Note: it assumes the file is binary (rather than text).

      By repeatable-read we mean, after `close()`, the next invocation of `read()` will re-open the input stream.

      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` - if file not found
      See Also:
        `getInstance(InputStream)`, `getInstance(String)`

    - #### getInstance

          public static java.io.InputStream getInstance​(java.lang.String filename)
                                                 throws java.io.FileNotFoundException

      Returns an input stream of a file that can be read repeatedly. Note: it assumes the file is binary (rather than text).

      By repeatable-read we mean, after `close()`, the next invocation of `read()` will re-open the input stream.

      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(InputStream)`, `getInstance(File)`

    - #### getInstance

          public static java.io.InputStream getInstance​(java.net.URL url)

      Returns an input stream of the resource of the given URL that can be read repeatedly. Note: it assumes the resource is binary (rather than text).

      By repeatable-read we mean, after `close()`, the next invocation of `read()` will re-open the input stream.

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

      Throws:
        `java.lang.IllegalArgumentException` - if url is null.
      See Also:
        `getInstance(InputStream)`, `getInstance(String)`

    - #### read

          public int read()
                   throws java.io.IOException

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

    - #### read

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

      Overrides:
        `read` in class `java.io.InputStream`
      Throws:
        `java.io.IOException`

    - #### close

          public void close()
                     throws java.io.IOException

      Closes the current access, and the next call of `close()` re-opens the buffered input stream.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.io.Closeable`
      Overrides:
        `close` in class `java.io.InputStream`
      Throws:
        `java.io.IOException`