NullReader (Commons IO 2.5)
Date: 2016-12-01

org.apache.commons.io.input

## Class NullReader

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

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

      public class NullReader
      extends java.io.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
  Version:
    $Id: NullReader.java 1586350 2014-04-10 15:57:20Z ggregory $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private boolean` | `eof`
    `private long` | `mark`
    `private boolean` | `markSupported`
    `private long` | `position`
    `private long` | `readlimit`
    `private long` | `size`
    `private boolean` | `throwEofException`

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

      `lock`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close this Reader - resets the internal state to the initial values.
    `private int` | `doEndOfFile()` Handle End of File.
    `long` | `getPosition()` Return the current position.
    `long` | `getSize()` Return the size this `Reader` emulates.
    `void` | `mark(int readlimit)` Mark the current position.
    `boolean` | `markSupported()` Indicates whether mark is supported.
    `protected int` | `processChar()` Return 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()` Read a character.
    `int` | `read(char[] chars)` Read some characters into the specified array.
    `int` | `read(char[] chars, int offset, int length)` Read the specified number characters into an array.
    `void` | `reset()` Reset the stream to the point when mark was last called.
    `long` | `skip(long numberOfChars)` Skip 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

    - #### size

          private final long size

    - #### position

          private long position

    - #### mark

          private long mark

    - #### readlimit

          private long readlimit

    - #### eof

          private boolean eof

    - #### throwEofException

          private final boolean throwEofException

    - #### markSupported

          private final boolean markSupported

  - ### Constructor Detail

    - #### NullReader

          public NullReader(long size)

      Create 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)

      Create 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

    - #### getPosition

          public long getPosition()

      Return the current position.
      Returns:
        the current position.

    - #### getSize

          public long getSize()

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

    - #### close

          public void close()
                     throws java.io.IOException

      Close this Reader - resets the internal state to the initial values.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in class `java.io.Reader`
      Throws:
        `java.io.IOException` - If an error occurs.

    - #### mark

          public void mark(int readlimit)

      Mark the current position.
      Overrides:
        `mark` in class `java.io.Reader`
      Parameters:
        `readlimit` - The number of characters before this marked position is invalid.
      Throws:
        `java.lang.UnsupportedOperationException` - if mark is not supported.

    - #### markSupported

          public boolean markSupported()

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

    - #### read

          public int read()
                   throws java.io.IOException

      Read a character.
      Overrides:
        `read` in class `java.io.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:
        `java.io.EOFException` - if the end of file is reached and `throwEofException` is set to `true`.
        `java.io.IOException` - if trying to read past the end of file.

    - #### read

          public int read(char[] chars)
                   throws java.io.IOException

      Read some characters into the specified array.
      Overrides:
        `read` in class `java.io.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:
        `java.io.EOFException` - if the end of file is reached and `throwEofException` is set to `true`.
        `java.io.IOException` - if trying to read past the end of file.

    - #### read

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

      Read the specified number characters into an array.
      Specified by:
        `read` in class `java.io.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:
        `java.io.EOFException` - if the end of file is reached and `throwEofException` is set to `true`.
        `java.io.IOException` - if trying to read past the end of file.

    - #### reset

          public void reset()
                     throws java.io.IOException

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

    - #### skip

          public long skip(long numberOfChars)
                    throws java.io.IOException

      Skip a specified number of characters.
      Overrides:
        `skip` in class `java.io.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:
        `java.io.EOFException` - if the end of file is reached and `throwEofException` is set to `true`.
        `java.io.IOException` - if trying to read past the end of file.

    - #### processChar

          protected int processChar()

      Return 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.

    - #### doEndOfFile

          private int doEndOfFile()
                           throws java.io.EOFException

      Handle End of File.
      Returns:
        `-1` if `throwEofException` is set to `false`
      Throws:
        `java.io.EOFException` - if `throwEofException` is set to `true`.

Copyright (c) 2002-2016 Apache Software Foundation