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