Jakarta EE 11.0.0 · jakarta.servlet.ServletInputStream

Access	Constructor and Description
protected	ServletInputStream() Does nothing, because this is an abstract class.

Method Summary

Modifier and Type	Method and Description
public abstract boolean	Returns: `true` when all data for this particular request has been read, otherwise returns `false`. isFinished() Returns true when all the data from the stream has been read else it returns false.
public abstract boolean	Returns: `true` if data can be obtained without blocking, otherwise returns `false`. isReady() Returns `true` if it is allowable to call a `read()` method.
public int	Returns: The number of bytes read or `-1` if the end of the stream has been reached. read(ByteBuffer The buffer into which the data is read. buffer) Reads from the input stream into the given buffer.
public byte[]	readAllBytes() Overrides java.io.InputStream.readAllBytes. Reads all remaining bytes from the input stream.
public int	Returns: an integer specifying the actual number of bytes read, or -1 if the end of the stream is reached readLine(byte[] an array of bytes into which data is read b, int an integer specifying the character at which this method begins reading off, int an integer specifying the maximum number of bytes to read len) Reads the input stream, one line at a time.
public byte[]	readNBytes(int the maximum number of bytes to read len) Overrides java.io.InputStream.readNBytes. Reads up to a specified number of bytes from the input stream.
public int	readNBytes(byte[] the byte array into which the data is read b, int the start offset in `b` at which the data is written off, int the maximum number of bytes to read len) Overrides java.io.InputStream.readNBytes. Reads the requested number of bytes from the input stream into the given byte array.
public abstract void	setReadListener(ReadListener the `ReadListener` that should be notified when it's possible to read. readListener) Instructs the `ServletInputStream` to invoke the provided `ReadListener` when it is possible to read

Inherited from java.io.InputStream:: available close mark markSupported nullInputStream read read read reset skip skipNBytes transferTo

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

Method Detail

isFinished back to summary

isFinished	back to summary
public abstract boolean isFinished() Returns true when all the data from the stream has been read else it returns false. Returns:boolean `true` when all data for this particular request has been read, otherwise returns `false`. Since Servlet 3.1

public abstract boolean isFinished()

Returns true when all the data from the stream has been read else it returns false.

Returns:boolean: true when all data for this particular request has been read, otherwise returns false.
Since: Servlet 3.1

isReady back to summary

isReady	back to summary
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:boolean `true` if data can be obtained without blocking, otherwise returns `false`. Since Servlet 3.1 See Also `ReadListener`

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:boolean: true if data can be obtained without blocking, otherwise returns false.
Since: Servlet 3.1
See Also: ReadListener

read back to summary

read	back to summary
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:ByteBuffer The buffer into which the data is read. Returns:int The number of bytes read or `-1` if the end of the stream has been reached. Exceptions 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. 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. NullPointerException: If buffer is null. Since Servlet 6.1

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:ByteBuffer: The buffer into which the data is read.

Returns:int

The number of bytes read or -1 if the end of the stream has been reached.

Exceptions

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.
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.
NullPointerException:: If buffer is null.

Since

Servlet 6.1

readAllBytes	back to summary
public byte[] readAllBytes() throws IOException Overrides java.io.InputStream.readAllBytes. Doc from java.io.InputStream.readAllBytes. Reads all remaining bytes from the input stream. This method blocks until all remaining bytes have been read and end of stream is detected, or an exception is thrown. This method does not close the input stream. When this stream reaches end of stream, further invocations of this method will return an empty byte array. Note that this method is intended for simple cases where it is convenient to read all bytes into a byte array. It is not intended for reading input streams with large amounts of data. The behavior for the case where the input stream is asynchronously closed, or the thread interrupted during the read, is highly input stream specific, and therefore not specified. If an I/O error occurs reading from the input stream, then it may do so after some, but not all, bytes have been read. Consequently the input stream may not be at end of stream and may be in an inconsistent state. It is strongly recommended that the stream be promptly closed if an I/O error occurs. This method may only be used when the input stream is in blocking mode. Returns:byte[] a byte array containing the bytes read from this input stream Annotations @Override Exceptions IOException: if an I/O error occurs IllegalStateException: If this method is called when the input stream is in non-blocking mode.

readAllBytes

back to summary

public byte[] readAllBytes() throws IOException

Overrides java.io.InputStream.readAllBytes.

Doc from java.io.InputStream.readAllBytes.

Reads all remaining bytes from the input stream. This method blocks until all remaining bytes have been read and end of stream is detected, or an exception is thrown. This method does not close the input stream.

When this stream reaches end of stream, further invocations of this method will return an empty byte array.

Note that this method is intended for simple cases where it is convenient to read all bytes into a byte array. It is not intended for reading input streams with large amounts of data.

The behavior for the case where the input stream is asynchronously closed, or the thread interrupted during the read, is highly input stream specific, and therefore not specified.

If an I/O error occurs reading from the input stream, then it may do so after some, but not all, bytes have been read. Consequently the input stream may not be at end of stream and may be in an inconsistent state. It is strongly recommended that the stream be promptly closed if an I/O error occurs.

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

Returns:byte[]

a byte array containing the bytes read from this input stream

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs
IllegalStateException:: If this method is called when the input stream is in non-blocking mode.

readLine back to summary

readLine	back to summary
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:byte[] an array of bytes into which data is read off:int an integer specifying the character at which this method begins reading len:int an integer specifying the maximum number of bytes to read Returns:int an integer specifying the actual number of bytes read, or -1 if the end of the stream is reached Exceptions IOException: if an input or output exception has occurred IllegalStateException: If this method is called when the input stream is in non-blocking mode.

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:byte[]: an array of bytes into which data is read
off:int: an integer specifying the character at which this method begins reading
len:int: an integer specifying the maximum number of bytes to read

Returns:int

an integer specifying the actual number of bytes read, or -1 if the end of the stream is reached

Exceptions

IOException:: if an input or output exception has occurred
IllegalStateException:: If this method is called when the input stream is in non-blocking mode.

readNBytes back to summary

readNBytes	back to summary
public byte[] readNBytes(int len) throws IOException Overrides java.io.InputStream.readNBytes. Doc from java.io.InputStream.readNBytes. Reads up to a specified number of bytes from the input stream. This method blocks until the requested number of bytes has been read, end of stream is detected, or an exception is thrown. This method does not close the input stream. The length of the returned array equals the number of bytes read from the stream. If `len` is zero, then no bytes are read and an empty byte array is returned. Otherwise, up to `len` bytes are read from the stream. Fewer than `len` bytes may be read if end of stream is encountered. When this stream reaches end of stream, further invocations of this method will return an empty byte array. Note that this method is intended for simple cases where it is convenient to read the specified number of bytes into a byte array. The total amount of memory allocated by this method is proportional to the number of bytes read from the stream which is bounded by `len`. Therefore, the method may be safely called with very large values of `len` provided sufficient memory is available. The behavior for the case where the input stream is asynchronously closed, or the thread interrupted during the read, is highly input stream specific, and therefore not specified. If an I/O error occurs reading from the input stream, then it may do so after some, but not all, bytes have been read. Consequently the input stream may not be at end of stream and may be in an inconsistent state. It is strongly recommended that the stream be promptly closed if an I/O error occurs. This method may only be used when the input stream is in blocking mode. Parameters len:int the maximum number of bytes to read Returns:byte[] a byte array containing the bytes read from this input stream Annotations @Override Exceptions IOException: if an I/O error occurs IllegalStateException: If this method is called when the input stream is in non-blocking mode.

public byte[] readNBytes(int len) throws IOException

Overrides java.io.InputStream.readNBytes.

Doc from java.io.InputStream.readNBytes.

Reads up to a specified number of bytes from the input stream. This method blocks until the requested number of bytes has been read, end of stream is detected, or an exception is thrown. This method does not close the input stream.

The length of the returned array equals the number of bytes read from the stream. If len is zero, then no bytes are read and an empty byte array is returned. Otherwise, up to len bytes are read from the stream. Fewer than len bytes may be read if end of stream is encountered.

When this stream reaches end of stream, further invocations of this method will return an empty byte array.

Note that this method is intended for simple cases where it is convenient to read the specified number of bytes into a byte array. The total amount of memory allocated by this method is proportional to the number of bytes read from the stream which is bounded by len. Therefore, the method may be safely called with very large values of len provided sufficient memory is available.

The behavior for the case where the input stream is asynchronously closed, or the thread interrupted during the read, is highly input stream specific, and therefore not specified.

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

Parameters

len:int: the maximum number of bytes to read

Returns:byte[]

a byte array containing the bytes read from this input stream

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs
IllegalStateException:: If this method is called when the input stream is in non-blocking mode.

readNBytes back to summary

readNBytes	back to summary
public int readNBytes(byte[] b, int off, int len) throws IOException Overrides java.io.InputStream.readNBytes. Doc from java.io.InputStream.readNBytes. Reads the requested number of bytes from the input stream into the given byte array. This method blocks until `len` bytes of input data have been read, end of stream is detected, or an exception is thrown. The number of bytes actually read, possibly zero, is returned. This method does not close the input stream. In the case where end of stream is reached before `len` bytes have been read, then the actual number of bytes read will be returned. When this stream reaches end of stream, further invocations of this method will return zero. If `len` is zero, then no bytes are read and `0` is returned; otherwise, there is an attempt to read up to `len` bytes. The first byte read is stored into element `b[off]`, the next one in to `b[off+1]`, and so on. The number of bytes read is, at most, equal to `len`. Let k be the number of bytes actually read; these bytes will be stored in elements `b[off]` through `b[off+`k`-1]`, leaving elements `b[off+`k `]` through `b[off+len-1]` unaffected. The behavior for the case where the input stream is asynchronously closed, or the thread interrupted during the read, is highly input stream specific, and therefore not specified. If an I/O error occurs reading from the input stream, then it may do so after some, but not all, bytes of `b` have been updated with data from the input stream. Consequently the input stream and `b` may be in an inconsistent state. It is strongly recommended that the stream be promptly closed if an I/O error occurs. This method may only be used when the input stream is in blocking mode. Parameters b:byte[] the byte array into which the data is read off:int the start offset in `b` at which the data is written len:int the maximum number of bytes to read Returns:int the actual number of bytes read into the buffer Annotations @Override Exceptions IOException: if an I/O error occurs IllegalStateException: If this method is called when the input stream is in non-blocking mode.

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

Overrides java.io.InputStream.readNBytes.

Doc from java.io.InputStream.readNBytes.

Reads the requested number of bytes from the input stream into the given byte array. This method blocks until len bytes of input data have been read, end of stream is detected, or an exception is thrown. The number of bytes actually read, possibly zero, is returned. This method does not close the input stream.

In the case where end of stream is reached before len bytes have been read, then the actual number of bytes read will be returned. When this stream reaches end of stream, further invocations of this method will return zero.

If len is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read up to len bytes.

The first byte read is stored into element b[off], the next one in to b[off+1], and so on. The number of bytes read is, at most, equal to len. Let k be the number of bytes actually read; these bytes will be stored in elements b[off] through b[off+k-1], leaving elements b[off+k ] through b[off+len-1] unaffected.

The behavior for the case where the input stream is asynchronously closed, or the thread interrupted during the read, is highly input stream specific, and therefore not specified.

If an I/O error occurs reading from the input stream, then it may do so after some, but not all, bytes of b have been updated with data from the input stream. Consequently the input stream and b may be in an inconsistent state. It is strongly recommended that the stream be promptly closed if an I/O error occurs.

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

Parameters

b:byte[]: the byte array into which the data is read
off:int: the start offset in b at which the data is written
len:int: the maximum number of bytes to read

Returns:int

the actual number of bytes read into the buffer

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs
IllegalStateException:: If this method is called when the input stream is in non-blocking mode.

setReadListener back to summary

setReadListener	back to summary
public abstract void setReadListener(ReadListener readListener) Instructs the `ServletInputStream` to invoke the provided `ReadListener` when it is possible to read Parameters readListener:ReadListener the `ReadListener` that should be notified when it's possible to read. Exceptions 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

public abstract void setReadListener(ReadListener readListener)

Instructs the ServletInputStream to invoke the provided ReadListener when it is possible to read

Parameters

readListener:ReadListener: the ReadListener that should be notified when it's possible to read.

Exceptions

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

public abstract Class ServletInputStream

Constructor Summary

Method Summary

Constructor Detail

Method Detail