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 org.eclipse.jetty.http2.frames.DataFrame; 22 import org.eclipse.jetty.http2.frames.HeadersFrame; 23 import org.eclipse.jetty.http2.frames.PushPromiseFrame; 24 import org.eclipse.jetty.http2.frames.ResetFrame; 25 import org.eclipse.jetty.util.Callback; 26 import org.eclipse.jetty.util.Promise; 27 28 /** 29 * <p>A {@link Stream} represents a bidirectional exchange of data on top of a {@link Session}.</p> 30 * <p>Differently from socket streams, where the input and output streams are permanently associated 31 * with the socket (and hence with the connection that the socket represents), there can be multiple 32 * HTTP/2 streams present concurrent for a HTTP/2 session.</p> 33 * <p>A {@link Stream} maps to a HTTP request/response cycle, and after the request/response cycle is 34 * completed, the stream is closed and removed from the session.</p> 35 * <p>Like {@link Session}, {@link Stream} is the active part and by calling its API applications 36 * can generate events on the stream; conversely, {@link Stream.Listener} is the passive part, and 37 * its callbacks are invoked when events happen on the stream.</p> 38 * 39 * @see Stream.Listener 40 */ 41 public interface Stream 42 { 43 /** 44 * @return the stream unique id 45 */ 46 public int getId(); 47 48 /** 49 * @return the session this stream is associated to 50 */ 51 public Session getSession(); 52 53 /** 54 * <p>Sends the given HEADERS {@code frame} representing a HTTP response.</p> 55 * 56 * @param frame the HEADERS frame to send 57 * @param callback the callback that gets notified when the frame has been sent 58 */ 59 public void headers(HeadersFrame frame, Callback callback); 60 61 /** 62 * <p>Sends the given PUSH_PROMISE {@code frame}.</p> 63 * 64 * @param frame the PUSH_PROMISE frame to send 65 * @param promise the promise that gets notified of the pushed stream creation 66 * @param listener the listener that gets notified of stream events 67 */ 68 public void push(PushPromiseFrame frame, Promise<Stream> promise, Listener listener); 69 70 /** 71 * <p>Sends the given DATA {@code frame}.</p> 72 * 73 * @param frame the DATA frame to send 74 * @param callback the callback that gets notified when the frame has been sent 75 */ 76 public void data(DataFrame frame, Callback callback); 77 78 /** 79 * <p>Sends the given RST_STREAM {@code frame}.</p> 80 * 81 * @param frame the RST_FRAME to send 82 * @param callback the callback that gets notified when the frame has been sent 83 */ 84 public void reset(ResetFrame frame, Callback callback); 85 86 /** 87 * @param key the attribute key 88 * @return an arbitrary object associated with the given key to this stream 89 * or null if no object can be found for the given key. 90 * @see #setAttribute(String, Object) 91 */ 92 public Object getAttribute(String key); 93 94 /** 95 * @param key the attribute key 96 * @param value an arbitrary object to associate with the given key to this stream 97 * @see #getAttribute(String) 98 * @see #removeAttribute(String) 99 */ 100 public void setAttribute(String key, Object value); 101 102 /** 103 * @param key the attribute key 104 * @return the arbitrary object associated with the given key to this stream 105 * @see #setAttribute(String, Object) 106 */ 107 public Object removeAttribute(String key); 108 109 /** 110 * @return whether this stream has been reset 111 */ 112 public boolean isReset(); 113 114 /** 115 * @return whether this stream is closed, both locally and remotely. 116 */ 117 public boolean isClosed(); 118 119 /** 120 * @return the stream idle timeout 121 * @see #setIdleTimeout(long) 122 */ 123 public long getIdleTimeout(); 124 125 /** 126 * @param idleTimeout the stream idle timeout 127 * @see #getIdleTimeout() 128 * @see Stream.Listener#onTimeout(Stream, Throwable) 129 */ 130 public void setIdleTimeout(long idleTimeout); 131 132 /** 133 * <p>A {@link Stream.Listener} is the passive counterpart of a {@link Stream} and receives 134 * events happening on a HTTP/2 stream.</p> 135 * 136 * @see Stream 137 */ 138 public interface Listener 139 { 140 /** 141 * <p>Callback method invoked when a HEADERS frame representing the HTTP response has been received.</p> 142 * 143 * @param stream the stream 144 * @param frame the HEADERS frame received 145 */ 146 public void onHeaders(Stream stream, HeadersFrame frame); 147 148 /** 149 * <p>Callback method invoked when a PUSH_PROMISE frame has been received.</p> 150 * 151 * @param stream the stream 152 * @param frame the PUSH_PROMISE frame received 153 * @return a {@link Stream.Listener} that will be notified of pushed stream events 154 */ 155 public Listener onPush(Stream stream, PushPromiseFrame frame); 156 157 /** 158 * <p>Callback method invoked when a DATA frame has been received.</p> 159 * 160 * @param stream the stream 161 * @param frame the DATA frame received 162 * @param callback the callback to complete when the bytes of the DATA frame have been consumed 163 */ 164 public void onData(Stream stream, DataFrame frame, Callback callback); 165 166 /** 167 * <p>Callback method invoked when a RST_STREAM frame has been received for this stream.</p> 168 * 169 * @param stream the stream 170 * @param frame the RST_FRAME received 171 * @see Session.Listener#onReset(Session, ResetFrame) 172 */ 173 public void onReset(Stream stream, ResetFrame frame); 174 175 /** 176 * <p>Callback method invoked when the stream exceeds its idle timeout.</p> 177 * 178 * @param stream the stream 179 * @param x the timeout failure 180 * @see #getIdleTimeout() 181 */ 182 public void onTimeout(Stream stream, Throwable x); 183 184 /** 185 * <p>Empty implementation of {@link Listener}</p> 186 */ 187 public static class Adapter implements Listener 188 { 189 @Override 190 public void onHeaders(Stream stream, HeadersFrame frame) 191 { 192 } 193 194 @Override 195 public Listener onPush(Stream stream, PushPromiseFrame frame) 196 { 197 return null; 198 } 199 200 @Override 201 public void onData(Stream stream, DataFrame frame, Callback callback) 202 { 203 callback.succeeded(); 204 } 205 206 @Override 207 public void onReset(Stream stream, ResetFrame frame) 208 { 209 } 210 211 @Override 212 public void onTimeout(Stream stream, Throwable x) 213 { 214 } 215 } 216 } 217 }