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

public Interface Session

Known Direct Implementers
org.eclipse.jetty.http2.HTTP2Session
Imports
java.net.InetSocketAddress, .SocketAddress, java.util.Collection, .Map, java.util.concurrent.CompletableFuture, org.eclipse.jetty.http2.frames.GoAwayFrame, .HeadersFrame, .PingFrame, .PriorityFrame, .ResetFrame, .SettingsFrame, org.eclipse.jetty.util.Callback, .Promise

A Session represents the client-side endpoint of an HTTP/2 connection to a single origin server.

Once a Session has been obtained, it can be used to open HTTP/2 streams:

Session session = ...;
HeadersFrame frame = ...;
Promise<Stream> promise = ...
session.newStream(frame, promise, new Stream.Listener()
{
    public void onHeaders(Stream stream, HeadersFrame frame)
    {
        // Reply received
    }
});

A Session is the active part of the endpoint, and by calling its API applications can generate events on the connection; conversely Session.Listener is the passive part of the endpoint, and has callbacks that are invoked when events happen on the connection.

See Also
Session.Listener

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
Session.Listener

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

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true if the frame is being sent, false if the session was already closed
close(int
the error code
error, String
an optional payload (may be null)
payload, Callback
the callback that gets notified when the frame has been sent
callback)

Closes the session by sending a GOAWAY frame with the given error code and payload.

public InetSocketAddress
getLocalAddress()
Deprecated use getLocalSocketAddress() instead

Returns: the local network address this session is bound to, or null if this session is not bound to a network address

public default SocketAddress
getLocalSocketAddress()

Returns: the local network address this session is bound to, or null if this session is not bound to a network address

public InetSocketAddress
getRemoteAddress()
Deprecated use getRemoteSocketAddress() instead

Returns: the remote network address this session is connected to, or null if this session is not connected to a network address

public default SocketAddress
getRemoteSocketAddress()

Returns: the remote network address this session is connected to, or null if this session is not connected to a network address

public Stream

Returns:

the stream with the given id, or null if no such stream exist
getStream(int
the stream id of the stream looked for
streamId)

Retrieves the stream with the given streamId.

public Collection<Stream>
getStreams()

Returns: a snapshot of all the streams currently belonging to this session

public boolean
isClosed()

Returns: whether the session is not open

public boolean
isPushEnabled()

Returns: whether the push functionality is enabled

public default CompletableFuture<Stream>

Returns:

a CompletableFuture that is notified of the stream creation
newStream(HeadersFrame
the HEADERS frame containing the HTTP headers
frame, Stream.Listener
the listener that gets notified of stream events
listener)

Sends the given HEADERS frame to create a new Stream.

public void
newStream(HeadersFrame
the HEADERS frame containing the HTTP headers
frame, Promise<Stream>
the promise that gets notified of the stream creation
promise, Stream.Listener
the listener that gets notified of stream events
listener)

Sends the given HEADERS frame to create a new Stream.

public void
ping(PingFrame
the PING frame to send
frame, Callback
the callback that gets notified when the frame has been sent
callback)

Sends the given PING frame.

public int

Returns:

the new stream id generated by the PRIORITY frame, or the stream id that it is already referencing
priority(PriorityFrame
the PRIORITY frame to send
frame, Callback
the callback that gets notified when the frame has been sent
callback)

Sends the given PRIORITY frame.

public default CompletableFuture<Void>

Returns:

a CompletableFuture that is notified when the frame has been sent
settings(SettingsFrame
the SETTINGS frame to send
frame)

Sends the given SETTINGS frame to configure the session.

public void
settings(SettingsFrame
the SETTINGS frame to send
frame, Callback
the callback that gets notified when the frame has been sent
callback)

Sends the given SETTINGS frame to configure the session.

public CompletableFuture<Void>

Returns:

a CompletableFuture that is completed when all the streams are completed
shutdown()

Gracefully closes the session, returning a CompletableFuture that is completed when all the streams currently being processed are completed.

Method Detail

closeback to summary
public boolean close(int error, String payload, Callback callback)

Closes the session by sending a GOAWAY frame with the given error code and payload.

Parameters
error:int

the error code

payload:String

an optional payload (may be null)

callback:Callback

the callback that gets notified when the frame has been sent

Returns:boolean

true if the frame is being sent, false if the session was already closed

getLocalAddressback to summary
public InetSocketAddress getLocalAddress()

Deprecated

use getLocalSocketAddress() instead

Returns:InetSocketAddress

the local network address this session is bound to, or null if this session is not bound to a network address

Annotations
@Deprecated
getLocalSocketAddressback to summary
public default SocketAddress getLocalSocketAddress()
Returns:SocketAddress

the local network address this session is bound to, or null if this session is not bound to a network address

getRemoteAddressback to summary
public InetSocketAddress getRemoteAddress()

Deprecated

use getRemoteSocketAddress() instead

Returns:InetSocketAddress

the remote network address this session is connected to, or null if this session is not connected to a network address

Annotations
@Deprecated
getRemoteSocketAddressback to summary
public default SocketAddress getRemoteSocketAddress()
Returns:SocketAddress

the remote network address this session is connected to, or null if this session is not connected to a network address

getStreamback to summary
public Stream getStream(int streamId)

Retrieves the stream with the given streamId.

Parameters
streamId:int

the stream id of the stream looked for

Returns:Stream

the stream with the given id, or null if no such stream exist

getStreamsback to summary
public Collection<Stream> getStreams()
Returns:Collection<Stream>

a snapshot of all the streams currently belonging to this session

isClosedback to summary
public boolean isClosed()
Returns:boolean

whether the session is not open

isPushEnabledback to summary
public boolean isPushEnabled()
Returns:boolean

whether the push functionality is enabled

newStreamback to summary
public default CompletableFuture<Stream> newStream(HeadersFrame frame, Stream.Listener listener)

Sends the given HEADERS frame to create a new Stream.

Parameters
frame:HeadersFrame

the HEADERS frame containing the HTTP headers

listener:Stream.Listener

the listener that gets notified of stream events

Returns:CompletableFuture<Stream>

a CompletableFuture that is notified of the stream creation

newStreamback to summary
public void newStream(HeadersFrame frame, Promise<Stream> promise, Stream.Listener listener)

Sends the given HEADERS frame to create a new Stream.

Parameters
frame:HeadersFrame

the HEADERS frame containing the HTTP headers

promise:Promise<Stream>

the promise that gets notified of the stream creation

listener:Stream.Listener

the listener that gets notified of stream events

pingback to summary
public void ping(PingFrame frame, Callback callback)

Sends the given PING frame.

PING frames may be used to test the connection integrity and to measure round-trip time.

Parameters
frame:PingFrame

the PING frame to send

callback:Callback

the callback that gets notified when the frame has been sent

priorityback to summary
public int priority(PriorityFrame frame, Callback callback)

Sends the given PRIORITY frame.

If the frame references a streamId that does not exist (for example 0), then a new streamId will be allocated, to support unused anchor streams that act as parent for other streams.

Parameters
frame:PriorityFrame

the PRIORITY frame to send

callback:Callback

the callback that gets notified when the frame has been sent

Returns:int

the new stream id generated by the PRIORITY frame, or the stream id that it is already referencing

settingsback to summary
public default CompletableFuture<Void> settings(SettingsFrame frame)

Sends the given SETTINGS frame to configure the session.

Parameters
frame:SettingsFrame

the SETTINGS frame to send

Returns:CompletableFuture<Void>

a CompletableFuture that is notified when the frame has been sent

settingsback to summary
public void settings(SettingsFrame frame, Callback callback)

Sends the given SETTINGS frame to configure the session.

Parameters
frame:SettingsFrame

the SETTINGS frame to send

callback:Callback

the callback that gets notified when the frame has been sent

shutdownback to summary
public CompletableFuture<Void> shutdown()

Gracefully closes the session, returning a CompletableFuture that is completed when all the streams currently being processed are completed.

Implementation is idempotent, i.e. calling this method a second time or concurrently results in a no-operation.

Returns:CompletableFuture<Void>

a CompletableFuture that is completed when all the streams are completed

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

public Interface Session.Listener

Known Direct Subinterfaces
org.eclipse.jetty.http2.api.server.ServerSessionListener

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

See Also
Session

Method Summary

Modifier and TypeMethod and Description
public default void
onClose(Session
the session
session, GoAwayFrame
the GOAWAY frame that caused the session to be closed
frame, Callback
the callback to notify of the GOAWAY processing
callback)

Callback method invoked when a GOAWAY frame caused the session to be closed.

public default void
onFailure(Session
the session
session, Throwable
the failure
failure, Callback
the callback to notify of failure processing
callback)

Callback method invoked when a failure has been detected for this session.

public default void
onGoAway(Session
the session
session, GoAwayFrame
the GOAWAY frame received
frame)

Callback method invoked when a GOAWAY frame has been received.

public default boolean

Returns:

whether the session should be closed
onIdleTimeout(Session
the session
session)

Callback method invoked when the idle timeout expired.

public default Stream.Listener

Returns:

a Stream.Listener that will be notified of stream events
onNewStream(Stream
the newly created stream
stream, HeadersFrame
the HEADERS frame received
frame)

Callback method invoked when a new stream is being created upon receiving a HEADERS frame representing an HTTP request.

public default void
onPing(Session
the session
session, PingFrame
the PING frame received
frame)

Callback method invoked when a PING frame has been received.

public default Map<Integer, Integer>

Returns:

a (possibly empty or null) map containing SETTINGS configuration options to send.
onPreface(Session
the session
session)

Callback method invoked:

  • for clients, just before the preface is sent, to gather the SETTINGS configuration options the client wants to send to the server;
  • for servers, just after having received the preface, to gather the SETTINGS configuration options the server wants to send to the client.
public default void
onReset(Session
the session
session, ResetFrame
the RST_STREAM frame received
frame)

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

public default void
onSettings(Session
the session
session, SettingsFrame
the SETTINGS frame received
frame)

Callback method invoked when a SETTINGS frame has been received.

Method Detail

onCloseback to summary
public default void onClose(Session session, GoAwayFrame frame, Callback callback)

Callback method invoked when a GOAWAY frame caused the session to be closed.

Parameters
session:Session

the session

frame:GoAwayFrame

the GOAWAY frame that caused the session to be closed

callback:Callback

the callback to notify of the GOAWAY processing

onFailureback to summary
public default void onFailure(Session session, Throwable failure, Callback callback)

Callback method invoked when a failure has been detected for this session.

Parameters
session:Session

the session

failure:Throwable

the failure

callback:Callback

the callback to notify of failure processing

onGoAwayback to summary
public default void onGoAway(Session session, GoAwayFrame frame)

Callback method invoked when a GOAWAY frame has been received.

Parameters
session:Session

the session

frame:GoAwayFrame

the GOAWAY frame received

onIdleTimeoutback to summary
public default boolean onIdleTimeout(Session session)

Callback method invoked when the idle timeout expired.

Parameters
session:Session

the session

Returns:boolean

whether the session should be closed

onNewStreamback to summary
public default Stream.Listener onNewStream(Stream stream, HeadersFrame frame)

Callback method invoked when a new stream is being created upon receiving a HEADERS frame representing an HTTP request.

Applications should implement this method to process HTTP requests, typically providing an HTTP response via Stream#headers(HeadersFrame, Callback).

Applications can detect whether request DATA frames will be arriving by testing HeadersFrame#isEndStream(). If the application is interested in processing the DATA frames, it must demand for DATA frames using Stream#demand() and then return either a Stream.Listener implementation that overrides Stream.Listener#onDataAvailable(Stream) where applications can read from the Stream via Stream#readData(), or Stream.Listener#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 DATA frames.

Parameters
stream:Stream

the newly created stream

frame:HeadersFrame

the HEADERS frame received

Returns:Stream.Listener

a Stream.Listener that will be notified of stream events

onPingback to summary
public default void onPing(Session session, PingFrame frame)

Callback method invoked when a PING frame has been received.

Parameters
session:Session

the session

frame:PingFrame

the PING frame received

onPrefaceback to summary
public default Map<Integer, Integer> onPreface(Session session)

Callback method invoked:

  • for clients, just before the preface is sent, to gather the SETTINGS configuration options the client wants to send to the server;
  • for servers, just after having received the preface, to gather the SETTINGS configuration options the server wants to send to the client.
Parameters
session:Session

the session

Returns:Map<Integer, Integer>

a (possibly empty or null) map containing SETTINGS configuration options to send.

onResetback to summary
public default void onReset(Session session, ResetFrame frame)

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

Parameters
session:Session

the session

frame:ResetFrame

the RST_STREAM frame received

See Also
Stream.Listener#onReset(Stream, ResetFrame, Callback)
onSettingsback to summary
public default void onSettings(Session session, SettingsFrame frame)

Callback method invoked when a SETTINGS frame has been received.

Parameters
session:Session

the session

frame:SettingsFrame

the SETTINGS frame received