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).

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Stream.Client	The client side version of Stream.
static class	Stream.Data	A Stream.Data instance associates a ByteBuffer containing request bytes or response bytes with a completion event that applications must trigger when the bytes have been processed.
static interface	Stream.Server	The server side version of Stream.

Method Summary

Modifier and Type	Method	Description
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.
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.
long	getId()
Session	getSession()
Stream.Data	readData()	Reads request content bytes or response content bytes.
void	reset(long error, Throwable failure)	Abruptly terminates this stream with the given error.
CompletableFuture<Stream>	trailer(HeadersFrame frame)	Sends the given HEADERS frame containing the trailer headers.

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:

• Stream.Client.Listener.onDataAvailable(Stream.Client)
• Stream.Server.Listener.onDataAvailable(Stream.Server)

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:

• readData()
• Stream.Client.Listener.onDataAvailable(Stream.Client)
• Stream.Server.Listener.onDataAvailable(Stream.Server)

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