1 // 2 // ======================================================================== 3 // Copyright (c) 1995-2016 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:</p> 138 * <ul> 139 * <li>for clients, just before the preface is sent, to gather the 140 * SETTINGS configuration options the client wants to send to the server;</li> 141 * <li>for servers, just after having received the preface, to gather 142 * the SETTINGS configuration options the server wants to send to the 143 * client.</li> 144 * </ul> 145 * 146 * @param session the session 147 * @return a (possibly empty or null) map containing SETTINGS configuration 148 * options to send. 149 */ 150 public Map<Integer, Integer> onPreface(Session session); 151 152 /** 153 * <p>Callback method invoked when a new stream is being created upon 154 * receiving a HEADERS frame representing a HTTP request.</p> 155 * <p>Applications should implement this method to process HTTP requests, 156 * typically providing a HTTP response via 157 * {@link Stream#headers(HeadersFrame, Callback)}.</p> 158 * <p>Applications can detect whether request DATA frames will be arriving 159 * by testing {@link HeadersFrame#isEndStream()}. If the application is 160 * interested in processing the DATA frames, it must return a 161 * {@link Stream.Listener} implementation that overrides 162 * {@link Stream.Listener#onData(Stream, DataFrame, Callback)}.</p> 163 * 164 * @param stream the newly created stream 165 * @param frame the HEADERS frame received 166 * @return a {@link Stream.Listener} that will be notified of stream events 167 */ 168 public Stream.Listener onNewStream(Stream stream, HeadersFrame frame); 169 170 /** 171 * <p>Callback method invoked when a SETTINGS frame has been received.</p> 172 * 173 * @param session the session 174 * @param frame the SETTINGS frame received 175 */ 176 public void onSettings(Session session, SettingsFrame frame); 177 178 /** 179 * <p>Callback method invoked when a PING frame has been received.</p> 180 * 181 * @param session the session 182 * @param frame the PING frame received 183 */ 184 public void onPing(Session session, PingFrame frame); 185 186 /** 187 * <p>Callback method invoked when a RST_STREAM frame has been received for an unknown stream.</p> 188 * 189 * @param session the session 190 * @param frame the RST_STREAM frame received 191 * @see Stream.Listener#onReset(Stream, ResetFrame) 192 */ 193 public void onReset(Session session, ResetFrame frame); 194 195 /** 196 * <p>Callback method invoked when a GOAWAY frame has been received.</p> 197 * 198 * @param session the session 199 * @param frame the GOAWAY frame received 200 */ 201 public void onClose(Session session, GoAwayFrame frame); 202 203 /** 204 * <p>Callback method invoked when the idle timeout expired.</p> 205 * @param session the session 206 * @return whether the session should be closed 207 */ 208 public boolean onIdleTimeout(Session session); 209 210 /** 211 * <p>Callback method invoked when a failure has been detected for this session.</p> 212 * 213 * @param session the session 214 * @param failure the failure 215 */ 216 public void onFailure(Session session, Throwable failure); 217 218 /** 219 * <p>Empty implementation of {@link Stream.Listener}.</p> 220 */ 221 public static class Adapter implements Session.Listener 222 { 223 @Override 224 public Map<Integer, Integer> onPreface(Session session) 225 { 226 return null; 227 } 228 229 @Override 230 public Stream.Listener onNewStream(Stream stream, HeadersFrame frame) 231 { 232 return null; 233 } 234 235 @Override 236 public void onSettings(Session session, SettingsFrame frame) 237 { 238 } 239 240 @Override 241 public void onPing(Session session, PingFrame frame) 242 { 243 } 244 245 @Override 246 public void onReset(Session session, ResetFrame frame) 247 { 248 } 249 250 @Override 251 public void onClose(Session session, GoAwayFrame frame) 252 { 253 } 254 255 @Override 256 public boolean onIdleTimeout(Session session) 257 { 258 return true; 259 } 260 261 @Override 262 public void onFailure(Session session, Throwable failure) 263 { 264 } 265 } 266 } 267 }