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 }