1 //========================================================================
2 //Copyright 2011-2012 Mort Bay Consulting Pty. Ltd.
3 //------------------------------------------------------------------------
4 //All rights reserved. This program and the accompanying materials
5 //are made available under the terms of the Eclipse Public License v1.0
6 //and Apache License v2.0 which accompanies this distribution.
7 //The Eclipse Public License is available at
8 //http://www.eclipse.org/legal/epl-v10.html
9 //The Apache License v2.0 is available at
10 //http://www.opensource.org/licenses/apache2.0.php
11 //You may elect to redistribute this code under either of these licenses.
12 //========================================================================
13
14 package org.eclipse.jetty.spdy.api;
15
16 import java.util.EventListener;
17 import java.util.Set;
18 import java.util.concurrent.Future;
19 import java.util.concurrent.TimeUnit;
20
21 /**
22 * <p>A {@link Session} represents the client-side endpoint of a SPDY connection to a single origin server.</p>
23 * <p>Once a {@link Session} has been obtained, it can be used to open SPDY streams:</p>
24 * <pre>
25 * Session session = ...;
26 * SynInfo synInfo = new SynInfo(true);
27 * session.syn(synInfo, new Stream.FrameListener.Adapter()
28 * {
29 * public void onReply(Stream stream, ReplyInfo replyInfo)
30 * {
31 * // Stream reply received
32 * }
33 * });
34 * </pre>
35 * <p>A {@link Session} is the active part of the endpoint, and by calling its API applications can generate
36 * events on the connection; conversely {@link SessionFrameListener} is the passive part of the endpoint, and
37 * has callbacks that are invoked when events happen on the connection.</p>
38 *
39 * @see SessionFrameListener
40 */
41 public interface Session
42 {
43 /**
44 * @return the SPDY protocol version used by this session
45 */
46 public short getVersion();
47
48 /**
49 * <p>Registers the given {@code listener} to be notified of session events.</p>
50 *
51 * @param listener the listener to register
52 * @see #removeListener(Listener)
53 */
54 public void addListener(Listener listener);
55
56 /**
57 * <p>Deregisters the give {@code listener} from being notified of session events.</p>
58 *
59 * @param listener the listener to deregister
60 * @see #addListener(Listener)
61 */
62 public void removeListener(Listener listener);
63
64 /**
65 * <p>Sends asynchronously a SYN_FRAME to create a new {@link Stream SPDY stream}.</p>
66 * <p>Callers may use the returned future to wait for the stream to be created, and
67 * use the stream, for example, to send data frames.</p>
68 *
69 * @param synInfo the metadata to send on stream creation
70 * @param listener the listener to invoke when events happen on the stream just created
71 * @return a future for the stream that will be created
72 * @see #syn(SynInfo, StreamFrameListener, long, TimeUnit, Handler)
73 */
74 public Future<Stream> syn(SynInfo synInfo, StreamFrameListener listener);
75
76 /**
77 * <p>Sends asynchronously a SYN_FRAME to create a new {@link Stream SPDY stream}.</p>
78 * <p>Callers may pass a non-null completion handler to be notified of when the
79 * stream has been created and use the stream, for example, to send data frames.</p>
80 *
81 * @param synInfo the metadata to send on stream creation
82 * @param listener the listener to invoke when events happen on the stream just created
83 * @param timeout the operation's timeout
84 * @param unit the timeout's unit
85 * @param handler the completion handler that gets notified of stream creation
86 * @see #syn(SynInfo, StreamFrameListener)
87 */
88 public void syn(SynInfo synInfo, StreamFrameListener listener, long timeout, TimeUnit unit, Handler<Stream> handler);
89
90
91 /**
92 * <p>Sends asynchronously a RST_STREAM to abort a stream.</p>
93 * <p>Callers may use the returned future to wait for the reset to be sent.</p>
94 *
95 * @param rstInfo the metadata to reset the stream
96 * @return a future to wait for the reset to be sent
97 * @see #rst(RstInfo, long, TimeUnit, Handler)
98 */
99 public Future<Void> rst(RstInfo rstInfo);
100
101 /**
102 * <p>Sends asynchronously a RST_STREAM to abort a stream.</p>
103 * <p>Callers may pass a non-null completion handler to be notified of when the
104 * reset has been actually sent.</p>
105 *
106 * @param rstInfo the metadata to reset the stream
107 * @param timeout the operation's timeout
108 * @param unit the timeout's unit
109 * @param handler the completion handler that gets notified of reset's send
110 * @see #rst(RstInfo)
111 */
112 public void rst(RstInfo rstInfo, long timeout, TimeUnit unit, Handler<Void> handler);
113
114 /**
115 * <p>Sends asynchronously a SETTINGS to configure the SPDY connection.</p>
116 * <p>Callers may use the returned future to wait for the settings to be sent.</p>
117 *
118 * @param settingsInfo the metadata to send
119 * @return a future to wait for the settings to be sent
120 * @see #settings(SettingsInfo, long, TimeUnit, Handler)
121 */
122 public Future<Void> settings(SettingsInfo settingsInfo);
123
124 /**
125 * <p>Sends asynchronously a SETTINGS to configure the SPDY connection.</p>
126 * <p>Callers may pass a non-null completion handler to be notified of when the
127 * settings has been actually sent.</p>
128 *
129 * @param settingsInfo the metadata to send
130 * @param timeout the operation's timeout
131 * @param unit the timeout's unit
132 * @param handler the completion handler that gets notified of settings' send
133 * @see #settings(SettingsInfo)
134 */
135 public void settings(SettingsInfo settingsInfo, long timeout, TimeUnit unit, Handler<Void> handler);
136
137 /**
138 * <p>Sends asynchronously a PING, normally to measure round-trip time.</p>
139 * <p>Callers may use the returned future to wait for the ping to be sent.</p>
140 *
141 * @return a future for the metadata sent
142 * @see #ping(long, TimeUnit, Handler)
143 */
144 public Future<PingInfo> ping();
145
146 /**
147 * <p>Sends asynchronously a PING, normally to measure round-trip time.</p>
148 * <p>Callers may pass a non-null completion handler to be notified of when the
149 * ping has been actually sent.</p>
150 *
151 * @param timeout the operation's timeout
152 * @param unit the timeout's unit
153 * @param handler the completion handler that gets notified of ping's send
154 * @see #ping()
155 */
156 public void ping(long timeout, TimeUnit unit, Handler<PingInfo> handler);
157
158 /**
159 * <p>Closes gracefully this session, sending a GO_AWAY frame and then closing the TCP connection.</p>
160 * <p>Callers may use the returned future to wait for the go away to be sent.</p>
161 *
162 * @return a future to wait for the go away to be sent
163 * @see #goAway(long, TimeUnit, Handler)
164 */
165 public Future<Void> goAway();
166
167 /**
168 * <p>Closes gracefully this session, sending a GO_AWAY frame and then closing the TCP connection.</p>
169 * <p>Callers may pass a non-null completion handler to be notified of when the
170 * go away has been actually sent.</p>
171 *
172 * @param timeout the operation's timeout
173 * @param unit the timeout's unit
174 * @param handler the completion handler that gets notified of go away's send
175 * @see #goAway()
176 */
177 public void goAway(long timeout, TimeUnit unit, Handler<Void> handler);
178
179 /**
180 * @return a snapshot of the streams currently active in this session
181 * @see #getStream(int)
182 */
183 public Set<Stream> getStreams();
184
185 /**
186 * @param streamId the id of the stream to retrieve
187 * @return the stream with the given stream id
188 * @see #getStreams()
189 */
190 public Stream getStream(int streamId);
191
192 /**
193 * @param key the attribute key
194 * @return an arbitrary object associated with the given key to this session
195 * @see #setAttribute(String, Object)
196 */
197 public Object getAttribute(String key);
198
199 /**
200 * @param key the attribute key
201 * @param value an arbitrary object to associate with the given key to this session
202 * @see #getAttribute(String)
203 * @see #removeAttribute(String)
204 */
205 public void setAttribute(String key, Object value);
206
207 /**
208 * @param key the attribute key
209 * @return the arbitrary object associated with the given key to this session
210 * @see #setAttribute(String, Object)
211 */
212 public Object removeAttribute(String key);
213
214 /**
215 * <p>Super interface for listeners with callbacks that are invoked on specific session events.</p>
216 */
217 public interface Listener extends EventListener
218 {
219 }
220
221 /**
222 * <p>Specialized listener that is invoked upon creation and removal of streams.</p>
223 */
224 public interface StreamListener extends Listener
225 {
226 /**
227 * <p>Callback invoked when a new SPDY stream is created.</p>
228 *
229 * @param stream the stream just created
230 */
231 public void onStreamCreated(Stream stream);
232
233 /**
234 * <p>Callback invoked when a SPDY stream is closed.</p>
235 *
236 * @param stream the stream just closed.
237 */
238 public void onStreamClosed(Stream stream);
239
240 /**
241 * <p>Empty implementation of {@link StreamListener}.</p>
242 */
243 public static class Adapter implements StreamListener
244 {
245 @Override
246 public void onStreamCreated(Stream stream)
247 {
248 }
249
250 @Override
251 public void onStreamClosed(Stream stream)
252 {
253 }
254 }
255 }
256 }