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;
20
21 import org.eclipse.jetty.http2.api.Session;
22 import org.eclipse.jetty.http2.api.Stream;
23 import org.eclipse.jetty.http2.frames.DataFrame;
24 import org.eclipse.jetty.http2.frames.Frame;
25 import org.eclipse.jetty.http2.frames.PushPromiseFrame;
26 import org.eclipse.jetty.http2.frames.WindowUpdateFrame;
27 import org.eclipse.jetty.util.Callback;
28 import org.eclipse.jetty.util.Promise;
29
30 /**
31 * <p>The SPI interface for implementing a HTTP/2 session.</p>
32 * <p>This class extends {@link Session} by adding the methods required to
33 * implement the HTTP/2 session functionalities.</p>
34 */
35 public interface ISession extends Session
36 {
37 @Override
38 public IStream getStream(int streamId);
39
40 /**
41 * <p>Removes the given {@code stream}.</p>
42 *
43 * @param stream the stream to remove
44 */
45 public void removeStream(IStream stream);
46
47 /**
48 * <p>Enqueues the given frames to be written to the connection.</p>
49 *
50 * @param stream the stream the frames belong to
51 * @param callback the callback that gets notified when the frames have been sent
52 * @param frame the first frame to enqueue
53 * @param frames additional frames to enqueue
54 */
55 public void frames(IStream stream, Callback callback, Frame frame, Frame... frames);
56
57 /**
58 * <p>Enqueues the given PUSH_PROMISE frame to be written to the connection.</p>
59 * <p>Differently from {@link #frames(IStream, Callback, Frame, Frame...)}, this method
60 * generates atomically the stream id for the pushed stream.</p>
61 *
62 * @param stream the stream associated to the pushed stream
63 * @param promise the promise that gets notified of the pushed stream creation
64 * @param frame the PUSH_PROMISE frame to enqueue
65 * @param listener the listener that gets notified of pushed stream events
66 */
67 public void push(IStream stream, Promise<Stream> promise, PushPromiseFrame frame, Stream.Listener listener);
68
69 /**
70 * <p>Enqueues the given DATA frame to be written to the connection.</p>
71 *
72 * @param stream the stream the data frame belongs to
73 * @param callback the callback that gets notified when the frame has been sent
74 * @param frame the DATA frame to send
75 */
76 public void data(IStream stream, Callback callback, DataFrame frame);
77
78 /**
79 * <p>Updates the session send window by the given {@code delta}.</p>
80 *
81 * @param delta the delta value (positive or negative) to add to the session send window
82 * @return the previous value of the session send window
83 */
84 public int updateSendWindow(int delta);
85
86 /**
87 * <p>Updates the session receive window by the given {@code delta}.</p>
88 *
89 * @param delta the delta value (positive or negative) to add to the session receive window
90 * @return the previous value of the session receive window
91 */
92 public int updateRecvWindow(int delta);
93
94 /**
95 * <p>Callback method invoked when a WINDOW_UPDATE frame has been received.</p>
96 *
97 * @param stream the stream the window update belongs to, or null if the window update belongs to the session
98 * @param frame the WINDOW_UPDATE frame received
99 */
100 public void onWindowUpdate(IStream stream, WindowUpdateFrame frame);
101
102 /**
103 * @return whether the push functionality is enabled
104 */
105 public boolean isPushEnabled();
106
107 /**
108 * <p>Callback invoked when the connection reads -1.</p>
109 *
110 * @see #onIdleTimeout()
111 * @see #close(int, String, Callback)
112 */
113 public void onShutdown();
114
115 /**
116 * <p>Callback invoked when the idle timeout expires.</p>
117 *
118 * @see #onShutdown()
119 * @see #close(int, String, Callback)
120 */
121 public boolean onIdleTimeout();
122
123 /**
124 * <p>Callback method invoked during an HTTP/1.1 to HTTP/2 upgrade requests
125 * to process the given synthetic frame.</p>
126 *
127 * @param frame the synthetic frame to process
128 */
129 public void onFrame(Frame frame);
130 }