Package 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, light weight `Reader` that emulates a reader of a specified size.

This implementation provides a light weight 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
              }
          }
      }

Since:
  1.3

- ## Field Summary

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

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

  `lock`

- ## Constructor Summary

  Constructors
  Constructor
  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

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Closes this Reader - resets the internal state to the initial values.
  `long`
  `getPosition()`
  Returns the current position.
  `long`
  `getSize()`
  Returns the size this `Reader` emulates.
  `void`
  `mark(int readLimit)`
  Marks the current position.
  `boolean`
  `markSupported()`
  Indicates 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 Details

  - ### INSTANCE

    public static final NullReader INSTANCE
    The singleton instance.
    Since:
      2.12.0

- ## Constructor Details

  - ### NullReader

    public NullReader()
    Constructs a `Reader` that emulates a size 0 reader which supports marking and does not throw EOFException.
    Since:
      2.7

  - ### 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 Details

  - ### close

    public void close() throws IOException
    Closes this Reader - resets the internal state to the initial values.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Specified by:
      `close` in class `Reader`
    Throws:
      `IOException` - If an error occurs.

  - ### getPosition

    public long getPosition()
    Returns the current position.
    Returns:
      the current position.

  - ### getSize

    public long getSize()
    Returns 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()
    Indicates 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.