org.apache.commons.io.input

## Class NullInputStream

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

- All Implemented Interfaces:
    Closeable, AutoCloseable

      public class NullInputStream
      extends InputStream

  A functional, light weight `InputStream` that emulates a stream of a specified size.

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

  Since:
    1.3

- - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NullInputStream()` Create an `InputStream` that emulates a size 0 stream which supports marking and does not throw EOFException.
    `NullInputStream(long size)` Create an `InputStream` that emulates a specified size which supports marking and does not throw EOFException.
    `NullInputStream(long size, boolean markSupported, boolean throwEofException)` Create 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()` Return the number of bytes that can be read.
    `void` | `close()` Close this input stream - resets the internal state to the initial values.
    `long` | `getPosition()` Return the current position.
    `long` | `getSize()` Return the size this `InputStream` emulates.
    `void` | `mark(int readlimit)` Mark the current position.
    `boolean` | `markSupported()` Indicates whether mark is supported.
    `protected int` | `processByte()` Return a byte value for the `read()` method.
    `protected void` | `processBytes(byte[] bytes, int offset, int length)` Process the bytes for the `read(byte[], offset, length)` method.
    `int` | `read()` Read a byte.
    `int` | `read(byte[] bytes)` Read some bytes into the specified array.
    `int` | `read(byte[] bytes, int offset, int length)` Read the specified number bytes into an array.
    `void` | `reset()` Reset the stream to the point when mark was last called.
    `long` | `skip(long numberOfBytes)` Skip a specified number of bytes.

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

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

- - ### Field Detail

    - #### INSTANCE

          public static final NullInputStream INSTANCE

      The singleton instance.
      Since:
        2.12.0

  - ### Constructor Detail

    - #### NullInputStream

          public NullInputStream()

      Create an `InputStream` that emulates a size 0 stream which supports marking and does not throw EOFException.
      Since:
        2.7

    - #### NullInputStream

          public NullInputStream(long size)

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

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

      Return the number of bytes that can be read.
      Overrides:
        `available` in class `InputStream`
      Returns:
        The number of bytes that can be read.

    - #### close

          public void close()
                     throws IOException

      Close this input stream - resets the internal state to the initial values.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Overrides:
        `close` in class `InputStream`
      Throws:
        `IOException` - If an error occurs.

    - #### getPosition

          public long getPosition()

      Return the current position.
      Returns:
        the current position.

    - #### getSize

          public long getSize()

      Return the size this `InputStream` emulates.
      Returns:
        The size of the input stream to emulate.

    - #### mark

          public void mark(int readlimit)

      Mark 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()

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

    - #### processByte

          protected int processByte()

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

      Process 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

      Read 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

      Read 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

      Read 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

      Reset 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

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

Copyright © 2002–2023 The Apache Software Foundation. All rights reserved.