1 //
2 // ========================================================================
3 // Copyright (c) 1995-2015 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 * @param local whether the stream is local or remote
45 */
46 public void removeStream(IStream stream, boolean local);
47
48 /**
49 * <p>Enqueues the given frames to be written to the connection.</p>
50 *
51 * @param stream the stream the frames belong to
52 * @param callback the callback that gets notified when the frames have been sent
53 * @param frame the first frame to enqueue
54 * @param frames additional frames to enqueue
55 */
56 public void frames(IStream stream, Callback callback, Frame frame, Frame... frames);
57
58 /**
59 * <p>Enqueues the given PUSH_PROMISE frame to be written to the connection.</p>
60 * <p>Differently from {@link #frames(IStream, Callback, Frame, Frame...)}, this method
61 * generates atomically the stream id for the pushed stream.</p>
62 *
63 * @param stream the stream associated to the pushed stream
64 * @param promise the promise that gets notified of the pushed stream creation
65 * @param frame the PUSH_PROMISE frame to enqueue
66 * @param listener the listener that gets notified of pushed stream events
67 */
68 public void push(IStream stream, Promise<Stream> promise, PushPromiseFrame frame, Stream.Listener listener);
69
70 /**
71 * <p>Enqueues the given DATA frame to be written to the connection.</p>
72 *
73 * @param stream the stream the data frame belongs to
74 * @param callback the callback that gets notified when the frame has been sent
75 * @param frame the DATA frame to send
76 */
77 public void data(IStream stream, Callback callback, DataFrame frame);
78
79 /**
80 * <p>Updates the session send window by the given {@code delta}.</p>
81 *
82 * @param delta the delta value (positive or negative) to add to the session send window
83 * @return the previous value of the session send window
84 */
85 public int updateSendWindow(int delta);
86
87 /**
88 * <p>Updates the session receive window by the given {@code delta}.</p>
89 *
90 * @param delta the delta value (positive or negative) to add to the session receive window
91 * @return the previous value of the session receive window
92 */
93 public int updateRecvWindow(int delta);
94
95 /**
96 * <p>Callback method invoked when a WINDOW_UPDATE frame has been received.</p>
97 *
98 * @param stream the stream the window update belongs to, or null if the window update belongs to the session
99 * @param frame the WINDOW_UPDATE frame received
100 */
101 public void onWindowUpdate(IStream stream, WindowUpdateFrame frame);
102
103 /**
104 * @return whether the push functionality is enabled
105 */
106 public boolean isPushEnabled();
107
108 /**
109 * <p>Callback invoked when the connection reads -1.</p>
110 *
111 * @see #onIdleTimeout()
112 * @see #close(int, String, Callback)
113 */
114 public void onShutdown();
115
116 /**
117 * <p>Callback invoked when the idle timeout expires.</p>
118 *
119 * @see #onShutdown()
120 * @see #close(int, String, Callback)
121 */
122 public void onIdleTimeout();
123
124 /**
125 * <p>Callback method invoked during an HTTP/1.1 to HTTP/2 upgrade requests
126 * to process the given synthetic frame.</p>
127 *
128 * @param frame the synthetic frame to process
129 */
130 public void onFrame(Frame frame);
131 }