Interface Stream

All Known Implementing Classes:
AbstractStream, QuicheStream
public interface Stream

A stream represents a unidirectional or bidirectional exchange of data within a Session.

Streams are multiplexed within a session, that is there can be multiple, different, concurrent streams present in a session.

Stream is the active part and by calling its API applications can generate events on the stream. Conversely, Stream.Listener is the passive part, and its methods are invoked when events happen on the stream.

See Also:

  • Method Details

    • getId

      long getId()

      Returns the stream id.

      Returns:
      the stream id

    • isBidirectional

      boolean isBidirectional()

      Returns whether the stream is bidirectional.

      Returns:
      whether the stream is bidirectional

    • isLocal

      boolean isLocal()

      Returns whether the stream has been created locally or remotely.

      Returns:
      whether the stream is local or remote

    • isClosed

      boolean isClosed()

      Returns whether the stream is fully closed, both locally and remotely.

      Returns:
      whether the stream is fully closed
      See Also:

    • isLocallyClosed

      boolean isLocallyClosed()

      Returns whether the stream is locally closed.

      A locally closed stream will not send further data.

      A stream becomes locally closed when either it has sent the last data, or issued a reset(long, Promise.Invocable).

      Returns:
      whether the stream is locally closed
      See Also:

    • isRemotelyClosed

      boolean isRemotelyClosed()

      Returns whether the stream is remotely closed.

      A remotely closed stream will not receive further data.

      A stream becomes remotely closed when it has read() the last data.

      Returns:
      whether the stream is remotely closed
      See Also:

    • getIdleTimeout

      long getIdleTimeout()

    • setIdleTimeout

      void setIdleTimeout(long idleTimeout)

    • getSession

      Session getSession()

      Returns the Session this stream is associated to.

      Returns:
      the Session this stream is associated to

    • read

      Content.Chunk read()

      Reads data from this stream, if any.

      The returned Content.Chunk object may be null indicating that the end of the read side of the stream has not yet been reached, which may happen when not all the bytes have been received so far, for example the remote peer did not send them yet, or they are in-flight.

      When the returned Content.Chunk object is not null, the flow control window has been enlarged by the data length. Applications must call, either immediately or later (even asynchronously from a different thread) Retainable.release() to notify the implementation that the bytes have been processed.

      Content.Chunk objects may be stored away for later, asynchronous, processing (for example, to process them only when all of them have been received).

      Once the returned Content.Chunk object indicates that the end of the read side of the stream has been reached, further calls to this method will return a Content.Chunk object with the same indication, although the instance may be different.

      Returns:
      a Content.Chunk object containing the data bytes or a failure, or null if no data bytes are available
      See Also:

    • demand

      void demand()

      Demands more data bytes for this stream.

      Calling this method causes Stream.Listener.onDataAvailable(Stream) to be invoked, possibly at a later time, when the stream has data to be read, but also when the stream has reached EOF.

      This method is idempotent: calling it when there already is an outstanding demand to invoke Stream.Listener.onDataAvailable(Stream) is a no-operation.

      The thread invoking this method may invoke directly Stream.Listener.onDataAvailable(Stream), unless another thread that must invoke Stream.Listener.onDataAvailable(Stream) notices the outstanding demand first.

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

      See Also:

    • data

      void data(boolean last, List<ByteBuffer> data, Promise.Invocable<Stream> promise)

      Sends a STREAM frame with the given data bytes and the indication of whether they are the last to be sent.

      Parameters:
      last - whether the data bytes are the last
      data - the list of data bytes to send
      promise - the Promise.Invocable that gets notified when the data has been sent

    • maxData

      void maxData(long maxData, Promise.Invocable<Stream> promise)

      Sends a MAX_STREAM_DATA frame with the new total max data bytes that this peer is willing to receive.

      Parameters:
      maxData - the max data bytes this peer is willing to receive
      promise - the Promise.Invocable that gets notified when the frame has been sent

    • reset

      void reset(long appErrorCode, Promise.Invocable<Stream> promise)

      Sends a RESET_STREAM frame, with the given application error code.

      Parameters:
      appErrorCode - the application error code
      promise - the Promise.Invocable that gets notified when the frame has been sent

    • stopSending

      void stopSending(long appErrorCode, Promise.Invocable<Stream> promise)

      Sends a STOP_SENDING frame, with the given application error code.

      Parameters:
      appErrorCode - the application error code
      promise - the Promise.Invocable that gets notified when the frame has been sent

    • dataBlocked

      void dataBlocked(long offset, Promise.Invocable<Stream> promise)

      Sends a STREAM_DATA_BLOCKED frame, with the given offset.

      Parameters:
      offset - the data offset
      promise - the Promise.Invocable that gets notified when the frame has been sent

    • disconnect

      void disconnect(long appErrorCode, Throwable failure, Promise.Invocable<Stream> promise)

      Abruptly terminates this stream with the given error.

      This method removes this stream from its session and then terminates the QUIC stream, via stopSending(long, Promise.Invocable), and then a reset(long, Promise.Invocable).

      Parameters:
      appErrorCode - the application error code
      failure - the failure that caused the disconnect of the stream
      promise - the Promise.Invocable that gets notified when the disconnect is completed