1 /*
2 * Copyright (c) 2012 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.eclipse.jetty.spdy.api;
18
19 import java.util.EventListener;
20 import java.util.Set;
21 import java.util.concurrent.Future;
22 import java.util.concurrent.TimeUnit;
23
24 /**
25 * <p>A {@link Session} represents the client-side endpoint of a SPDY connection to a single origin server.</p>
26 * <p>Once a {@link Session} has been obtained, it can be used to open SPDY streams:</p>
27 * <pre>
28 * Session session = ...;
29 * SynInfo synInfo = new SynInfo(true);
30 * session.syn(synInfo, new Stream.FrameListener.Adapter()
31 * {
32 * public void onReply(Stream stream, ReplyInfo replyInfo)
33 * {
34 * // Stream reply received
35 * }
36 * });
37 * </pre>
38 * <p>A {@link Session} is the active part of the endpoint, and by calling its API applications can generate
39 * events on the connection; conversely {@link SessionFrameListener} is the passive part of the endpoint, and
40 * has callbacks that are invoked when events happen on the connection.</p>
41 *
42 * @see SessionFrameListener
43 */
44 public interface Session
45 {
46 /**
47 * @return the SPDY protocol version used by this session
48 */
49 public short getVersion();
50
51 /**
52 * <p>Registers the given {@code listener} to be notified of session events.</p>
53 *
54 * @param listener the listener to register
55 * @see #removeListener(Listener)
56 */
57 public void addListener(Listener listener);
58
59 /**
60 * <p>Deregisters the give {@code listener} from being notified of session events.</p>
61 *
62 * @param listener the listener to deregister
63 * @see #addListener(Listener)
64 */
65 public void removeListener(Listener listener);
66
67 /**
68 * <p>Sends asynchronously a SYN_FRAME to create a new {@link Stream SPDY stream}.</p>
69 * <p>Callers may use the returned future to wait for the stream to be created, and
70 * use the stream, for example, to send data frames.</p>
71 *
72 * @param synInfo the metadata to send on stream creation
73 * @param listener the listener to invoke when events happen on the stream just created
74 * @return a future for the stream that will be created
75 * @see #syn(SynInfo, StreamFrameListener, long, TimeUnit, Handler)
76 */
77 public Future<Stream> syn(SynInfo synInfo, StreamFrameListener listener);
78
79 /**
80 * <p>Sends asynchronously a SYN_FRAME to create a new {@link Stream SPDY stream}.</p>
81 * <p>Callers may pass a non-null completion handler to be notified of when the
82 * stream has been created and use the stream, for example, to send data frames.</p>
83 *
84 * @param synInfo the metadata to send on stream creation
85 * @param listener the listener to invoke when events happen on the stream just created
86 * @param timeout the operation's timeout
87 * @param unit the timeout's unit
88 * @param handler the completion handler that gets notified of stream creation
89 * @see #syn(SynInfo, StreamFrameListener)
90 */
91 public void syn(SynInfo synInfo, StreamFrameListener listener, long timeout, TimeUnit unit, Handler<Stream> handler);
92
93
94 /**
95 * <p>Sends asynchronously a RST_STREAM to abort a stream.</p>
96 * <p>Callers may use the returned future to wait for the reset to be sent.</p>
97 *
98 * @param rstInfo the metadata to reset the stream
99 * @return a future to wait for the reset to be sent
100 * @see #rst(RstInfo, long, TimeUnit, Handler)
101 */
102 public Future<Void> rst(RstInfo rstInfo);
103
104 /**
105 * <p>Sends asynchronously a RST_STREAM to abort a stream.</p>
106 * <p>Callers may pass a non-null completion handler to be notified of when the
107 * reset has been actually sent.</p>
108 *
109 * @param rstInfo the metadata to reset the stream
110 * @param timeout the operation's timeout
111 * @param unit the timeout's unit
112 * @param handler the completion handler that gets notified of reset's send
113 * @see #rst(RstInfo)
114 */
115 public void rst(RstInfo rstInfo, long timeout, TimeUnit unit, Handler<Void> handler);
116
117 /**
118 * <p>Sends asynchronously a SETTINGS to configure the SPDY connection.</p>
119 * <p>Callers may use the returned future to wait for the settings to be sent.</p>
120 *
121 * @param settingsInfo the metadata to send
122 * @return a future to wait for the settings to be sent
123 * @see #settings(SettingsInfo, long, TimeUnit, Handler)
124 */
125 public Future<Void> settings(SettingsInfo settingsInfo);
126
127 /**
128 * <p>Sends asynchronously a SETTINGS to configure the SPDY connection.</p>
129 * <p>Callers may pass a non-null completion handler to be notified of when the
130 * settings has been actually sent.</p>
131 *
132 * @param settingsInfo the metadata to send
133 * @param timeout the operation's timeout
134 * @param unit the timeout's unit
135 * @param handler the completion handler that gets notified of settings' send
136 * @see #settings(SettingsInfo)
137 */
138 public void settings(SettingsInfo settingsInfo, long timeout, TimeUnit unit, Handler<Void> handler);
139
140 /**
141 * <p>Sends asynchronously a PING, normally to measure round-trip time.</p>
142 * <p>Callers may use the returned future to wait for the ping to be sent.</p>
143 *
144 * @return a future for the metadata sent
145 * @see #ping(long, TimeUnit, Handler)
146 */
147 public Future<PingInfo> ping();
148
149 /**
150 * <p>Sends asynchronously a PING, normally to measure round-trip time.</p>
151 * <p>Callers may pass a non-null completion handler to be notified of when the
152 * ping has been actually sent.</p>
153 *
154 * @param timeout the operation's timeout
155 * @param unit the timeout's unit
156 * @param handler the completion handler that gets notified of ping's send
157 * @see #ping()
158 */
159 public void ping(long timeout, TimeUnit unit, Handler<PingInfo> handler);
160
161 /**
162 * <p>Closes gracefully this session, sending a GO_AWAY frame and then closing the TCP connection.</p>
163 * <p>Callers may use the returned future to wait for the go away to be sent.</p>
164 *
165 * @return a future to wait for the go away to be sent
166 * @see #goAway(long, TimeUnit, Handler)
167 */
168 public Future<Void> goAway();
169
170 /**
171 * <p>Closes gracefully this session, sending a GO_AWAY frame and then closing the TCP connection.</p>
172 * <p>Callers may pass a non-null completion handler to be notified of when the
173 * go away has been actually sent.</p>
174 *
175 * @param timeout the operation's timeout
176 * @param unit the timeout's unit
177 * @param handler the completion handler that gets notified of go away's send
178 * @see #goAway()
179 */
180 public void goAway(long timeout, TimeUnit unit, Handler<Void> handler);
181
182 /**
183 * @return the streams currently active in this session
184 */
185 public Set<Stream> getStreams();
186
187 /**
188 * <p>Super interface for listeners with callbacks that are invoked on specific session events.</p>
189 */
190 public interface Listener extends EventListener
191 {
192 }
193
194 /**
195 * <p>Specialized listener that is invoked upon creation and removal of streams.</p>
196 */
197 public interface StreamListener extends Listener
198 {
199 /**
200 * <p>Callback invoked when a new SPDY stream is created.</p>
201 *
202 * @param stream the stream just created
203 */
204 public void onStreamCreated(Stream stream);
205
206 /**
207 * <p>Callback invoked when a SPDY stream is closed.</p>
208 *
209 * @param stream the stream just closed.
210 */
211 public void onStreamClosed(Stream stream);
212
213 /**
214 * <p>Empty implementation of {@link StreamListener}.</p>
215 */
216 public static class Adapter implements StreamListener
217 {
218 @Override
219 public void onStreamCreated(Stream stream)
220 {
221 }
222
223 @Override
224 public void onStreamClosed(Stream stream)
225 {
226 }
227 }
228 }
229 }