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#HeadersFrame(MetaData, boolean) and DataFrame#DataFrame(ByteBuffer, boolean).

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	Stream.Client The client side version of `Stream`.
public abstract static class	Stream.Data A `Stream.Data` instance associates a `ByteBuffer` containing request bytes or response bytes.
public static interface	Stream.Server The server side version of `Stream`.

Method Summary

Modifier and Type	Method and Description
public CompletableFuture<Stream>	Returns: the `CompletableFuture` that gets notified when the frame has been sent data(DataFrame the DATA frame containing some or all the bytes of the request or of the response. frame) Sends the given DATA frame containing some or all the bytes of the request content or of the response content.
public void	demand() Demands more `DATA` frames for this stream.
public long	Returns: the stream id getId() Get the stream id.
public Session	Returns: the session this stream is associated to getSession() Get the session this stream is associated to.
public Stream.Data	Returns: a `Stream.Data` object containing the request bytes or the response bytes, or null if no bytes are available readData() Reads request content bytes or response content bytes.
public void	reset(long the error code error, Throwable the failure that caused the reset of the stream failure) Abruptly terminates this stream with the given error.
public CompletableFuture<Stream>	Returns: the `CompletableFuture` that gets notified when the frame has been sent trailer(HeadersFrame the HEADERS frame containing the trailer headers frame) Sends the given HEADERS frame containing the trailer headers.

Method Detail

data	back to summary
public 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:DataFrame the DATA frame containing some or all the bytes of the request or of the response. Returns:CompletableFuture<Stream> the `CompletableFuture` that gets notified when the frame has been sent

demand back to summary

demand	back to summary
public void demand() Demands more `DATA` frames for this stream. Calling this method 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, but also when the stream has reached EOF. 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. 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)`

public void demand()

Demands more DATA frames for this stream.

Calling this method 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, but also when the stream has reached EOF.

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.

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)

getId	back to summary
public long getId() Get the stream id. Returns:long the stream id

getId

back to summary

public long getId()

Get the stream id.

Returns:long: the stream id

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

getSession

back to summary

public Session getSession()

Get the session this stream is associated to.

Returns:Session: the session this stream is associated to

readData back to summary

readData	back to summary
public 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#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). Returns:Stream.Data 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)`

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

Returns:Stream.Data: 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)

reset	back to summary
public void reset(long error, Throwable failure) Abruptly terminates this stream with the given error. Parameters error:long the error code failure:Throwable the failure that caused the reset of the stream

reset

back to summary

public void reset(long error, Throwable failure)

Abruptly terminates this stream with the given error.

Parameters

error:long: the error code
failure:Throwable: the failure that caused the reset of the stream

trailer back to summary

trailer	back to summary
public CompletableFuture<Stream> trailer(HeadersFrame frame) Sends the given HEADERS frame containing the trailer headers. Parameters frame:HeadersFrame the HEADERS frame containing the trailer headers Returns:CompletableFuture<Stream> the `CompletableFuture` that gets notified when the frame has been sent

public CompletableFuture<Stream> trailer(HeadersFrame frame)

Sends the given HEADERS frame containing the trailer headers.

Parameters

frame:HeadersFrame: the HEADERS frame containing the trailer headers

Returns:CompletableFuture<Stream>

the CompletableFuture that gets notified when the frame has been sent

org.eclipse.jetty.http3.api back to summary

public Interface Stream.Client

extends Stream

The client side version of Stream.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	Stream.Client.Listener A `Stream.Client.Listener` is the passive counterpart of a `Stream.Client` and receives client-side events happening on an HTTP/3 stream.

Method Summary

Inherited from org.eclipse.jetty.http3.api.Stream:: data demand getId getSession readData reset trailer

org.eclipse.jetty.http3.api back to summary

public Interface Stream.Client.Listener

A Stream.Client.Listener is the passive counterpart of a Stream.Client and receives client-side events happening on an HTTP/3 stream.

See Also: Stream.Client

Method Summary

Modifier and Type	Method and Description
public default void	onDataAvailable(Stream.Client the stream stream) Callback method invoked if the application has expressed `demand` for content, and if there may be content available.
public default void	onFailure(Stream.Client the stream stream, long the failure error error, Throwable the cause of the failure failure) Callback method invoked when a stream failure occurred.
public default void	onIdleTimeout(Stream.Client the stream stream, Throwable the timeout failure failure, Promise<Boolean> the promise to complete with true to reset the stream, false to ignore the idle timeout promise) Callback method invoked when the stream idle timeout elapses.
public default void	onNewStream(Stream.Client the newly created stream stream) Callback method invoked when a stream is created locally by `Session.Client#newRequest(HeadersFrame, Listener)`.
public default void	onResponse(Stream.Client the stream stream, HeadersFrame the HEADERS frame containing the response headers frame) Callback method invoked when a response is received.
public default void	onTrailer(Stream.Client the stream stream, HeadersFrame the HEADERS frame containing the trailer headers frame) Callback method invoked when a trailer is received.

Method Detail

onDataAvailable back to summary

onDataAvailable	back to summary
public default void onDataAvailable(Stream.Client stream) Callback method invoked if the application has expressed `demand` for content, and if there may be content available. A server application that wishes to handle request content should typically call `Stream#demand()` from `Session.Server.Listener#onRequest(Server, HeadersFrame)`. A client application that wishes to handle response content should typically call `Stream#demand()` from `Stream.Client.Listener#onResponse(Client, HeadersFrame)`. Just prior calling this method, the outstanding demand is cancelled; applications that implement this method should read content calling `Stream#readData()`, and call `Stream#demand()` to signal to the implementation to call again this method when there may be more content 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.Client.Listener { @Override public void onDataAvailable(Stream.Client stream) { // Read a chunk of the content. Stream.Data data = stream.readData(); if (data == null) { // No data available now, demand to be called back. stream.demand(); } else { // Process the content. process(data.getByteBuffer()); // Notify that the content has been consumed. data.release(); if (!data.isLast()) { // Demand to be called back. stream.demand(); } } } } Parameters stream:Stream.Client the stream

public default void onDataAvailable(Stream.Client stream)

Callback method invoked if the application has expressed demand for content, and if there may be content available.

A server application that wishes to handle request content should typically call Stream#demand() from Session.Server.Listener#onRequest(Server, HeadersFrame).

A client application that wishes to handle response content should typically call Stream#demand() from Stream.Client.Listener#onResponse(Client, HeadersFrame).

Just prior calling this method, the outstanding demand is cancelled; applications that implement this method should read content calling Stream#readData(), and call Stream#demand() to signal to the implementation to call again this method when there may be more content 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.Client.Listener
{
    @Override
    public void onDataAvailable(Stream.Client stream)
    {
        // Read a chunk of the content.
        Stream.Data data = stream.readData();
        if (data == null)
        {
            // No data available now, demand to be called back.
            stream.demand();
        }
        else
        {
            // Process the content.
            process(data.getByteBuffer());
            // Notify that the content has been consumed.
            data.release();
            if (!data.isLast())
            {
                // Demand to be called back.
                stream.demand();
            }
        }
    }
}

Parameters

stream:Stream.Client: the stream

onFailure	back to summary
public default void onFailure(Stream.Client stream, long error, Throwable failure) Callback method invoked when a stream failure occurred. Typical stream failures, among others, are failures to decode a HEADERS frame, or failures to read bytes because the stream has been reset. Parameters stream:Stream.Client the stream error:long the failure error failure:Throwable the cause of the failure

onFailure

back to summary

public default void onFailure(Stream.Client stream, long error, Throwable failure)

Callback method invoked when a stream failure occurred.

Typical stream failures, among others, are failures to decode a HEADERS frame, or failures to read bytes because the stream has been reset.

Parameters

stream:Stream.Client: the stream
error:long: the failure error
failure:Throwable: the cause of the failure

onIdleTimeout	back to summary
public default void onIdleTimeout(Stream.Client stream, Throwable failure, Promise<Boolean> promise) Callback method invoked when the stream idle timeout elapses. Parameters stream:Stream.Client the stream failure:Throwable the timeout failure promise:Promise<Boolean> the promise to complete with true to reset the stream, false to ignore the idle timeout

onIdleTimeout

back to summary

public default void onIdleTimeout(Stream.Client stream, Throwable failure, Promise<Boolean> promise)

Callback method invoked when the stream idle timeout elapses.

Parameters

stream:Stream.Client: the stream
failure:Throwable: the timeout failure
promise:Promise<Boolean>: the promise to complete with true to reset the stream, false to ignore the idle timeout

onNewStream back to summary

onNewStream	back to summary
public default void onNewStream(Stream.Client stream) Callback method invoked when a stream is created locally by `Session.Client#newRequest(HeadersFrame, Listener)`. Parameters stream:Stream.Client the newly created stream

public default void onNewStream(Stream.Client stream)

Callback method invoked when a stream is created locally by Session.Client#newRequest(HeadersFrame, Listener).

Parameters

stream:Stream.Client: the newly created stream

onResponse back to summary

onResponse	back to summary
public default void onResponse(Stream.Client stream, HeadersFrame frame) Callback method invoked when a response is received. To read response content, applications should call `Stream#demand()` and override `Stream.Client.Listener#onDataAvailable(Client)`. Parameters stream:Stream.Client the stream frame:HeadersFrame the HEADERS frame containing the response headers See Also `Stream.Client.Listener#onDataAvailable(Client)`

public default void onResponse(Stream.Client stream, HeadersFrame frame)

Callback method invoked when a response is received.

To read response content, applications should call Stream#demand() and override Stream.Client.Listener#onDataAvailable(Client).

Parameters

stream:Stream.Client: the stream
frame:HeadersFrame: the HEADERS frame containing the response headers

onTrailer	back to summary
public default void onTrailer(Stream.Client stream, HeadersFrame frame) Callback method invoked when a trailer is received. Parameters stream:Stream.Client the stream frame:HeadersFrame the HEADERS frame containing the trailer headers

onTrailer

back to summary

public default void onTrailer(Stream.Client stream, HeadersFrame frame)

Callback method invoked when a trailer is received.

Parameters

stream:Stream.Client: the stream
frame:HeadersFrame: the HEADERS frame containing the trailer headers

org.eclipse.jetty.http3.api back to summary

public abstract Class Stream.Data

Class Inheritance

extends Object
implements Retainable

java.lang.Object
org.eclipse.jetty.http3.api.Stream.Data

All Implemented Interfaces

org.eclipse.jetty.io.Retainable

Known Direct Subclasses

org.eclipse.jetty.http3.api.Stream.Data.EOFData, org.eclipse.jetty.http3.HTTP3StreamConnection.StreamData

A Stream.Data instance associates a ByteBuffer containing request bytes or response bytes.

See Also: Stream#readData()

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	Stream.Data.EOFData

Field Summary

Modifier and Type	Field and Description
public static final Stream.Data	EOF
private final DataFrame	frame

Constructor Summary

Access	Constructor and Description
public	Data(DataFrame frame)

Method Summary

Modifier and Type	Method and Description
public ByteBuffer	getByteBuffer() Returns: the `ByteBuffer` containing the data bytes
public boolean	isLast() Returns: whether this is the instance that ends the stream of bytes received from the remote peer
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

EOF	back to summary
public static final Stream.Data EOF

frame	back to summary
private final DataFrame frame

Constructor Detail

Data	back to summary
public Data(DataFrame frame)

Method Detail

getByteBuffer	back to summary
public ByteBuffer getByteBuffer() Returns:ByteBuffer the `ByteBuffer` containing the data bytes

isLast	back to summary
public boolean isLast() Returns:boolean whether this is the instance that ends the stream of bytes received from the remote peer

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Satisfying this method's contract implies a non-`null` result must be returned. Annotations @Override

org.eclipse.jetty.http3.api back to summary

private Class Stream.Data.EOFData

Class Inheritance

extends Data

java.lang.Object
org.eclipse.jetty.http3.api.Stream.Data
org.eclipse.jetty.http3.api.Stream.Data.EOFData

Field Summary

Inherited from org.eclipse.jetty.http3.api.Stream.Data:: EOF

Constructor Summary

Access	Constructor and Description
private	EOFData()

Method Summary

Inherited from org.eclipse.jetty.http3.api.Stream.Data:: getByteBuffer isLast toString

Constructor Detail

EOFData	back to summary
private EOFData()

org.eclipse.jetty.http3.api back to summary

public Interface Stream.Server

extends Stream

The server side version of Stream.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	Stream.Server.Listener A `Stream.Server.Listener` is the passive counterpart of a `Stream.Server` and receives server-side events happening on an HTTP/3 stream.

Method Summary

Modifier and Type	Method and Description
public CompletableFuture<Stream>	Returns: the `CompletableFuture` that gets notified when the frame has been sent respond(HeadersFrame the HEADERS frame containing the response headers frame) Responds to a request performed via `Session.Client#newRequest(HeadersFrame, Client.Listener)`, sending the given HEADERS frame containing the response status code and response headers.

Inherited from org.eclipse.jetty.http3.api.Stream:: data demand getId getSession readData reset trailer

Method Detail

respond back to summary

respond	back to summary
public CompletableFuture<Stream> respond(HeadersFrame frame) Responds to a request performed via `Session.Client#newRequest(HeadersFrame, Client.Listener)`, sending the given HEADERS frame containing the response status code and response headers. Parameters frame:HeadersFrame the HEADERS frame containing the response headers Returns:CompletableFuture<Stream> the `CompletableFuture` that gets notified when the frame has been sent

public CompletableFuture<Stream> respond(HeadersFrame frame)

Responds to a request performed via Session.Client#newRequest(HeadersFrame, Client.Listener), sending the given HEADERS frame containing the response status code and response headers.

Parameters

frame:HeadersFrame: the HEADERS frame containing the response headers

Returns:CompletableFuture<Stream>

the CompletableFuture that gets notified when the frame has been sent

org.eclipse.jetty.http3.api back to summary

public Interface Stream.Server.Listener

A Stream.Server.Listener is the passive counterpart of a Stream.Server and receives server-side events happening on an HTTP/3 stream.

See Also: Stream.Server

Method Summary

Modifier and Type	Method and Description
public default void	onDataAvailable(Stream.Server the stream stream) Callback method invoked if the application has expressed `demand` for content, and if there may be content available.
public default void	onFailure(Stream.Server the stream stream, long the failure error error, Throwable the cause of the failure failure) Callback method invoked when a stream failure occurred.
public default void	onIdleTimeout(Stream.Server the stream stream, TimeoutException the timeout failure failure, Promise<Boolean> the promise to complete with true to reset the stream, false to ignore the idle timeout promise) Callback method invoked when the stream idle timeout elapses.
public default void	onTrailer(Stream.Server the stream stream, HeadersFrame the HEADERS frame containing the trailer headers frame) Callback method invoked when a trailer is received.

Method Detail

onDataAvailable back to summary

onDataAvailable	back to summary
public default void onDataAvailable(Stream.Server stream) Callback method invoked if the application has expressed `demand` for content, and if there may be content available. A server application that wishes to handle request content should typically call `Stream#demand()` from `Session.Server.Listener#onRequest(Server, HeadersFrame)`. A client application that wishes to handle response content should typically call `Stream#demand()` from `Stream.Client.Listener#onResponse(Client, HeadersFrame)`. Just prior calling this method, the outstanding demand is cancelled; applications that implement this method should read content calling `Stream#readData()`, and call `Stream#demand()` to signal to the implementation to call again this method when there may be more content 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.Server.Listener { @Override public void onDataAvailable(Stream.Server stream) { // Read a chunk of the content. Stream.Data data = stream.readData(); if (data == null) { // No data available now, demand to be called back. stream.demand(); } else { // Process the content. process(data.getByteBuffer()); // Notify that the content has been consumed. data.release(); if (!data.isLast()) { // Demand to be called back. stream.demand(); } } } } Parameters stream:Stream.Server the stream

public default void onDataAvailable(Stream.Server stream)

Callback method invoked if the application has expressed demand for content, and if there may be content available.

A server application that wishes to handle request content should typically call Stream#demand() from Session.Server.Listener#onRequest(Server, HeadersFrame).

A client application that wishes to handle response content should typically call Stream#demand() from Stream.Client.Listener#onResponse(Client, HeadersFrame).

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.Server.Listener
{
    @Override
    public void onDataAvailable(Stream.Server stream)
    {
        // Read a chunk of the content.
        Stream.Data data = stream.readData();
        if (data == null)
        {
            // No data available now, demand to be called back.
            stream.demand();
        }
        else
        {
            // Process the content.
            process(data.getByteBuffer());
            // Notify that the content has been consumed.
            data.release();
            if (!data.isLast())
            {
                // Demand to be called back.
                stream.demand();
            }
        }
    }
}

Parameters

stream:Stream.Server: the stream

onFailure	back to summary
public default void onFailure(Stream.Server stream, long error, Throwable failure) Callback method invoked when a stream failure occurred. Typical stream failures, among others, are failures to decode a HEADERS frame, or failures to read bytes because the stream has been reset. Parameters stream:Stream.Server the stream error:long the failure error failure:Throwable the cause of the failure

onFailure

back to summary

public default void onFailure(Stream.Server stream, long error, Throwable failure)

Callback method invoked when a stream failure occurred.

Typical stream failures, among others, are failures to decode a HEADERS frame, or failures to read bytes because the stream has been reset.

Parameters

stream:Stream.Server: the stream
error:long: the failure error
failure:Throwable: the cause of the failure

onIdleTimeout	back to summary
public default void onIdleTimeout(Stream.Server stream, TimeoutException failure, Promise<Boolean> promise) Callback method invoked when the stream idle timeout elapses. Parameters stream:Stream.Server the stream failure:TimeoutException the timeout failure promise:Promise<Boolean> the promise to complete with true to reset the stream, false to ignore the idle timeout

onIdleTimeout

back to summary

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

Callback method invoked when the stream idle timeout elapses.

Parameters

stream:Stream.Server: the stream
failure:TimeoutException: the timeout failure
promise:Promise<Boolean>: the promise to complete with true to reset the stream, false to ignore the idle timeout

onTrailer	back to summary
public default void onTrailer(Stream.Server stream, HeadersFrame frame) Callback method invoked when a trailer is received. Parameters stream:Stream.Server the stream frame:HeadersFrame the HEADERS frame containing the trailer headers

onTrailer

back to summary

public default void onTrailer(Stream.Server stream, HeadersFrame frame)

Callback method invoked when a trailer is received.

Parameters

stream:Stream.Server: the stream
frame:HeadersFrame: the HEADERS frame containing the trailer headers