org.apache.commons.io.input

## Class NullInputStream

- java.lang.Object
- - java.io.InputStream
  - - org.apache.commons.io.input.AbstractInputStream
    - - org.apache.commons.io.input.NullInputStream

- All Implemented Interfaces:
    Closeable, AutoCloseable

      public class NullInputStream
      extends AbstractInputStream

  A lightweight `InputStream` that emulates a stream of a specified size.

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

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

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

        public class TestInputStream extends NullInputStream {

            public TestInputStream(int size) {
                super(size);
            }

            protected int processByte() {
                return ... // return required value here
            }

            protected void processBytes(byte[] bytes, int offset, int length) {
                for (int i = offset; i < length; i++) {
                    bytes[i] = ... // set array value here
                }
            }
        }

  This class is not thread-safe.

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `available()`
    `void` | `close()` Closes this input stream.
    `long` | `getPosition()` Gets the current position.
    `long` | `getSize()` Gets the size this `InputStream` emulates.
    `NullInputStream` | `init()` Initializes or re-initializes this instance for reuse.
    `void` | `mark(int readLimit)` Marks the current position.
    `boolean` | `markSupported()` Tests whether mark is supported.
    `protected int` | `processByte()` Returns a byte value for the `read()` method.
    `protected void` | `processBytes(byte[] bytes, int offset, int length)` Processes the bytes for the `read(byte[], offset, length)` method.
    `int` | `read()` Reads a byte.
    `int` | `read(byte[] bytes)` Reads some bytes into the specified array.
    `int` | `read(byte[] bytes, int offset, int length)` Reads the specified number bytes into an array.
    `void` | `reset()` Resets the stream to the point when mark was last called.
    `long` | `skip(long numberOfBytes)` Skips a specified number of bytes.

    - ### Methods inherited from class org.apache.commons.io.input.AbstractInputStream

      `checkOpen, isClosed, setClosed`

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

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

- - ### Constructor Detail

    - #### NullInputStream

          public NullInputStream()

      Constructs an `InputStream` that emulates a size 0 stream which supports marking and does not throw EOFException.

      This is an "empty" input stream.

    - #### NullInputStream

          public NullInputStream(long size)

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

    - #### NullInputStream

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

      Constructs an `InputStream` that emulates a specified size with option settings.
      Parameters:
        `size` - The size of the input stream 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

    - #### available

          public int available()

      Overrides:
        `available` in class `InputStream`

    - #### close

          public void close()
                     throws IOException

      Closes this input stream.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Overrides:
        `close` in class `AbstractInputStream`
      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 `InputStream` emulates.
      Returns:
        The size of the input stream to emulate.

    - #### init

          public NullInputStream init()

      Initializes or re-initializes this instance for reuse.
      Returns:
        this instance.

    - #### mark

          public void mark(int readLimit)

      Marks the current position.
      Overrides:
        `mark` in class `InputStream`
      Parameters:
        `readLimit` - The number of bytes 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 `InputStream`
      Returns:
        Whether mark is supported or not.

    - #### processByte

          protected int processByte()

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

      This implementation returns zero.

      Returns:
        This implementation always returns zero.

    - #### processBytes

          protected void processBytes(byte[] bytes,
                                      int offset,
                                      int length)

      Processes the bytes for the `read(byte[], offset, length)` method.

      This implementation leaves the byte array unchanged.

      Parameters:
        `bytes` - The byte array
        `offset` - The offset to start at.
        `length` - The number of bytes.

    - #### read

          public int read()
                   throws IOException

      Reads a byte.
      Specified by:
        `read` in class `InputStream`
      Returns:
        Either The byte value returned by `processByte()` 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(byte[] bytes)
                   throws IOException

      Reads some bytes into the specified array.
      Overrides:
        `read` in class `InputStream`
      Parameters:
        `bytes` - The byte array to read into
      Returns:
        The number of bytes 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(byte[] bytes,
                          int offset,
                          int length)
                   throws IOException

      Reads the specified number bytes into an array.
      Overrides:
        `read` in class `InputStream`
      Parameters:
        `bytes` - The byte array to read into.
        `offset` - The offset to start reading bytes into.
        `length` - The number of bytes to read.
      Returns:
        The number of bytes 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 `InputStream`
      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 numberOfBytes)
                    throws IOException

      Skips a specified number of bytes.
      Overrides:
        `skip` in class `InputStream`
      Parameters:
        `numberOfBytes` - The number of bytes to skip.
      Returns:
        The number of bytes 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.