ServletOutputStream (Servlet 6.1 API Documentation - Apache Tomcat 11.0.21)
Description: declaration: package: jakarta.servlet, class: ServletOutputStream

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

  `flush, nullOutputStream, write, write, write`

  ### Methods inherited from class 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`