View Javadoc
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    * http://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  import java.util.Collection;
19  
20  /**
21   * A single stream within an HTTP2 connection. Streams are compared to each other by priority.
22   */
23  public interface Http2Stream {
24  
25      /**
26       * The allowed states of an HTTP2 stream.
27       */
28      enum State {
29          IDLE,
30          RESERVED_LOCAL,
31          RESERVED_REMOTE,
32          OPEN,
33          HALF_CLOSED_LOCAL,
34          HALF_CLOSED_REMOTE,
35          CLOSED
36      }
37  
38      /**
39       * Gets the unique identifier for this stream within the connection.
40       */
41      int id();
42  
43      /**
44       * Gets the state of this stream.
45       */
46      State state();
47  
48      /**
49       * Add this stream to {@link Http2Connection#activeStreams()} and transition state to:
50       * <ul>
51       * <li>{@link State#OPEN} if {@link #state()} is {@link State#IDLE} and {@code halfClosed} is {@code false}.</li>
52       * <li>{@link State#HALF_CLOSED_LOCAL} if {@link #state()} is {@link State#IDLE} and {@code halfClosed}
53       * is {@code true} and the stream is local.</li>
54       * <li>{@link State#HALF_CLOSED_REMOTE} if {@link #state()} is {@link State#IDLE} and {@code halfClosed}
55       * is {@code true} and the stream is remote.</li>
56       * <li>{@link State#RESERVED_LOCAL} if {@link #state()} is {@link State#HALF_CLOSED_REMOTE}.</li>
57       * <li>{@link State#RESERVED_REMOTE} if {@link #state()} is {@link State#HALF_CLOSED_LOCAL}.</li>
58       * </ul>
59       */
60      Http2Stream open(boolean halfClosed) throws Http2Exception;
61  
62      /**
63       * Closes the stream.
64       */
65      Http2Stream close();
66  
67      /**
68       * Closes the local side of this stream. If this makes the stream closed, the child is closed as
69       * well.
70       */
71      Http2Stream closeLocalSide();
72  
73      /**
74       * Closes the remote side of this stream. If this makes the stream closed, the child is closed
75       * as well.
76       */
77      Http2Stream closeRemoteSide();
78  
79      /**
80       * Indicates whether a {@code RST_STREAM} frame has been sent from the local endpoint for this stream.
81       */
82      boolean isResetSent();
83  
84      /**
85       * Sets the flag indicating that a {@code RST_STREAM} frame has been sent from the local endpoint
86       * for this stream. This does not affect the stream state.
87       */
88      Http2Stream resetSent();
89  
90      /**
91       * Indicates whether the remote side of this stream is open (i.e. the state is either
92       * {@link State#OPEN} or {@link State#HALF_CLOSED_LOCAL}).
93       */
94      boolean remoteSideOpen();
95  
96      /**
97       * Indicates whether the local side of this stream is open (i.e. the state is either
98       * {@link State#OPEN} or {@link State#HALF_CLOSED_REMOTE}).
99       */
100     boolean localSideOpen();
101 
102     /**
103      * Associates the application-defined data with this stream.
104      * @return The value that was previously associated with {@code key}, or {@code null} if there was none.
105      */
106     Object setProperty(Object key, Object value);
107 
108     /**
109      * Returns application-defined data if any was associated with this stream.
110      */
111     <V> V getProperty(Object key);
112 
113     /**
114      * Returns and removes application-defined data if any was associated with this stream.
115      */
116     <V> V removeProperty(Object key);
117 
118     /**
119      * Updates an priority for this stream. Calling this method may affect the straucture of the
120      * priority tree.
121      *
122      * @param parentStreamId the parent stream that given stream should depend on. May be {@code 0},
123      *            if the stream has no dependencies and should be an immediate child of the
124      *            connection.
125      * @param weight the weight to be assigned to this stream relative to its parent. This value
126      *            must be between 1 and 256 (inclusive)
127      * @param exclusive indicates that the stream should be the exclusive dependent on its parent.
128      *            This only applies if the stream has a parent.
129      * @return this stream.
130      */
131     Http2Stream setPriority(int parentStreamId, short weight, boolean exclusive) throws Http2Exception;
132 
133     /**
134      * Indicates whether or not this stream is the root node of the priority tree.
135      */
136     boolean isRoot();
137 
138     /**
139      * Indicates whether or not this is a leaf node (i.e. {@link #numChildren} is 0) of the priority tree.
140      */
141     boolean isLeaf();
142 
143     /**
144      * Returns weight assigned to the dependency with the parent. The weight will be a value
145      * between 1 and 256.
146      */
147     short weight();
148 
149     /**
150      * The total of the weights of all children of this stream.
151      */
152     int totalChildWeights();
153 
154     /**
155      * The parent (i.e. the node in the priority tree on which this node depends), or {@code null}
156      * if this is the root node (i.e. the connection, itself).
157      */
158     Http2Stream parent();
159 
160     /**
161      * Indicates whether or not this stream is a descendant in the priority tree from the given stream.
162      */
163     boolean isDescendantOf(Http2Stream stream);
164 
165     /**
166      * Returns the number of child streams directly dependent on this stream.
167      */
168     int numChildren();
169 
170     /**
171      * Indicates whether the given stream is a direct child of this stream.
172      */
173     boolean hasChild(int streamId);
174 
175     /**
176      * Attempts to find a child of this stream with the given ID. If not found, returns
177      * {@code null}.
178      */
179     Http2Stream child(int streamId);
180 
181     /**
182      * Gets all streams that are direct dependents on this stream.
183      */
184     Collection<? extends Http2Stream> children();
185 }