ServletInputStream (Servlet 4.0 API Documentation - Apache Tomcat 9.0.106)
Description: declaration: package: javax.servlet, class: ServletInputStream

# Class ServletInputStream

java.lang.Object
java.io.InputStream
javax.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()`
  Can data be read from this InputStream without blocking?
  `int`
  `readLine(byte[] b, int off, int len)`
  Reads the input stream, one line at a time.
  `abstract void`
  `setReadListener(ReadListener listener)`
  Sets the `ReadListener` for this `ServletInputStream` and thereby switches to non-blocking IO.

  ### Methods inherited from class java.io.InputStream

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

  ### Methods inherited from class java.lang.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

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

    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:
      `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()
    Can data be read from this InputStream without blocking? Returns If this method is called and returns false, the container will invoke `ReadListener.onDataAvailable()` when data is available.
    Returns:
      `true` if data can be read without blocking, else `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