Package jakarta.servlet

Class ServletOutputStream

java.lang.Object

java.io.OutputStream

jakarta.servlet.ServletOutputStream

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public abstract class ServletOutputStream
extends OutputStream

Provides an output stream for sending binary data to the client. A ServletOutputStream object is normally retrieved via the ServletResponse.getOutputStream() method.

This is an abstract class that the servlet container implements. Subclasses of this class must implement the java.io.OutputStream.write(int) method.

See Also:

• ServletResponse

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
void	close()
abstract boolean	isReady()	Returns true if it is allowable to call any method that may write data (e.g.
void	print(boolean b)	Writes a boolean value to the client, with no carriage return-line feed (CRLF) character at the end.
void	print(char c)	Writes a character to the client, with no carriage return-line feed (CRLF) at the end.
void	print(double d)	Writes a double value to the client, with no carriage return-line feed (CRLF) at the end.
void	print(float f)	Writes a float value to the client, with no carriage return-line feed (CRLF) at the end.
void	print(int i)	Writes an int to the client, with no carriage return-line feed (CRLF) at the end.
void	print(long l)	Writes a long value to the client, with no carriage return-line feed (CRLF) at the end.
void	print(String s)	Writes a String to the client, without a carriage return-line feed (CRLF) character at the end.
void	println()	Writes a carriage return-line feed (CRLF) to the client.
void	println(boolean b)	Writes a boolean value to the client, followed by a carriage return-line feed (CRLF).
void	println(char c)	Writes a character to the client, followed by a carriage return-line feed (CRLF).
void	println(double d)	Writes a double value to the client, followed by a carriage return-line feed (CRLF).
void	println(float f)	Writes a float value to the client, followed by a carriage return-line feed (CRLF).
void	println(int i)	Writes an int to the client, followed by a carriage return-line feed (CRLF) character.
void	println(long l)	Writes a long value to the client, followed by a carriage return-line feed (CRLF).
void	println(String s)	Writes a String to the client, followed by a carriage return-line feed (CRLF).
abstract void	setWriteListener(WriteListener listener)	Sets the WriteListener for this ServletOutputStream and thereby switches to non-blocking IO.
void	write(ByteBuffer buffer)	Writes from the given buffer to the output stream.

Methods inherited from class java.io.OutputStream

flush, nullOutputStream, write, write, write

Methods inherited from class java.lang.Object

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

Constructor Details

ServletOutputStream

protected ServletOutputStream()

Does nothing, because this is an abstract class.

Method Details

write

public void write(ByteBuffer buffer)
           throws IOException

Writes from the given buffer to the output stream.

If the output steam is in non-blocking mode, before each invocation of this method isReady() must be called and must return true or the WriteListener.onWritePossible() call back must indicate that data may be written else an IllegalStateException must be thrown.

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

If the output stream is in non-blocking mode, neither the position, limit nor content of the buffer passed to this method may be modified until a subsequent call to isReady() returns true or the WriteListener.onWritePossible() call back indicates data may be written again. At this point the buffer's limit will be unchanged from the value when passed to this method and the position will be the same as the limit.

If the output stream is in blocking mode and buffer has space remaining, this method blocks until all the remaining data in the buffer has been written. When the method returns, and if data has been written, the buffer's limit will be unchanged from the value when passed to this method and the position will be the same as the limit.

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

Parameters:

buffer - The buffer from which the data is written.

Throws:

IllegalStateException - If the output stream is in non-blocking mode and this method is called without first calling isReady() and that method has returned true or WriteListener.onWritePossible() has not signalled that data may be written.

IOException - If the output stream has been closed or if some other I/O error occurs.

NullPointerException - If buffer is null.

Since:

Servlet 6.1

print

public void print(String s)
           throws IOException

Writes a String to the client, without a carriage return-line feed (CRLF) character at the end.

Parameters:

s - the String to send to the client

Throws:

IOException - if an input or output exception occurred

print

public void print(boolean b)
           throws IOException

Writes a boolean value to the client, with no carriage return-line feed (CRLF) character at the end.

Parameters:

b - the boolean value to send to the client

Throws:

IOException - if an input or output exception occurred

print

public void print(char c)
           throws IOException

Writes a character to the client, with no carriage return-line feed (CRLF) at the end.

Parameters:

c - the character to send to the client

Throws:

IOException - if an input or output exception occurred

print

public void print(int i)
           throws IOException

Writes an int to the client, with no carriage return-line feed (CRLF) at the end.

Parameters:

i - the int to send to the client

Throws:

IOException - if an input or output exception occurred

print

public void print(long l)
           throws IOException

Writes a long value to the client, with no carriage return-line feed (CRLF) at the end.

Parameters:

l - the long value to send to the client

Throws:

IOException - if an input or output exception occurred

print

public void print(float f)
           throws IOException

Writes a float value to the client, with no carriage return-line feed (CRLF) at the end.

Parameters:

f - the float value to send to the client

Throws:

IOException - if an input or output exception occurred

print

public void print(double d)
           throws IOException

Writes a double value to the client, with no carriage return-line feed (CRLF) at the end.

Parameters:

d - the double value to send to the client

Throws:

IOException - if an input or output exception occurred

println

public void println()
             throws IOException

Writes a carriage return-line feed (CRLF) to the client.

Throws:

IOException - if an input or output exception occurred

println

public void println(String s)
             throws IOException

Writes a String to the client, followed by a carriage return-line feed (CRLF).

Parameters:

s - the String to write to the client

Throws:

IOException - if an input or output exception occurred

println

public void println(boolean b)
             throws IOException

Writes a boolean value to the client, followed by a carriage return-line feed (CRLF).

Parameters:

b - the boolean value to write to the client

Throws:

IOException - if an input or output exception occurred

println

public void println(char c)
             throws IOException

Writes a character to the client, followed by a carriage return-line feed (CRLF).

Parameters:

c - the character to write to the client

Throws:

IOException - if an input or output exception occurred

println

public void println(int i)
             throws IOException

Writes an int to the client, followed by a carriage return-line feed (CRLF) character.

Parameters:

i - the int to write to the client

Throws:

IOException - if an input or output exception occurred

println

public void println(long l)
             throws IOException

Writes a long value to the client, followed by a carriage return-line feed (CRLF).

Parameters:

l - the long value to write to the client

Throws:

IOException - if an input or output exception occurred

println

public void println(float f)
             throws IOException

Writes a float value to the client, followed by a carriage return-line feed (CRLF).

Parameters:

f - the float value to write to the client

Throws:

IOException - if an input or output exception occurred

println

public void println(double d)
             throws IOException

Writes a double value to the client, followed by a carriage return-line feed (CRLF).

Parameters:

d - the double value to write to the client

Throws:

IOException - if an input or output exception occurred

isReady

public abstract boolean isReady()

Returns true if it is allowable to call any method that may write data (e.g. write(), print() or flush). In blocking mode, this method will always return true, but a subsequent call to a method that writes data may block. In non-blocking mode this method may return false, in which case it is illegal to call a method that writes data and an IllegalStateException MUST be thrown. When WriteListener.onWritePossible() is called, a call to this method that returned true is implicit.

If this method returns false and a WriteListener has been set via setWriteListener(WriteListener), then container will subsequently invoke WriteListener.onWritePossible() once a write operation becomes possible without blocking. Other than the initial call, WriteListener.onWritePossible() will only be called if and only if this method is called and returns false.

Returns:

true if data can be written without blocking, otherwise returns false.

Since:

Servlet 3.1

setWriteListener

public abstract void setWriteListener(WriteListener listener)

Sets the WriteListener for this ServletOutputStream 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 write listener

Throws:

IllegalStateException - If this method is called if neither async nor HTTP upgrade is in progress or if the WriteListener has already been set

NullPointerException - If listener is null

Since:

Servlet 3.1

close

public void close()
           throws IOException

If this method is called when the output stream is in non-blocking mode, it will immediately return with the stream effectively closed, even if the stream contains buffered data that is yet to be written to client. The container will write this data out in the background. If this process fails the WriteListener.onError(Throwable) method will be invoked as normal.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Overrides:

close in class OutputStream

Throws:

IOException