1 /*
2 * Copyright 2014 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License, version 2.0 (the
5 * "License"); you may not use this file except in compliance with the License. You may obtain a
6 * copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software distributed under the License
11 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
12 * or implied. See the License for the specific language governing permissions and limitations under
13 * the License.
14 */
15
16 package io.netty.handler.codec.http2;
17
18 /**
19 * A single stream within an HTTP2 connection. Streams are compared to each other by priority.
20 */
21 public interface Http2Stream {
22
23 /**
24 * The allowed states of an HTTP2 stream.
25 */
26 enum State {
27 IDLE(false, false),
28 RESERVED_LOCAL(false, false),
29 RESERVED_REMOTE(false, false),
30 OPEN(true, true),
31 HALF_CLOSED_LOCAL(false, true),
32 HALF_CLOSED_REMOTE(true, false),
33 CLOSED(false, false);
34
35 private final boolean localSideOpen;
36 private final boolean remoteSideOpen;
37
38 State(boolean localSideOpen, boolean remoteSideOpen) {
39 this.localSideOpen = localSideOpen;
40 this.remoteSideOpen = remoteSideOpen;
41 }
42
43 /**
44 * Indicates whether the local side of this stream is open (i.e. the state is either
45 * {@link State#OPEN} or {@link State#HALF_CLOSED_REMOTE}).
46 */
47 public boolean localSideOpen() {
48 return localSideOpen;
49 }
50
51 /**
52 * Indicates whether the remote side of this stream is open (i.e. the state is either
53 * {@link State#OPEN} or {@link State#HALF_CLOSED_LOCAL}).
54 */
55 public boolean remoteSideOpen() {
56 return remoteSideOpen;
57 }
58 }
59
60 /**
61 * Gets the unique identifier for this stream within the connection.
62 */
63 int id();
64
65 /**
66 * Gets the state of this stream.
67 */
68 State state();
69
70 /**
71 * Opens this stream, making it available via {@link Http2Connection#forEachActiveStream(Http2StreamVisitor)} and
72 * transition state to:
73 * <ul>
74 * <li>{@link State#OPEN} if {@link #state()} is {@link State#IDLE} and {@code halfClosed} is {@code false}.</li>
75 * <li>{@link State#HALF_CLOSED_LOCAL} if {@link #state()} is {@link State#IDLE} and {@code halfClosed}
76 * is {@code true} and the stream is local. In this state, {@link #isHeadersSent()} is {@code true}</li>
77 * <li>{@link State#HALF_CLOSED_REMOTE} if {@link #state()} is {@link State#IDLE} and {@code halfClosed}
78 * is {@code true} and the stream is remote. In this state, {@link #isHeadersReceived()} is {@code true}</li>
79 * <li>{@link State#RESERVED_LOCAL} if {@link #state()} is {@link State#HALF_CLOSED_REMOTE}.</li>
80 * <li>{@link State#RESERVED_REMOTE} if {@link #state()} is {@link State#HALF_CLOSED_LOCAL}.</li>
81 * </ul>
82 */
83 Http2Stream open(boolean halfClosed) throws Http2Exception;
84
85 /**
86 * Closes the stream.
87 */
88 Http2Stream close();
89
90 /**
91 * Closes the local side of this stream. If this makes the stream closed, the child is closed as
92 * well.
93 */
94 Http2Stream closeLocalSide();
95
96 /**
97 * Closes the remote side of this stream. If this makes the stream closed, the child is closed
98 * as well.
99 */
100 Http2Stream closeRemoteSide();
101
102 /**
103 * Indicates whether a {@code RST_STREAM} frame has been sent from the local endpoint for this stream.
104 */
105 boolean isResetSent();
106
107 /**
108 * Sets the flag indicating that a {@code RST_STREAM} frame has been sent from the local endpoint
109 * for this stream. This does not affect the stream state.
110 */
111 Http2Stream resetSent();
112
113 /**
114 * Associates the application-defined data with this stream.
115 * @return The value that was previously associated with {@code key}, or {@code null} if there was none.
116 */
117 <V> V setProperty(Http2Connection.PropertyKey key, V value);
118
119 /**
120 * Returns application-defined data if any was associated with this stream.
121 */
122 <V> V getProperty(Http2Connection.PropertyKey key);
123
124 /**
125 * Returns and removes application-defined data if any was associated with this stream.
126 */
127 <V> V removeProperty(Http2Connection.PropertyKey key);
128
129 /**
130 * Indicates that headers have been sent to the remote endpoint on this stream. The first call to this method would
131 * be for the initial headers (see {@link #isHeadersSent()}} and the second call would indicate the trailers
132 * (see {@link #isTrailersReceived()}).
133 * @param isInformational {@code true} if the headers contain an informational status code (for responses only).
134 */
135 Http2Stream headersSent(boolean isInformational);
136
137 /**
138 * Indicates whether or not headers were sent to the remote endpoint.
139 */
140 boolean isHeadersSent();
141
142 /**
143 * Indicates whether or not trailers were sent to the remote endpoint.
144 */
145 boolean isTrailersSent();
146
147 /**
148 * Indicates that headers have been received. The first call to this method would be for the initial headers
149 * (see {@link #isHeadersReceived()}} and the second call would indicate the trailers
150 * (see {@link #isTrailersReceived()}).
151 * @param isInformational {@code true} if the headers contain an informational status code (for responses only).
152 */
153 Http2Stream headersReceived(boolean isInformational);
154
155 /**
156 * Indicates whether or not the initial headers have been received.
157 */
158 boolean isHeadersReceived();
159
160 /**
161 * Indicates whether or not the trailers have been received.
162 */
163 boolean isTrailersReceived();
164
165 /**
166 * Indicates that a push promise was sent to the remote endpoint.
167 */
168 Http2Stream pushPromiseSent();
169
170 /**
171 * Indicates whether or not a push promise was sent to the remote endpoint.
172 */
173 boolean isPushPromiseSent();
174 }