org.eclipse.jetty.spdy.api

Interface Stream

All Known Subinterfaces:

IStream

All Known Implementing Classes:

StandardStream

public interface Stream

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 SPDY streams for a SPDY session.

SPDY streams may terminate without this implying that the SPDY session is terminated.

If SPDY is used to transport the HTTP protocol, then a SPDY stream maps to a HTTP request/response cycle, and after the request/response cycle is completed, the stream is closed, and other streams may be opened. Differently from HTTP, though, multiple SPDY streams may be opened concurrently on the same SPDY session.

Like Session, Stream is the active part and by calling its API applications can generate events on the stream; conversely, StreamFrameListener is the passive part, and its callbacks are invoked when events happen on the stream.

A Stream can send multiple data frames one after the other but implementations use a flow control mechanism that only sends the data frames if the other end has signalled that it can accept the frame.

Data frames should be sent sequentially only when the previous frame has been completely sent. The reason for this requirement is to avoid potentially confusing code such as:

 // WRONG CODE, DO NOT USE IT
 final Stream stream = ...;
 stream.data(StringDataInfo("chunk1", false), 5, TimeUnit.SECONDS, new Handler<Void>() { ... });
 stream.data(StringDataInfo("chunk2", true), 1, TimeUnit.SECONDS, new Handler<Void>() { ... });
 

where the second call to data(DataInfo, Callback) has a timeout smaller than the previous call.

The behavior of such style of invocations is unspecified (it may even throw an exception - similar to WritePendingException).

The correct sending of data frames is the following:

 final Stream stream = ...;
 ...
 // Blocking version
 stream.data(new StringDataInfo("chunk1", false)).get(1, TimeUnit.SECONDS);
 stream.data(new StringDataInfo("chunk2", true)).get(1, TimeUnit.SECONDS);

 // Asynchronous version
 stream.data(new StringDataInfo("chunk1", false), 1, TimeUnit.SECONDS, new Handler.Adapter<Void>()
 {
     public void completed(Void context)
     {
         stream.data(new StringDataInfo("chunk2", true));
     }
 });
 

See Also:

StreamFrameListener

Method Summary

Methods

Modifier and Type	Method and Description
void	data(DataInfo dataInfo) Sends asynchronously a DATA frame on this stream.
void	data(DataInfo dataInfo, Callback callback) Sends asynchronously a DATA frame on this stream.
Stream	getAssociatedStream()
Object	getAttribute(String key)
int	getId()
long	getIdleTimeout() Get the idle timeout set for this particular stream
byte	getPriority()
Set<Stream>	getPushedStreams()
Session	getSession()
void	headers(HeadersInfo headersInfo) Sends asynchronously a HEADER frame on this stream.
void	headers(HeadersInfo headersInfo, Callback callback) Sends asynchronously a HEADER frame on this stream.
boolean	isClosed()
boolean	isHalfClosed()
boolean	isReset()
boolean	isUnidirectional()
Stream	push(PushInfo pushInfo) Initiate a unidirectional spdy pushstream associated to this stream asynchronously
void	push(PushInfo pushInfo, Promise<Stream> promise) Initiate a unidirectional spdy pushstream associated to this stream asynchronously
Object	removeAttribute(String key)
void	reply(ReplyInfo replyInfo) Sends asynchronously a SYN_REPLY frame in response to a SYN_STREAM frame.
void	reply(ReplyInfo replyInfo, Callback callback) Sends asynchronously a SYN_REPLY frame in response to a SYN_STREAM frame.
void	setAttribute(String key, Object value)
void	setIdleTimeout(long timeout) Set an idle timeout for this stream

Method Detail

getId

int getId()

Returns:

the id of this stream

getPriority

byte getPriority()

Returns:

the priority of this stream

getSession

Session getSession()

Returns:

the session this stream is associated to

push

Stream push(PushInfo pushInfo)
            throws InterruptedException,
                   ExecutionException,
                   TimeoutException

Initiate a unidirectional spdy pushstream associated to this stream asynchronously

Callers may use the returned future to get the pushstream once it got created

Parameters:

pushInfo - the metadata to send on stream creation

Returns:

a future containing the stream once it got established

Throws:

InterruptedException

ExecutionException

TimeoutException

See Also:

push(PushInfo, Promise)

push

void push(PushInfo pushInfo,
        Promise<Stream> promise)

Initiate a unidirectional spdy pushstream associated to this stream asynchronously

Callers may pass a non-null completion promise to be notified of when the pushstream has been established.

Parameters:

pushInfo - the metadata to send on stream creation

promise - the completion promise that gets notified once the pushstream is established

See Also:

push(PushInfo)

reply

void reply(ReplyInfo replyInfo)
           throws InterruptedException,
                  ExecutionException,
                  TimeoutException

Sends asynchronously a SYN_REPLY frame in response to a SYN_STREAM frame.

Callers may use the returned future to wait for the reply to be actually sent.

Parameters:

replyInfo - the metadata to send

Throws:

InterruptedException

ExecutionException

TimeoutException

See Also:

reply(ReplyInfo, Callback), SessionFrameListener.onSyn(Stream, SynInfo)

reply

void reply(ReplyInfo replyInfo,
         Callback callback)

Sends asynchronously a SYN_REPLY frame in response to a SYN_STREAM frame.

Callers may pass a non-null completion callback to be notified of when the reply has been actually sent.

Parameters:

replyInfo - the metadata to send

callback - the completion callback that gets notified of reply sent

See Also:

reply(ReplyInfo)

data

void data(DataInfo dataInfo)
          throws InterruptedException,
                 ExecutionException,
                 TimeoutException

Sends asynchronously a DATA frame on this stream.

DATA frames should always be sent after a SYN_REPLY frame.

Callers may use the returned future to wait for the data to be actually sent.

Parameters:

dataInfo - the metadata to send

Throws:

InterruptedException

ExecutionException

TimeoutException

See Also:

data(DataInfo, Callback), reply(ReplyInfo)

data

void data(DataInfo dataInfo,
        Callback callback)

Sends asynchronously a DATA frame on this stream.

DATA frames should always be sent after a SYN_REPLY frame.

Callers may pass a non-null completion callback to be notified of when the data has been actually sent.

Parameters:

dataInfo - the metadata to send

callback - the completion callback that gets notified of data sent

See Also:

data(DataInfo)

headers

void headers(HeadersInfo headersInfo)
             throws InterruptedException,
                    ExecutionException,
                    TimeoutException

Sends asynchronously a HEADER frame on this stream.

HEADERS frames should always be sent after a SYN_REPLY frame.

Callers may use the returned future to wait for the headers to be actually sent.

Parameters:

headersInfo - the metadata to send

Throws:

InterruptedException

ExecutionException

TimeoutException

See Also:

headers(HeadersInfo, Callback), reply(ReplyInfo)

headers

void headers(HeadersInfo headersInfo,
           Callback callback)

Sends asynchronously a HEADER frame on this stream.

HEADERS frames should always be sent after a SYN_REPLY frame.

Callers may pass a non-null completion callback to be notified of when the headers have been actually sent.

Parameters:

headersInfo - the metadata to send

callback - the completion callback that gets notified of headers sent

See Also:

headers(HeadersInfo)

isUnidirectional

boolean isUnidirectional()

Returns:

whether this stream is unidirectional or not

isReset

boolean isReset()

Returns:

whether this stream has been reset

isClosed

boolean isClosed()

Returns:

whether this stream has been closed by both parties

See Also:

isHalfClosed()

isHalfClosed

boolean isHalfClosed()

Returns:

whether this stream has been closed by one party only

See Also:

isClosed()

getAttribute

Object getAttribute(String key)

Parameters:

key - the attribute 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.

See Also:

setAttribute(String, Object)

setAttribute

void setAttribute(String key,
                Object value)

Parameters:

key - the attribute key

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

See Also:

getAttribute(String), removeAttribute(String)

removeAttribute

Object removeAttribute(String key)

Parameters:

key - the attribute key

Returns:

the arbitrary object associated with the given key to this stream

See Also:

setAttribute(String, Object)

getAssociatedStream

Stream getAssociatedStream()

Returns:

the associated parent stream or null if this is not an associated stream

getPushedStreams

Set<Stream> getPushedStreams()

Returns:

associated child streams or an empty set if no associated streams exist

getIdleTimeout

long getIdleTimeout()

Get the idle timeout set for this particular stream

Returns:

the idle timeout

setIdleTimeout

void setIdleTimeout(long timeout)

Set an idle timeout for this stream

Parameters:

timeout -