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

Since:
  1.3

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final NullInputStream`
  `INSTANCE`
  Deprecated.
  Not reusable without calling `init()` to reset state.

- ## Constructor Summary

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

  Modifier and Type
  Method
  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

  `isClosed, setClosed`

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

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

- ## Field Details

  - ### INSTANCE

    @Deprecated public static final NullInputStream INSTANCE
    Deprecated.
    Not reusable without calling `init()` to reset state.
    The singleton instance.

    Since instances hold state, call `init()` to reuse.

    Since:
      2.12.0

- ## Constructor Details

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

    Since:
      2.7

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

  - ### available

    public int available()
    Overrides:
      `available` in class `InputStream`

  - ### close

    public void close() throws IOException
    Closes this input stream.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    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.
    Since:
      2.17.0

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