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
Version:
  $Id$

### Constructor Summary

Constructors
Constructor and Description
`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
`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`

### Constructor Detail

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

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

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

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

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

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