ServletInputStream (Servlet 6.1 API Documentation - Apache Tomcat 11.0.21)
Description: declaration: package: jakarta.servlet, class: ServletInputStream

# Class ServletInputStream

java.lang.Object
java.io.InputStream
jakarta.servlet.ServletInputStream

All Implemented Interfaces:
  `Closeable, AutoCloseable`

public abstract class ServletInputStream extends InputStream
Provides an input stream for reading binary data from a client request, including an efficient `readLine` method for reading data one line at a time. With some protocols, such as HTTP POST and PUT, a `ServletInputStream` object can be used to read data sent from the client.

A `ServletInputStream` object is normally retrieved via the `ServletRequest.getInputStream()` method.

This is an abstract class that a servlet container implements. Subclasses of this class must implement the `java.io.InputStream.read()` method.

See Also:
  - `ServletRequest`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ServletInputStream()`
  Does nothing, because this is an abstract class.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract boolean`
  `isFinished()`
  Has the end of this InputStream been reached?
  `abstract boolean`
  `isReady()`
  Returns `true` if it is allowable to call a `read()` method.
  `int`
  `read(ByteBuffer buffer)`
  Reads from the input stream into the given buffer.
  `byte[]`
  `readAllBytes()`
  `int`
  `readLine(byte[] b, int off, int len)`
  Reads the input stream, one line at a time.
  `int`
  `readNBytes(byte[] b, int off, int len)`
  `byte[]`
  `readNBytes(int len)`
  `abstract void`
  `setReadListener(ReadListener listener)`
  Sets the `ReadListener` for this `ServletInputStream` and thereby switches to non-blocking IO.

  ### Methods inherited from class InputStream

  `available, close, mark, markSupported, nullInputStream, read, read, read, reset, skip, skipNBytes, transferTo`

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### ServletInputStream

    protected ServletInputStream()
    Does nothing, because this is an abstract class.

- ## Method Details

  - ### read

    public int read(ByteBuffer buffer) throws IOException
    Reads from the input stream into the given buffer.

    If the input stream is in non-blocking mode, before each invocation of this method `isReady()` must be called and must return `true` or the `ReadListener.onDataAvailable()` call back must indicate that data is available to read else an `IllegalStateException` must be thrown.

    Otherwise, if this method is called when `buffer` has no space remaining, the method returns `0` immediately and `buffer` is unchanged.

    If the input stream is in blocking mode and `buffer` has space remaining, this method blocks until at least one byte has been read, end of stream is reached or an exception is thrown.

    Returns the number of bytes read or `-1` if the end of stream is reached without reading any data.

    When the method returns, and if data has been read, the buffer's position will be unchanged from the value when passed to this method and the limit will be the position incremented by the number of bytes read.

    Subclasses are strongly encouraged to override this method and provide a more efficient implementation.

    Parameters:
      `buffer` - The buffer into which the data is read.
    Returns:
      The number of bytes read or `-1` if the end of the stream has been reached.
    Throws:
      `IllegalStateException` - If the input stream is in non-blocking mode and this method is called without first calling `isReady()` and that method has returned `true` or `ReadListener.onDataAvailable()` has not signalled that data is available to read.
      `IOException` - If data cannot be read for any reason other than the end of stream being reached, the input stream has been closed or if some other I/O error occurs.
      `NullPointerException` - If buffer is null.
    Since:
      Servlet 6.1

  - ### readLine

    public int readLine(byte[] b, int off, int len) throws IOException
    Reads the input stream, one line at a time. Starting at an offset, reads bytes into an array, until it reads a certain number of bytes or reaches a newline character, which it reads into the array as well.

    This method returns -1 if it reaches the end of the input stream before reading the maximum number of bytes.

    This method may only be used when the input stream is in blocking mode.

    Parameters:
      `b` - an array of bytes into which data is read
      `off` - an integer specifying the character at which this method begins reading
      `len` - an integer specifying the maximum number of bytes to read
    Returns:
      an integer specifying the actual number of bytes read, or -1 if the end of the stream is reached
    Throws:
      `IllegalStateException` - If this method is called when the input stream is in non-blocking mode.
      `IOException` - if an input or output exception has occurred

  - ### isFinished

    public abstract boolean isFinished()
    Has the end of this InputStream been reached?
    Returns:
      `true` if all the data has been read from the stream, else `false`
    Since:
      Servlet 3.1

  - ### isReady

    public abstract boolean isReady()
    Returns `true` if it is allowable to call a `read()` method. In blocking mode, this method will always return `true`, but a subsequent call to a `read()` method may block awaiting data. In non-blocking mode this method may return `false`, in which case it is illegal to call a `read()` method and an `IllegalStateException` MUST be thrown. When `ReadListener.onDataAvailable()` is called, a call to this method that returned `true` is implicit.

    If this method returns `false` and a `ReadListener` has been set via `setReadListener(ReadListener)`, then the container will subsequently invoke `ReadListener.onDataAvailable()` (or `ReadListener.onAllDataRead()`) once data (or EOF) has become available. Other than the initial call `ReadListener.onDataAvailable()` will only be called if and only if this method is called and returns false.

    Returns:
      `true` if data can be obtained without blocking, otherwise returns `false`.
    Since:
      Servlet 3.1

  - ### setReadListener

    public abstract void setReadListener(ReadListener listener)
    Sets the `ReadListener` for this `ServletInputStream` and thereby switches to non-blocking IO. It is only valid to switch to non-blocking IO within async processing or HTTP upgrade processing.
    Parameters:
      `listener` - The non-blocking IO read listener
    Throws:
      `IllegalStateException` - If this method is called if neither async nor HTTP upgrade is in progress or if the `ReadListener` has already been set
      `NullPointerException` - If listener is null
    Since:
      Servlet 3.1

  - ### readAllBytes

    public byte[] readAllBytes() throws IOException

    This method may only be used when the input stream is in blocking mode.

    Overrides:
      `readAllBytes` in class `InputStream`
    Throws:
      `IllegalStateException` - If this method is called when the input stream is in non-blocking mode.
      `IOException`

  - ### readNBytes

    public byte[] readNBytes(int len) throws IOException

    This method may only be used when the input stream is in blocking mode.

    Overrides:
      `readNBytes` in class `InputStream`
    Throws:
      `IllegalStateException` - If this method is called when the input stream is in non-blocking mode.
      `IOException`

  - ### readNBytes

    public int readNBytes(byte[] b, int off, int len) throws IOException

    This method may only be used when the input stream is in blocking mode.

    Overrides:
      `readNBytes` in class `InputStream`
    Throws:
      `IllegalStateException` - If this method is called when the input stream is in non-blocking mode.
      `IOException`