Module jakarta.servlet

Package jakarta.servlet

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()	Returns true when all the data from the stream has been read else it returns false.
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 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, nullInputStream, read, read, read, 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

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

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

See Also:

• ReadListener

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

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