1 //
2 // ========================================================================
3 // Copyright (c) 1995-2015 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.http2.api;
20
21 import java.util.Collection;
22 import java.util.Map;
23
24 import org.eclipse.jetty.http2.frames.DataFrame;
25 import org.eclipse.jetty.http2.frames.GoAwayFrame;
26 import org.eclipse.jetty.http2.frames.HeadersFrame;
27 import org.eclipse.jetty.http2.frames.PingFrame;
28 import org.eclipse.jetty.http2.frames.PriorityFrame;
29 import org.eclipse.jetty.http2.frames.ResetFrame;
30 import org.eclipse.jetty.http2.frames.SettingsFrame;
31 import org.eclipse.jetty.util.Callback;
32 import org.eclipse.jetty.util.Promise;
33
34 /**
35 * <p>A {@link Session} represents the client-side endpoint of a HTTP/2 connection to a single origin server.</p>
36 * <p>Once a {@link Session} has been obtained, it can be used to open HTTP/2 streams:</p>
37 * <pre>
38 * Session session = ...;
39 * HeadersFrame frame = ...;
40 * Promise<Stream> promise = ...
41 * session.newStream(frame, promise, new Stream.Listener.Adapter()
42 * {
43 * public void onHeaders(Stream stream, HeadersFrame frame)
44 * {
45 * // Reply received
46 * }
47 * });
48 * </pre>
49 * <p>A {@link Session} is the active part of the endpoint, and by calling its API applications can generate
50 * events on the connection; conversely {@link Session.Listener} is the passive part of the endpoint, and
51 * has callbacks that are invoked when events happen on the connection.</p>
52 *
53 * @see Session.Listener
54 */
55 public interface Session
56 {
57 /**
58 * <p>Sends the given HEADERS {@code frame} to create a new {@link Stream}.</p>
59 *
60 * @param frame the HEADERS frame containing the HTTP headers
61 * @param promise the promise that gets notified of the stream creation
62 * @param listener the listener that gets notified of stream events
63 */
64 public void newStream(HeadersFrame frame, Promise<Stream> promise, Stream.Listener listener);
65
66 /**
67 * <p>Sends the given PRIORITY {@code frame}.</p>
68 * <p>If the {@code frame} references a {@code streamId} that does not exist
69 * (for example {@code 0}), then a new {@code streamId} will be allocated, to
70 * support <em>unused anchor streams</em> that act as parent for other streams.</p>
71 *
72 * @param frame the PRIORITY frame to send
73 * @param callback the callback that gets notified when the frame has been sent
74 * @return the new stream id generated by the PRIORITY frame, or the stream id
75 * that it is already referencing
76 */
77 public int priority(PriorityFrame frame, Callback callback);
78
79 /**
80 * <p>Sends the given SETTINGS {@code frame} to configure the session.</p>
81 *
82 * @param frame the SETTINGS frame to send
83 * @param callback the callback that gets notified when the frame has been sent
84 */
85 public void settings(SettingsFrame frame, Callback callback);
86
87 /**
88 * <p>Sends the given PING {@code frame}.</p>
89 * <p>PING frames may be used to test the connection integrity and to measure
90 * round-trip time.</p>
91 *
92 * @param frame the PING frame to send
93 * @param callback the callback that gets notified when the frame has been sent
94 */
95 public void ping(PingFrame frame, Callback callback);
96
97 /**
98 * <p>Closes the session by sending a GOAWAY frame with the given error code
99 * and payload.</p>
100 * <p>The GOAWAY frame is sent only once; subsequent or concurrent attempts to
101 * close the session will have no effect.</p>
102 *
103 * @param error the error code
104 * @param payload an optional payload (may be null)
105 * @param callback the callback that gets notified when the frame has been sent
106 * @return true if the frame is being sent, false if the session was already closed
107 */
108 public boolean close(int error, String payload, Callback callback);
109
110 /**
111 * @return whether the session is not open
112 */
113 public boolean isClosed();
114
115 /**
116 * @return a snapshot of all the streams currently belonging to this session
117 */
118 public Collection<Stream> getStreams();
119
120 /**
121 * <p>Retrieves the stream with the given {@code streamId}.</p>
122 *
123 * @param streamId the stream id of the stream looked for
124 * @return the stream with the given id, or null if no such stream exist
125 */
126 public Stream getStream(int streamId);
127
128 /**
129 * <p>A {@link Listener} is the passive counterpart of a {@link Session} and
130 * receives events happening on a HTTP/2 connection.</p>
131 *
132 * @see Session
133 */
134 public interface Listener
135 {
136 /**
137 * <p>Callback method invoked when the preface has been received.</p>
138 *
139 * @param session the session
140 * @return a (possibly empty or null) map containing SETTINGS configuration
141 * options that are sent after the preface.
142 */
143 public Map<Integer, Integer> onPreface(Session session);
144
145 /**
146 * <p>Callback method invoked when a new stream is being created upon
147 * receiving a HEADERS frame representing a HTTP request.</p>
148 * <p>Applications should implement this method to process HTTP requests,
149 * typically providing a HTTP response via
150 * {@link Stream#headers(HeadersFrame, Callback)}.</p>
151 * <p>Applications can detect whether request DATA frames will be arriving
152 * by testing {@link HeadersFrame#isEndStream()}. If the application is
153 * interested in processing the DATA frames, it must return a
154 * {@link Stream.Listener} implementation that overrides
155 * {@link Stream.Listener#onData(Stream, DataFrame, Callback)}.</p>
156 *
157 * @param stream the newly created stream
158 * @param frame the HEADERS frame received
159 * @return a {@link Stream.Listener} that will be notified of stream events
160 */
161 public Stream.Listener onNewStream(Stream stream, HeadersFrame frame);
162
163 /**
164 * <p>Callback method invoked when a SETTINGS frame has been received.</p>
165 *
166 * @param session the session
167 * @param frame the SETTINGS frame received
168 */
169 public void onSettings(Session session, SettingsFrame frame);
170
171 /**
172 * <p>Callback method invoked when a PING frame has been received.</p>
173 *
174 * @param session the session
175 * @param frame the PING frame received
176 */
177 public void onPing(Session session, PingFrame frame);
178
179 /**
180 * <p>Callback method invoked when a RST_STREAM frame has been received for an unknown stream.</p>
181 *
182 * @param session the session
183 * @param frame the RST_STREAM frame received
184 * @see Stream.Listener#onReset(Stream, ResetFrame)
185 */
186 public void onReset(Session session, ResetFrame frame);
187
188 /**
189 * <p>Callback method invoked when a GOAWAY frame has been received.</p>
190 *
191 * @param session the session
192 * @param frame the GOAWAY frame received
193 */
194 public void onClose(Session session, GoAwayFrame frame);
195
196 /**
197 * <p>Callback method invoked when a failure has been detected for this session.</p>
198 *
199 * @param session the session
200 * @param failure the failure
201 */
202 public void onFailure(Session session, Throwable failure);
203
204 /**
205 * <p>Empty implementation of {@link Stream.Listener}.</p>
206 */
207 public static class Adapter implements Session.Listener
208 {
209 @Override
210 public Map<Integer, Integer> onPreface(Session session)
211 {
212 return null;
213 }
214
215 @Override
216 public Stream.Listener onNewStream(Stream stream, HeadersFrame frame)
217 {
218 return null;
219 }
220
221 @Override
222 public void onSettings(Session session, SettingsFrame frame)
223 {
224 }
225
226 @Override
227 public void onPing(Session session, PingFrame frame)
228 {
229 }
230
231 @Override
232 public void onReset(Session session, ResetFrame frame)
233 {
234 }
235
236 @Override
237 public void onClose(Session session, GoAwayFrame frame)
238 {
239 }
240
241 @Override
242 public void onFailure(Session session, Throwable failure)
243 {
244 }
245 }
246 }
247 }