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.net.InetSocketAddress;
22 import java.util.EventListener;
23 import java.util.Set;
24 import java.util.concurrent.ExecutionException;
25 import java.util.concurrent.TimeoutException;
26
27 import org.eclipse.jetty.util.Callback;
28 import org.eclipse.jetty.util.Promise;
29
30 /**
31 * <p>A {@link Session} represents the client-side endpoint of a SPDY connection to a single origin server.</p>
32 * <p>Once a {@link Session} has been obtained, it can be used to open SPDY streams:</p>
33 * <pre>
34 * Session session = ...;
35 * SynInfo synInfo = new SynInfo(true);
36 * session.push(synInfo, new Stream.FrameListener.Adapter()
37 * {
38 * public void onReply(Stream stream, ReplyInfo replyInfo)
39 * {
40 * // Stream reply received
41 * }
42 * });
43 * </pre>
44 * <p>A {@link Session} is the active part of the endpoint, and by calling its API applications can generate
45 * events on the connection; conversely {@link SessionFrameListener} is the passive part of the endpoint, and
46 * has callbacks that are invoked when events happen on the connection.</p>
47 *
48 * @see SessionFrameListener
49 */
50 public interface Session
51 {
52 /**
53 * @return the SPDY protocol version used by this session
54 */
55 public short getVersion();
56
57 /**
58 * <p>Registers the given {@code listener} to be notified of session events.</p>
59 *
60 * @param listener the listener to register
61 * @see #removeListener(Listener)
62 */
63 public void addListener(Listener listener);
64
65 /**
66 * <p>Deregisters the give {@code listener} from being notified of session events.</p>
67 *
68 * @param listener the listener to deregister
69 * @see #addListener(Listener)
70 */
71 public void removeListener(Listener listener);
72
73 /**
74 * <p>Sends a SYN_FRAME to create a new {@link Stream SPDY stream}.</p>
75 * <p>Callers may use the returned Stream for example, to send data frames.</p>
76 *
77 * @param synInfo the metadata to send on stream creation
78 * @param listener the listener to invoke when events happen on the stream just created
79 * @return the stream that will be created
80 * @see #syn(SynInfo, StreamFrameListener, Promise)
81 */
82 public Stream syn(SynInfo synInfo, StreamFrameListener listener) throws ExecutionException, InterruptedException, TimeoutException;
83
84 /**
85 * <p>Sends asynchronously a SYN_FRAME to create a new {@link Stream SPDY stream}.</p>
86 * <p>Callers may pass a non-null completion callback to be notified of when the
87 * stream has been created and use the stream, for example, to send data frames.</p>
88 *
89 *
90 * @param synInfo the metadata to send on stream creation
91 * @param listener the listener to invoke when events happen on the stream just created
92 * @param promise the completion callback that gets notified of stream creation
93 * @see #syn(SynInfo, StreamFrameListener)
94 */
95 public void syn(SynInfo synInfo, StreamFrameListener listener, Promise<Stream> promise);
96
97 /**
98 * <p>Sends synchronously a RST_STREAM to abort a stream.</p>
99 *
100 * @param rstInfo the metadata to reset the stream
101 * @see #rst(RstInfo, Callback)
102 */
103 public void rst(RstInfo rstInfo) throws InterruptedException, ExecutionException, TimeoutException;
104
105 /**
106 * <p>Sends asynchronously a RST_STREAM to abort a stream.</p>
107 * <p>Callers may pass a non-null completion callback to be notified of when the
108 * reset has been actually sent.</p>
109 *
110 * @param rstInfo the metadata to reset the stream
111 * @param callback the completion callback that gets notified of reset's send
112 * @see #rst(RstInfo)
113 */
114 public void rst(RstInfo rstInfo, Callback callback);
115
116 /**
117 * <p>Sends synchronously a SETTINGS to configure the SPDY connection.</p>
118 *
119 * @param settingsInfo the metadata to send
120 * @see #settings(SettingsInfo, Callback)
121 */
122 public void settings(SettingsInfo settingsInfo) throws ExecutionException, InterruptedException, TimeoutException;
123
124 /**
125 * <p>Sends asynchronously a SETTINGS to configure the SPDY connection.</p>
126 * <p>Callers may pass a non-null completion callback to be notified of when the
127 * settings has been actually sent.</p>
128 *
129 *
130 * @param settingsInfo the metadata to send
131 * @param callback the completion callback that gets notified of settings' send
132 * @see #settings(SettingsInfo)
133 */
134 public void settings(SettingsInfo settingsInfo, Callback callback);
135
136 /**
137 * <p>Sends synchronously a PING, normally to measure round-trip time.</p>
138 *
139 * @see #ping(PingInfo, Promise)
140 * @param pingInfo
141 */
142 public PingResultInfo ping(PingInfo pingInfo) throws ExecutionException, InterruptedException, TimeoutException;
143
144 /**
145 * <p>Sends asynchronously a PING, normally to measure round-trip time.</p>
146 * <p>Callers may pass a non-null completion callback to be notified of when the
147 * ping has been actually sent.</p>
148 *
149 * @param pingInfo
150 * @param promise the completion callback that gets notified of ping's send
151 * @see #ping(PingInfo)
152 */
153 public void ping(PingInfo pingInfo, Promise<PingResultInfo> promise);
154
155 /**
156 * <p>Closes gracefully this session, sending a GO_AWAY frame and then closing the TCP connection.</p>
157 *
158 * @see #goAway(GoAwayInfo, Callback)
159 * @param goAwayInfo
160 */
161 public void goAway(GoAwayInfo goAwayInfo) throws ExecutionException, InterruptedException, TimeoutException;
162
163 /**
164 * <p>Closes gracefully this session, sending a GO_AWAY frame and then closing the TCP connection.</p>
165 * <p>Callers may pass a non-null completion callback to be notified of when the
166 * go away has been actually sent.</p>
167 *
168 * @param goAwayInfo
169 * @param callback the completion callback that gets notified of go away's send
170 * @see #goAway(GoAwayInfo)
171 */
172 public void goAway(GoAwayInfo goAwayInfo, Callback callback);
173
174 /**
175 * @return a snapshot of the streams currently active in this session
176 * @see #getStream(int)
177 */
178 public Set<Stream> getStreams();
179
180 /**
181 * @param streamId the id of the stream to retrieve
182 * @return the stream with the given stream id
183 * @see #getStreams()
184 */
185 public Stream getStream(int streamId);
186
187 /**
188 * @param key the attribute key
189 * @return an arbitrary object associated with the given key to this session
190 * @see #setAttribute(String, Object)
191 */
192 public Object getAttribute(String key);
193
194 /**
195 * @param key the attribute key
196 * @param value an arbitrary object to associate with the given key to this session
197 * @see #getAttribute(String)
198 * @see #removeAttribute(String)
199 */
200 public void setAttribute(String key, Object value);
201
202 /**
203 * @param key the attribute key
204 * @return the arbitrary object associated with the given key to this session
205 * @see #setAttribute(String, Object)
206 */
207 public Object removeAttribute(String key);
208
209 /**
210 * @return the local address of the underlying endpoint
211 */
212 public InetSocketAddress getLocalAddress();
213
214 /**
215 * @return the remote address of the underlying endpoint
216 */
217 public InetSocketAddress getRemoteAddress();
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 }