Package org.eclipse.jetty.http2.api

Interface Stream

All Known Implementing Classes:
HTTP2Stream
public interface Stream

A Stream represents a bidirectional exchange of data on top of a Session.

Differently from socket streams, where the input and output streams are permanently associated with the socket (and hence with the connection that the socket represents), there can be multiple HTTP/2 streams present concurrently for an HTTP/2 session.

A Stream maps to an HTTP request/response cycle, and after the request/response cycle is completed, the stream is closed and removed from the session.

Like 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 callbacks are invoked when events happen on the stream.

See Also:

  • Method Details

    • getId

      int getId()
      Get the stream unique id.
      Returns:
      the stream unique id

    • getListener

      Stream.Listener getListener()
      Get the Stream.Listener associated with this stream.
      Returns:
      the Stream.Listener associated with this stream

    • getSession

      Session getSession()
      Get the session this stream is associated to.
      Returns:
      the session this stream is associated to

    • headers

      default CompletableFuture<Stream> headers(HeadersFrame frame)

      Sends the given HEADERS frame representing an HTTP response.

      Parameters:
      frame - the HEADERS frame to send
      Returns:
      the CompletableFuture that gets notified when the frame has been sent

    • headers

      void headers(HeadersFrame frame, Callback callback)

      Sends the given HEADERS frame.

      Typically used to send an HTTP response or to send the HTTP response trailers.

      Parameters:
      frame - the HEADERS frame to send
      callback - the callback that gets notified when the frame has been sent

    • push

      default CompletableFuture<Stream> push(PushPromiseFrame frame, Stream.Listener listener)

      Sends the given PUSH_PROMISE frame.

      Parameters:
      frame - the PUSH_PROMISE frame to send
      listener - the listener that gets notified of stream events
      Returns:
      the CompletableFuture that gets notified of the pushed stream creation

    • push

      void push(PushPromiseFrame frame, Promise<Stream> promise, Stream.Listener listener)

      Sends the given PUSH_PROMISE frame.

      Parameters:
      frame - the PUSH_PROMISE frame to send
      promise - the promise that gets notified of the pushed stream creation
      listener - the listener that gets notified of stream events

    • readData

      Stream.Data readData()

      Reads DATA frames from this stream, wrapping them in retainable Stream.Data objects.

      The returned Stream.Data object may be null, indicating that the end of the read side of the stream has not yet been reached, which may happen in these cases:

      • not all the bytes have been received so far, for example the remote peer did not send them yet, or they are in-flight
      • all the bytes have been received, but there is a trailer HEADERS frame to be received to indicate the end of the read side of the stream

      When the returned Stream.Data object is not null, the flow control window has been enlarged by the DATA frame 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.

      Stream.Data 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 Stream.Data object indicates that the end of the read side of the stream has been reached, further calls to this method will return a Stream.Data object with the same indication, although the instance may be different.

      Returns:
      a Stream.Data object containing the DATA frame, or null if no DATA frame is available
      See Also:

    • data

      default CompletableFuture<Stream> data(DataFrame frame)

      Sends the given DATA frame.

      Parameters:
      frame - the DATA frame to send
      Returns:
      the CompletableFuture that gets notified when the frame has been sent

    • data

      void data(DataFrame frame, Callback callback)

      Sends the given DATA frame.

      Parameters:
      frame - the DATA frame to send
      callback - the callback that gets notified when the frame has been sent

    • reset

      default CompletableFuture<Void> reset(ResetFrame frame)

      Sends the given RST_STREAM frame.

      Parameters:
      frame - the RST_STREAM frame to send
      Returns:
      the CompletableFuture that gets notified when the frame has been sent

    • reset

      void reset(ResetFrame frame, Callback callback)

      Sends the given RST_STREAM frame.

      Parameters:
      frame - the RST_STREAM frame to send
      callback - the callback that gets notified when the frame has been sent

    • getAttribute

      Object getAttribute(String key)
      Parameters:
      key - the attribute key
      Returns:
      an arbitrary object associated with the given key to this stream or null if no object can be found for the given key.
      See Also:

    • setAttribute

      void setAttribute(String key, Object value)
      Parameters:
      key - the attribute key
      value - an arbitrary object to associate with the given key to this stream
      See Also:

    • removeAttribute

      Object removeAttribute(String key)
      Parameters:
      key - the attribute key
      Returns:
      the arbitrary object associated with the given key to this stream
      See Also:

    • isLocal

      boolean isLocal()
      Returns:
      whether this stream is local or remote

    • isReset

      boolean isReset()
      Returns:
      whether this stream has been reset

    • isRemotelyClosed

      boolean isRemotelyClosed()
      Returns:
      whether the stream is closed remotely.
      See Also:

    • isClosed

      boolean isClosed()
      Returns:
      whether this stream is closed, both locally and remotely.

    • getIdleTimeout

      long getIdleTimeout()
      Returns:
      the stream idle timeout
      See Also:

    • setIdleTimeout

      void setIdleTimeout(long idleTimeout)
      Parameters:
      idleTimeout - the stream idle timeout
      See Also:

    • demand

      void demand()

      Demands more DATA frames 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: