Package org.eclipse.jetty.http3.api

Interface Stream

All Known Subinterfaces:
Stream.Client, Stream.Server
public interface Stream

A Stream represents a bidirectional exchange of data within a Session.

A Stream maps to an HTTP/3 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.Client.Listener and Stream.Server.Listener are the passive part, and their callbacks are invoked when events happen on the stream.

The client initiates a stream by sending a HEADERS frame containing the HTTP/3 request URI and request headers, and zero or more DATA frames containing request content.

Similarly, the server responds by sending a HEADERS frame containing the HTTP/3 response status code and response headers, and zero or more DATA frames containing response content.

Both client and server can end their side of the stream by sending a final frame with the last flag set to true, see HeadersFrame(MetaData, boolean) and DataFrame(ByteBuffer, boolean).

  • Method Details

    • getId

      long getId()
      Returns:
      the stream id

    • getSession

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

    • data

      CompletableFuture<Stream> data(DataFrame frame)

      Sends the given DATA frame containing some or all the bytes of the request content or of the response content.

      Parameters:
      frame - the DATA frame containing some or all the bytes of the request or of the response.
      Returns:
      the CompletableFuture that gets notified when the frame has been sent

    • readData

      Stream.Data readData()

      Reads request content bytes or response content bytes.

      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, applications must call, either immediately or later (possibly asynchronously) Stream.Data.complete() 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).

      Returns:
      a Stream.Data object containing the request bytes or the response bytes, or null if no bytes are available
      See Also:

    • demand

      void demand()

      Causes Stream.Client.Listener.onDataAvailable(Stream.Client) on the client, or Stream.Server.Listener.onDataAvailable(Stream.Server) on the server, to be invoked, possibly at a later time, when the stream has data to be read.

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

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

      When all bytes have been read (via readData()), further invocations of this method are a no-operation.

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

      See Also:

    • trailer

      CompletableFuture<Stream> trailer(HeadersFrame frame)

      Sends the given HEADERS frame containing the trailer headers.

      Parameters:
      frame - the HEADERS frame containing the trailer headers
      Returns:
      the CompletableFuture that gets notified when the frame has been sent

    • reset

      void reset(long error, Throwable failure)

      Abruptly terminates this stream with the given error.

      Parameters:
      error - the error code
      failure - the failure that caused the reset of the stream