Top Description Inners Methods
org.eclipse.jetty.http2.api

public Interface Stream

Known Direct Implementers
org.eclipse.jetty.http2.HTTP2Stream
Imports
java.util.concurrent.CompletableFuture, .TimeoutException, org.eclipse.jetty.http2.frames.DataFrame, .HeadersFrame, .PushPromiseFrame, .ResetFrame, org.eclipse.jetty.io.Retainable, org.eclipse.jetty.util.BufferUtil, .Callback, .Promise

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
Stream.Listener

Nested and Inner Type Summary

Modifier and TypeClass and Description
public abstract static class
Stream.Data

A Retainable wrapper of a DataFrame.

public static interface
Stream.Listener

A Stream.Listener is the passive counterpart of a Stream and receives events happening on an HTTP/2 stream.

Method Summary

Modifier and TypeMethod and Description
public default CompletableFuture<Stream>

Returns:

the CompletableFuture that gets notified when the frame has been sent
data(DataFrame
the DATA frame to send
frame)

Sends the given DATA frame.

public void
data(DataFrame
the DATA frame to send
frame, Callback
the callback that gets notified when the frame has been sent
callback)

Sends the given DATA frame.

public void
demand()

Demands more DATA frames for this stream.

public Object
getAttribute(String
the attribute key
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.

public int

Returns:

the stream unique id
getId()

Get the stream unique id.

public long
getIdleTimeout()

Returns: the stream idle timeout

public Stream.Listener

Returns:

the org.eclipse.jetty.http2.api.Stream.Listener associated with this stream
getListener()

Get the org.eclipse.jetty.http2.api.Stream.Listener associated with this stream.

public Session

Returns:

the session this stream is associated to
getSession()

Get the session this stream is associated to.

public default CompletableFuture<Stream>

Returns:

the CompletableFuture that gets notified when the frame has been sent
headers(HeadersFrame
the HEADERS frame to send
frame)

Sends the given HEADERS frame representing an HTTP response.

public void
headers(HeadersFrame
the HEADERS frame to send
frame, Callback
the callback that gets notified when the frame has been sent
callback)

Sends the given HEADERS frame.

public boolean
isClosed()

Returns: whether this stream is closed, both locally and remotely.

public boolean
isLocal()

Returns: whether this stream is local or remote

public boolean
isRemotelyClosed()

Returns: whether the stream is closed remotely.

public boolean
isReset()

Returns: whether this stream has been reset

public default CompletableFuture<Stream>

Returns:

the CompletableFuture that gets notified of the pushed stream creation
push(PushPromiseFrame
the PUSH_PROMISE frame to send
frame, Stream.Listener
the listener that gets notified of stream events
listener)

Sends the given PUSH_PROMISE frame.

public void
push(PushPromiseFrame
the PUSH_PROMISE frame to send
frame, Promise<Stream>
the promise that gets notified of the pushed stream creation
promise, Stream.Listener
the listener that gets notified of stream events
listener)

Sends the given PUSH_PROMISE frame.

public Stream.Data

Returns:

a Stream.Data object containing the DATA frame, or null if no DATA frame is available
readData()

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

public Object
removeAttribute(String
the attribute key
key)

Returns: the arbitrary object associated with the given key to this stream

public default CompletableFuture<Void>

Returns:

the CompletableFuture that gets notified when the frame has been sent
reset(ResetFrame
the RST_STREAM frame to send
frame)

Sends the given RST_STREAM frame.

public void
reset(ResetFrame
the RST_STREAM frame to send
frame, Callback
the callback that gets notified when the frame has been sent
callback)

Sends the given RST_STREAM frame.

public void
setAttribute(String
the attribute key
key, Object
an arbitrary object to associate with the given key to this stream
value)

public void
setIdleTimeout(long
the stream idle timeout
idleTimeout)

Method Detail

databack to summary
public default CompletableFuture<Stream> data(DataFrame frame)

Sends the given DATA frame.

Parameters
frame:DataFrame

the DATA frame to send

Returns:CompletableFuture<Stream>

the CompletableFuture that gets notified when the frame has been sent

databack to summary
public void data(DataFrame frame, Callback callback)

Sends the given DATA frame.

Parameters
frame:DataFrame

the DATA frame to send

callback:Callback

the callback that gets notified when the frame has been sent

demandback to summary
public void demand()

Demands more DATA frames for this stream.

Calling this method causes 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 Listener#onDataAvailable(Stream) is a no-operation.

The thread invoking this method may invoke directly Listener#onDataAvailable(Stream), unless another thread that must invoke 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
readData(), Listener#onDataAvailable(Stream)
getAttributeback to summary
public Object getAttribute(String key)
Parameters
key:String

the attribute key

Returns:Object

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(String, Object)
getIdback to summary
public int getId()

Get the stream unique id.

Returns:int

the stream unique id

getIdleTimeoutback to summary
public long getIdleTimeout()
Returns:long

the stream idle timeout

See Also
setIdleTimeout(long)
getListenerback to summary
public Stream.Listener getListener()

Get the org.eclipse.jetty.http2.api.Stream.Listener associated with this stream.

Returns:Stream.Listener

the org.eclipse.jetty.http2.api.Stream.Listener associated with this stream

getSessionback to summary
public Session getSession()

Get the session this stream is associated to.

Returns:Session

the session this stream is associated to

headersback to summary
public default CompletableFuture<Stream> headers(HeadersFrame frame)

Sends the given HEADERS frame representing an HTTP response.

Parameters
frame:HeadersFrame

the HEADERS frame to send

Returns:CompletableFuture<Stream>

the CompletableFuture that gets notified when the frame has been sent

headersback to summary
public 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:HeadersFrame

the HEADERS frame to send

callback:Callback

the callback that gets notified when the frame has been sent

isClosedback to summary
public boolean isClosed()
Returns:boolean

whether this stream is closed, both locally and remotely.

isLocalback to summary
public boolean isLocal()
Returns:boolean

whether this stream is local or remote

isRemotelyClosedback to summary
public boolean isRemotelyClosed()
Returns:boolean

whether the stream is closed remotely.

See Also
isClosed()
isResetback to summary
public boolean isReset()
Returns:boolean

whether this stream has been reset

pushback to summary
public default CompletableFuture<Stream> push(PushPromiseFrame frame, Stream.Listener listener)

Sends the given PUSH_PROMISE frame.

Parameters
frame:PushPromiseFrame

the PUSH_PROMISE frame to send

listener:Stream.Listener

the listener that gets notified of stream events

Returns:CompletableFuture<Stream>

the CompletableFuture that gets notified of the pushed stream creation

pushback to summary
public void push(PushPromiseFrame frame, Promise<Stream> promise, Stream.Listener listener)

Sends the given PUSH_PROMISE frame.

Parameters
frame:PushPromiseFrame

the PUSH_PROMISE frame to send

promise:Promise<Stream>

the promise that gets notified of the pushed stream creation

listener:Stream.Listener

the listener that gets notified of stream events

readDataback to summary
public Stream.Data readData()

Reads DATA frames from this stream, wrapping them in retainable 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) 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).

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

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

See Also
demand(), Listener#onDataAvailable(Stream)
removeAttributeback to summary
public Object removeAttribute(String key)
Parameters
key:String

the attribute key

Returns:Object

the arbitrary object associated with the given key to this stream

See Also
setAttribute(String, Object)
resetback to summary
public default CompletableFuture<Void> reset(ResetFrame frame)

Sends the given RST_STREAM frame.

Parameters
frame:ResetFrame

the RST_STREAM frame to send

Returns:CompletableFuture<Void>

the CompletableFuture that gets notified when the frame has been sent

resetback to summary
public void reset(ResetFrame frame, Callback callback)

Sends the given RST_STREAM frame.

Parameters
frame:ResetFrame

the RST_STREAM frame to send

callback:Callback

the callback that gets notified when the frame has been sent

setAttributeback to summary
public void setAttribute(String key, Object value)
Parameters
key:String

the attribute key

value:Object

an arbitrary object to associate with the given key to this stream

See Also
getAttribute(String), removeAttribute(String)
setIdleTimeoutback to summary
public void setIdleTimeout(long idleTimeout)
Parameters
idleTimeout:long

the stream idle timeout

See Also
getIdleTimeout(), Stream.Listener#onIdleTimeout(Stream, TimeoutException, Promise)
org.eclipse.jetty.http2.api back to summary

public abstract Class Stream.Data

extends Object
implements Retainable
Class Inheritance
All Implemented Interfaces
org.eclipse.jetty.io.Retainable
Known Direct Subclasses
org.eclipse.jetty.http2.api.Stream.Data.EOF, org.eclipse.jetty.http2.HTTP2Connection.StreamData

A Retainable wrapper of a DataFrame.

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
Stream.Data.EOF

Field Summary

Modifier and TypeField and Description
private final DataFrame
frame

Constructor Summary

AccessConstructor and Description
public
Data(DataFrame frame)

Method Summary

Modifier and TypeMethod and Description
public static Stream.Data
eof(int streamId)

public DataFrame
frame()

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

frameback to summary
private final DataFrame frame

Constructor Detail

Databack to summary
public Data(DataFrame frame)

Method Detail

eofback to summary
public static Stream.Data eof(int streamId)
frameback to summary
public DataFrame frame()
toStringback 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.

Returns:String

a string representation of the object

Annotations
@Override
org.eclipse.jetty.http2.api back to summary

private Class Stream.Data.EOF

extends Data
Class Inheritance

Constructor Summary

AccessConstructor and Description
public
EOF(int streamId)

Constructor Detail

EOFback to summary
public EOF(int streamId)
org.eclipse.jetty.http2.api back to summary

public Interface Stream.Listener

A Stream.Listener is the passive counterpart of a Stream and receives events happening on an HTTP/2 stream.

HTTP/2 data is flow controlled - this means that only a finite number of data events are delivered, until the flow control window is exhausted.

Applications control the delivery of data events by requesting them via Stream#demand(); the first event is always delivered, while subsequent events must be explicitly demanded.

Applications control the HTTP/2 flow control by completing the callback associated with data events - this allows the implementation to recycle the data buffer and eventually to enlarge the flow control window so that the sender can send more data.

See Also
Stream

Field Summary

Modifier and TypeField and Description
public static final Stream.Listener
AUTO_DISCARD

A convenient constant for a Listener implementation that demands and discards DATA frames, typically to be returned from Session.Listener#onNewStream(Stream, HeadersFrame) and Listener#onPush(Stream, PushPromiseFrame).

Method Summary

Modifier and TypeMethod and Description
public default void
onClosed(Stream
the stream
stream)

Callback method invoked after the stream has been closed.

public default void
onDataAvailable(Stream
the stream
stream)

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

public default void
onFailure(Stream
the stream
stream, int
the error code
error, String
the error reason, or null
reason, Throwable
the failure
failure, Callback
the callback to complete when the failure has been handled
callback)

Callback method invoked when the stream failed.

public default void
onHeaders(Stream
the stream
stream, HeadersFrame
the HEADERS frame received
frame)

Callback method invoked when a HEADERS frame representing the HTTP response has been received.

public default void
onIdleTimeout(Stream
the stream
stream, TimeoutException
the timeout failure
x, Promise<Boolean>
the promise to complete
promise)

Callback method invoked when the stream exceeds its idle timeout.

public default void
onNewStream(Stream
the newly created stream
stream)

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

public default Stream.Listener

Returns:

a Stream.Listener that will be notified of pushed stream events
onPush(Stream
the pushed stream
stream, PushPromiseFrame
the PUSH_PROMISE frame received
frame)

Callback method invoked when a PUSH_PROMISE frame has been received.

public default void
onReset(Stream
the stream
stream, ResetFrame
the RST_STREAM frame received
frame, Callback
the callback to complete when the reset has been handled
callback)

Callback method invoked when a RST_STREAM frame has been received for this stream.

Field Detail

AUTO_DISCARDback to summary
public static final Stream.Listener AUTO_DISCARD

A convenient constant for a Listener implementation that demands and discards DATA frames, typically to be returned from Session.Listener#onNewStream(Stream, HeadersFrame) and Listener#onPush(Stream, PushPromiseFrame).

Method Detail

onClosedback to summary
public default void onClosed(Stream stream)

Callback method invoked after the stream has been closed.

Parameters
stream:Stream

the stream

onDataAvailableback to summary
public default void onDataAvailable(Stream stream)

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

Applications that wish to handle DATA frames should call Stream#demand() for this method to be invoked when the data is available.

Server applications should typically demand from onNewStream(Stream) (upon receiving an HTTP request), while client applications should typically demand from onHeaders(Stream, HeadersFrame) (upon receiving an HTTP response).

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.Listener
{
    @Override
    public void onDataAvailable(Stream 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.frame().getByteBuffer());
            // Notify that the content has been consumed.
            data.release();
            if (!data.frame().isEndStream())
            {
                // Demand to be called back.
                stream.demand();
            }
        }
    }
}
Parameters
stream:Stream

the stream

See Also
Stream#demand()
onFailureback to summary
public default void onFailure(Stream stream, int error, String reason, Throwable failure, Callback callback)

Callback method invoked when the stream failed.

Parameters
stream:Stream

the stream

error:int

the error code

reason:String

the error reason, or null

failure:Throwable

the failure

callback:Callback

the callback to complete when the failure has been handled

onHeadersback to summary
public default void onHeaders(Stream stream, HeadersFrame frame)

Callback method invoked when a HEADERS frame representing the HTTP response has been received.

Parameters
stream:Stream

the stream

frame:HeadersFrame

the HEADERS frame received

onIdleTimeoutback to summary
public default void onIdleTimeout(Stream stream, TimeoutException x, Promise<Boolean> promise)

Callback method invoked when the stream exceeds its idle timeout.

Parameters
stream:Stream

the stream

x:TimeoutException

the timeout failure

promise:Promise<Boolean>

the promise to complete

See Also
getIdleTimeout()
onNewStreamback to summary
public default void onNewStream(Stream stream)

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

Parameters
stream:Stream

the newly created stream

onPushback to summary
public default Stream.Listener onPush(Stream stream, PushPromiseFrame frame)

Callback method invoked when a PUSH_PROMISE frame has been received.

Applications that override this method are typically interested in processing the pushed stream DATA frames, and must demand for pushed DATA frames via Stream#demand() and then return either a Listener implementation that overrides onDataAvailable(Stream) where applications can read from the Stream via Stream#readData(), or AUTO_DISCARD that automatically reads and discards DATA frames. Returning null is possible but discouraged, and has the same effect of demanding and discarding the pushed DATA frames.

Parameters
stream:Stream

the pushed stream

frame:PushPromiseFrame

the PUSH_PROMISE frame received

Returns:Stream.Listener

a Stream.Listener that will be notified of pushed stream events

onResetback to summary
public default void onReset(Stream stream, ResetFrame frame, Callback callback)

Callback method invoked when a RST_STREAM frame has been received for this stream.

Parameters
stream:Stream

the stream

frame:ResetFrame

the RST_STREAM frame received

callback:Callback

the callback to complete when the reset has been handled