javax.servlet

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

  Author:
    Various
  See Also:
    `ServletRequest`

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract boolean` | `isFinished()` Returns true when all the data from the stream has been read else it returns false.
    `abstract boolean` | `isReady()` Returns true if data can be read without blocking else returns false.
    `int` | `readLine(byte[] b, int off, int len)` Reads the input stream, one line at a time.
    `abstract void` | `setReadListener(ReadListener readListener)` Instructs the `ServletInputStream` to invoke the provided `ReadListener` when it is possible to read

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

      `available, close, mark, markSupported, read, read, read, reset, skip`

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

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

- - ### Constructor Detail

    - #### ServletInputStream

          protected ServletInputStream()

      Does nothing, because this is an abstract class.

  - ### Method Detail

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

      Returns true when all the data from the stream has been read else it returns false.
      Returns:
        `true` when all data for this particular request has been read, otherwise returns `false`.
      Since:
        Servlet 3.1

    - #### isReady

          public abstract boolean isReady()

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

    - #### setReadListener

          public abstract void setReadListener(ReadListener readListener)

      Instructs the `ServletInputStream` to invoke the provided `ReadListener` when it is possible to read
      Parameters:
        `readListener` - the `ReadListener` that should be notified when it's possible to read.
      Throws:
        `IllegalStateException` - if one of the following conditions is true
        - the associated request is neither upgraded nor the async started
        - setReadListener is called more than once within the scope of the same request.
        `NullPointerException` - if readListener is null
      Since:
        Servlet 3.1

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.