Interface Stream.Listener

All Known Implementing Classes:
HTTP2ServerConnectionFactory.HTTPServerSessionListener
Enclosing interface:
Stream
public static interface Stream.Listener

A Stream.Listener is the passive counterpart of a Stream and receives events happening on an HTTP/2 stream.

HTTP/2 data is flow controlled - this means that only a finite number of data events are delivered, until the flow control window is exhausted.

Applications control the delivery of data events by requesting them via Stream.demand(); the first event is always delivered, while subsequent events must be explicitly demanded.

Applications control the HTTP/2 flow control by completing the callback associated with data events - this allows the implementation to recycle the data buffer and eventually to enlarge the flow control window so that the sender can send more data.

See Also:

  • Field Details

  • Method Details

    • onNewStream

      default void onNewStream(Stream stream)

      Callback method invoked when a stream is created locally by Session.newStream(HeadersFrame, Promise, Listener).

      Parameters:
      stream - the newly created stream

    • onHeaders

      default void onHeaders(Stream stream, HeadersFrame frame)

      Callback method invoked when a HEADERS frame representing the HTTP response has been received.

      This overload version should be used for simple synchronous implementations.

      Parameters:
      stream - the stream
      frame - the HEADERS frame received

    • onHeaders

      default void onHeaders(Stream stream, HeadersFrame frame, Callback callback)

      Callback method invoked when a HEADERS frame representing the HTTP response has been received.

      This overload version allows for asynchronous implementations.

      Parameters:
      stream - the stream
      frame - the HEADERS frame received
      callback - the callback to notify when the processing is complete

    • onPush

      default Stream.Listener onPush(Stream stream, PushPromiseFrame frame)

      Callback method invoked when a PUSH_PROMISE frame has been received.

      Applications that override this method are typically interested in processing the pushed stream DATA frames, and must demand for pushed DATA frames via Stream.demand() and then return a Stream.Listener implementation that overrides either onDataAvailable(Stream) or onDataAvailable(Stream, boolean), where applications can read from the Stream via Stream.readData(), or return AUTO_DISCARD that automatically reads and discards DATA frames. Returning null is possible but discouraged, and has the same effect of demanding and discarding the pushed DATA frames.

      Parameters:
      stream - the pushed stream
      frame - the PUSH_PROMISE frame received
      Returns:
      a Stream.Listener that will be notified of pushed stream events

    • onDataAvailable

      default void onDataAvailable(Stream stream)

      A simplified version of onDataAvailable(Stream, boolean).

      The default implementation of this method reads and discards data.

      Parameters:
      stream - the stream
      See Also:

    • onDataAvailable

      default void onDataAvailable(Stream stream, boolean immediate)

      Callback method invoked if the application has expressed demand for DATA frames, and if there is content available.

      Applications that wish to handle DATA frames should call Stream.demand() for this method to be invoked when the data is available.

      Server applications should typically demand from onNewStream(Stream) (upon receiving an HTTP request), while client applications should typically demand from onHeaders(Stream, HeadersFrame) (upon receiving an HTTP response).

      Just prior calling this method, the outstanding demand is cancelled; applications that implement this method should read content calling Stream.readData(), and call Stream.demand() to signal to the implementation to call again this method when there may be more content available.

      Only one thread at a time invokes this method, although it may not be the same thread across different invocations.

      It is always guaranteed that invoking Stream.demand() from within this method will not cause a StackOverflowError.

      Typical usage:

      class MyStreamListener implements Stream.Listener
{
    @Override
    public void onDataAvailable(Stream stream, boolean immediate)
    {
        // Read a chunk of the content.
        Stream.Data data = stream.readData();
        if (data == null)
        {
            // No data available now, demand to be called back.
            stream.demand();
        }
        else
        {
            // Process the content.
            process(data.frame().getByteBuffer());
            // Notify that the content has been consumed.
            data.release();
            if (!data.frame().isEndStream())
            {
                // Demand to be called back.
                stream.demand();
            }
        }
    }
}

      The default implementation of this method calls onDataAvailable(Stream).

      Parameters:
      stream - the stream
      immediate - true when data is immediately available at the time Stream.demand() is invoked (this method is directly invoked from Stream.demand(); false when data was not immediately available at the time Stream.demand() was called, but is now available (this method is invoked from the network layer, not directly from Stream.demand()
      See Also:

    • onReset

      default void onReset(Stream stream, ResetFrame frame, Callback callback)

      Callback method invoked when a RST_STREAM frame has been received for this stream.

      Parameters:
      stream - the stream
      frame - the RST_STREAM frame received
      callback - the callback to complete when the reset has been handled

    • onIdleTimeout

      default void onIdleTimeout(Stream stream, TimeoutException x, Promise<Boolean> promise)

      Callback method invoked when the stream exceeds its idle timeout.

      Parameters:
      stream - the stream
      x - the timeout failure
      promise - the promise to complete
      See Also:

    • onFailure

      default void onFailure(Stream stream, int error, String reason, Throwable failure, Callback callback)

      Callback method invoked when the stream failed.

      Parameters:
      stream - the stream
      error - the error code
      reason - the error reason, or null
      failure - the failure
      callback - the callback to complete when the failure has been handled

    • onClosed

      default void onClosed(Stream stream)

      Callback method invoked after the stream has been closed.

      Parameters:
      stream - the stream