Interface Stream.Listener

All Superinterfaces:
EventListener
All Known Implementing Classes:
ProtocolStreamListener, ProtocolStreamListener.Client, ProtocolStreamListener.Server
Enclosing interface:
Stream
public static interface Stream.Listener extends EventListener

A Stream.Listener is the passive counterpart of a Stream and receives events, triggered by the remote peer, happening on stream.

Stream data is requested using Stream.demand() and when data is available onDataAvailable(Stream, boolean) is invoked.

See Also:

  • Method Details

    • onNewStream

      default void onNewStream(Stream stream, Frame.WithStreamId frame)

      Callback method invoked when receiving a frame that causes the creation of a new stream.

      Parameters:
      stream - the newly created stream
      frame - the frame that caused the creation of the stream

    • 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 when the application has expressed demand for data carried by STREAM frames, and there are STREAM frames available.

      Server applications should typically demand from onNewStream(Stream, Frame.WithStreamId) (upon receiving the first stream frame), while client applications should typically demand after obtaining a Stream via Session.newStream(long, Listener).

      Just prior calling this method, the outstanding demand is cancelled; applications that implement this method should read content calling Stream.read(), and call Stream.demand() to signal to the implementation to call again this method when there may be more data 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)
    {
        while (true)
        {
            // Read a chunk of the content.
            Content.Chunk chunk = stream.read();
            if (chunk == null)
            {
                // No data available now, demand to be called back.
                stream.demand();
                return;
            }

            // Process the content chunk.
            process(chunk);

            // Notify that the content has been consumed.
            chunk.release();

            if (chunk.isLast())
            {
                // All data has been processed.
                return;
            }
        }
    }
}

      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:

    • onDataBlocked

      default void onDataBlocked(Stream stream, StreamDataBlockedFrame frame)

      Invoked when a STREAM_DATA_BLOCKED frame has been received.

      This event is only emitted for informational purposes.

      Parameters:
      stream - the stream
      frame - the frame

    • onMaxData

      default void onMaxData(Stream stream, StreamMaxDataFrame frame)

      Invoked when a MAX_STREAM_DATA frame has been received.

      This event is only emitted for informational purposes.

      Parameters:
      stream - the stream
      frame - the frame

    • onStopSending

      default void onStopSending(Stream stream, StopSendingFrame frame)

      Invoked when a STOP_SENDING frame has been received.

      This event is only emitted for informational purposes.

      Parameters:
      stream - the stream
      frame - the frame

    • onReset

      default void onReset(Stream stream, ResetFrame frame)

      Invoked when a RESET_STREAM frame has been received.

      This event is only emitted for informational purposes.

      Parameters:
      stream - the stream
      frame - the frame

    • onClose

      default void onClose(Stream stream)

      Invoked when the stream has been closed.

      A stream is closed when either:

      • The receiving side read the last frame in the stream, and the sending side sent the last frame in the stream
      • The stream is disconnected, for example due to failures.
      Parameters:
      stream - the stream

    • onIdleTimeout

      default void onIdleTimeout(Stream stream, TimeoutException failure, Promise.Invocable<Boolean> promise)

      Invoked when the stream is idle for longer than the idle timeout.

      Parameters:
      stream - the stream
      failure - the idle timeout failure
      promise - the promise to complete to notify the other peer that this stream is closing

    • onFailure

      default void onFailure(Stream stream, Throwable failure)

      Invoked when a stream failure is detected.

      Parameters:
      stream - the stream
      failure - the stream failure