org.apache.commons.io.input

## Class NullReader

- java.lang.Object
- - java.io.Reader
  - - org.apache.commons.io.input.NullReader

- All Implemented Interfaces:
    Closeable, AutoCloseable, Readable

      public class NullReader
      extends Reader

  A functional, lightweight `Reader` that emulates a reader of a specified size.

  This implementation provides a lightweight object for testing with an `Reader` where the contents don't matter.

  One use case would be for testing the handling of large `Reader` as it can emulate that scenario without the overhead of actually processing large numbers of characters - significantly speeding up test execution times.

  This implementation returns a space from the method that reads a character and leaves the array unchanged in the read methods that are passed a character array. If alternative data is required the `processChar()` and `processChars()` methods can be implemented to generate data, for example:

        public class TestReader extends NullReader {
            public TestReader(int size) {
                super(size);
            }
            protected char processChar() {
                return ... // return required value here
            }
            protected void processChars(char[] chars, int offset, int length) {
                for (int i = offset; i < length; i++) {
                    chars[i] = ... // set array value here
                }
            }
        }

  This class is not thread-safe.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static NullReader` | `INSTANCE` The singleton instance.

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

      `lock`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NullReader()` Constructs a `Reader` that emulates a size 0 reader which supports marking and does not throw EOFException.
    `NullReader(long size)` Constructs a `Reader` that emulates a specified size which supports marking and does not throw EOFException.
    `NullReader(long size, boolean markSupported, boolean throwEofException)` Constructs a `Reader` that emulates a specified size with option settings.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes this Reader.
    `long` | `getPosition()` Gets the current position.
    `long` | `getSize()` Gets the size this `Reader` emulates.
    `void` | `mark(int readLimit)` Marks the current position.
    `boolean` | `markSupported()` Tests whether mark is supported.
    `protected int` | `processChar()` Returns a character value for the `read()` method.
    `protected void` | `processChars(char[] chars, int offset, int length)` Process the characters for the `read(char[], offset, length)` method.
    `int` | `read()` Reads a character.
    `int` | `read(char[] chars)` Reads some characters into the specified array.
    `int` | `read(char[] chars, int offset, int length)` Reads the specified number characters into an array.
    `void` | `reset()` Resets the stream to the point when mark was last called.
    `long` | `skip(long numberOfChars)` Skips a specified number of characters.

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

      `read, ready`

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

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

- - ### Field Detail

    - #### INSTANCE

          public static final NullReader INSTANCE

      The singleton instance.

  - ### Constructor Detail

    - #### NullReader

          public NullReader()

      Constructs a `Reader` that emulates a size 0 reader which supports marking and does not throw EOFException.

    - #### NullReader

          public NullReader(long size)

      Constructs a `Reader` that emulates a specified size which supports marking and does not throw EOFException.
      Parameters:
        `size` - The size of the reader to emulate.

    - #### NullReader

          public NullReader(long size,
                            boolean markSupported,
                            boolean throwEofException)

      Constructs a `Reader` that emulates a specified size with option settings.
      Parameters:
        `size` - The size of the reader to emulate.
        `markSupported` - Whether this instance will support the `mark()` functionality.
        `throwEofException` - Whether this implementation will throw an `EOFException` or return -1 when the end of file is reached.

  - ### Method Detail

    - #### close

          public void close()
                     throws IOException

      Closes this Reader. Resets the internal state to the initial values.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in class `Reader`
      Throws:
        `IOException` - If an error occurs.

    - #### getPosition

          public long getPosition()

      Gets the current position.
      Returns:
        the current position.

    - #### getSize

          public long getSize()

      Gets the size this `Reader` emulates.
      Returns:
        The size of the reader to emulate.

    - #### mark

          public void mark(int readLimit)

      Marks the current position.
      Overrides:
        `mark` in class `Reader`
      Parameters:
        `readLimit` - The number of characters before this marked position is invalid.
      Throws:
        `UnsupportedOperationException` - if mark is not supported.

    - #### markSupported

          public boolean markSupported()

      Tests whether mark is supported.
      Overrides:
        `markSupported` in class `Reader`
      Returns:
        Whether mark is supported or not.

    - #### processChar

          protected int processChar()

      Returns a character value for the `read()` method.

      This implementation returns zero.

      Returns:
        This implementation always returns zero.

    - #### processChars

          protected void processChars(char[] chars,
                                      int offset,
                                      int length)

      Process the characters for the `read(char[], offset, length)` method.

      This implementation leaves the character array unchanged.

      Parameters:
        `chars` - The character array
        `offset` - The offset to start at.
        `length` - The number of characters.

    - #### read

          public int read()
                   throws IOException

      Reads a character.
      Overrides:
        `read` in class `Reader`
      Returns:
        Either The character value returned by `processChar()` or `-1` if the end of file has been reached and `throwEofException` is set to `false`.
      Throws:
        `EOFException` - if the end of file is reached and `throwEofException` is set to `true`.
        `IOException` - if trying to read past the end of file.

    - #### read

          public int read(char[] chars)
                   throws IOException

      Reads some characters into the specified array.
      Overrides:
        `read` in class `Reader`
      Parameters:
        `chars` - The character array to read into
      Returns:
        The number of characters read or `-1` if the end of file has been reached and `throwEofException` is set to `false`.
      Throws:
        `EOFException` - if the end of file is reached and `throwEofException` is set to `true`.
        `IOException` - if trying to read past the end of file.

    - #### read

          public int read(char[] chars,
                          int offset,
                          int length)
                   throws IOException

      Reads the specified number characters into an array.
      Specified by:
        `read` in class `Reader`
      Parameters:
        `chars` - The character array to read into.
        `offset` - The offset to start reading characters into.
        `length` - The number of characters to read.
      Returns:
        The number of characters read or `-1` if the end of file has been reached and `throwEofException` is set to `false`.
      Throws:
        `EOFException` - if the end of file is reached and `throwEofException` is set to `true`.
        `IOException` - if trying to read past the end of file.

    - #### reset

          public void reset()
                     throws IOException

      Resets the stream to the point when mark was last called.
      Overrides:
        `reset` in class `Reader`
      Throws:
        `UnsupportedOperationException` - if mark is not supported.
        `IOException` - If no position has been marked or the read limit has been exceeded since the last position was marked.

    - #### skip

          public long skip(long numberOfChars)
                    throws IOException

      Skips a specified number of characters.
      Overrides:
        `skip` in class `Reader`
      Parameters:
        `numberOfChars` - The number of characters to skip.
      Returns:
        The number of characters skipped or `-1` if the end of file has been reached and `throwEofException` is set to `false`.
      Throws:
        `EOFException` - if the end of file is reached and `throwEofException` is set to `true`.
        `IOException` - if trying to read past the end of file.