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.

Author:
Various
See Also:

  • 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 (i.e.
    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 writeListener)
    Instructs the ServletOutputStream to invoke the provided WriteListener when it is possible to write
    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 (i.e. write(), print() println() 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
      See Also:

    • setWriteListener

      public abstract void setWriteListener(WriteListener writeListener)
      Instructs the ServletOutputStream to invoke the provided WriteListener when it is possible to write
      Parameters:
      writeListener - the WriteListener that should be notified when it's possible to write
      Throws:
      IllegalStateException - if one of the following conditions is true
      • the associated request is neither upgraded nor the async started
      • setWriteListener is called more than once within the scope of the same request.
      NullPointerException - if writeListener 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