View Javadoc

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 }