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 * @return the RstInfo belonging to the reset to be sent
102 * @see #rst(RstInfo, Callback)
103 */
104 public void rst(RstInfo rstInfo) throws InterruptedException, ExecutionException, TimeoutException;
105
106 /**
107 * <p>Sends asynchronously a RST_STREAM to abort a stream.</p>
108 * <p>Callers may pass a non-null completion callback 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 callback the completion callback that gets notified of reset's send
113 * @see #rst(RstInfo)
114 */
115 public void rst(RstInfo rstInfo, Callback callback);
116
117 /**
118 * <p>Sends synchronously a SETTINGS to configure the SPDY connection.</p>
119 *
120 * @param settingsInfo the metadata to send
121 * @see #settings(SettingsInfo, Callback)
122 */
123 public void settings(SettingsInfo settingsInfo) throws ExecutionException, InterruptedException, TimeoutException;
124
125 /**
126 * <p>Sends asynchronously a SETTINGS to configure the SPDY connection.</p>
127 * <p>Callers may pass a non-null completion callback to be notified of when the
128 * settings has been actually sent.</p>
129 *
130 *
131 * @param settingsInfo the metadata to send
132 * @param callback the completion callback that gets notified of settings' send
133 * @see #settings(SettingsInfo)
134 */
135 public void settings(SettingsInfo settingsInfo, Callback callback);
136
137 /**
138 * <p>Sends synchronously a PING, normally to measure round-trip time.</p>
139 *
140 * @see #ping(PingInfo, Promise
141 * @param pingInfo
142 */
143 public PingResultInfo ping(PingInfo pingInfo) throws ExecutionException, InterruptedException, TimeoutException;
144
145 /**
146 * <p>Sends asynchronously a PING, normally to measure round-trip time.</p>
147 * <p>Callers may pass a non-null completion callback to be notified of when the
148 * ping has been actually sent.</p>
149 *
150 * @param pingInfo
151 * @param promise the completion callback that gets notified of ping's send
152 * @see #ping(PingInfo)
153 */
154 public void ping(PingInfo pingInfo, Promise<PingResultInfo> promise);
155
156 /**
157 * <p>Closes gracefully this session, sending a GO_AWAY frame and then closing the TCP connection.</p>
158 *
159 * @see #goAway(GoAwayInfo, Callback)
160 * @param goAwayInfo
161 */
162 public void goAway(GoAwayInfo goAwayInfo) throws ExecutionException, InterruptedException, TimeoutException;
163
164 /**
165 * <p>Closes gracefully this session, sending a GO_AWAY frame and then closing the TCP connection.</p>
166 * <p>Callers may pass a non-null completion callback to be notified of when the
167 * go away has been actually sent.</p>
168 *
169 * @param goAwayInfo
170 * @param callback the completion callback that gets notified of go away's send
171 * @see #goAway(GoAwayInfo)
172 */
173 public void goAway(GoAwayInfo goAwayInfo, Callback callback);
174
175 /**
176 * @return a snapshot of the streams currently active in this session
177 * @see #getStream(int)
178 */
179 public Set<Stream> getStreams();
180
181 /**
182 * @param streamId the id of the stream to retrieve
183 * @return the stream with the given stream id
184 * @see #getStreams()
185 */
186 public Stream getStream(int streamId);
187
188 /**
189 * @param key the attribute key
190 * @return an arbitrary object associated with the given key to this session
191 * @see #setAttribute(String, Object)
192 */
193 public Object getAttribute(String key);
194
195 /**
196 * @param key the attribute key
197 * @param value an arbitrary object to associate with the given key to this session
198 * @see #getAttribute(String)
199 * @see #removeAttribute(String)
200 */
201 public void setAttribute(String key, Object value);
202
203 /**
204 * @param key the attribute key
205 * @return the arbitrary object associated with the given key to this session
206 * @see #setAttribute(String, Object)
207 */
208 public Object removeAttribute(String key);
209
210 /**
211 * @return the local address of the underlying endpoint
212 */
213 public InetSocketAddress getLocalAddress();
214
215 /**
216 * @return the remote address of the underlying endpoint
217 */
218 public InetSocketAddress getRemoteAddress();
219
220 /**
221 * <p>Super interface for listeners with callbacks that are invoked on specific session events.</p>
222 */
223 public interface Listener extends EventListener
224 {
225 }
226
227 /**
228 * <p>Specialized listener that is invoked upon creation and removal of streams.</p>
229 */
230 public interface StreamListener extends Listener
231 {
232 /**
233 * <p>Callback invoked when a new SPDY stream is created.</p>
234 *
235 * @param stream the stream just created
236 */
237 public void onStreamCreated(Stream stream);
238
239 /**
240 * <p>Callback invoked when a SPDY stream is closed.</p>
241 *
242 * @param stream the stream just closed.
243 */
244 public void onStreamClosed(Stream stream);
245
246 /**
247 * <p>Empty implementation of {@link StreamListener}.</p>
248 */
249 public static class Adapter implements StreamListener
250 {
251 @Override
252 public void onStreamCreated(Stream stream)
253 {
254 }
255
256 @Override
257 public void onStreamClosed(Stream stream)
258 {
259 }
260 }
261 }
262 }