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  package io.netty.handler.codec.http2;
16  
17  import io.netty.channel.ChannelHandlerContext;
18  import io.netty.util.internal.UnstableApi;
19  
20  /**
21   * Base interface for all HTTP/2 flow controllers.
22   */
23  @UnstableApi
24  public interface Http2FlowController {
25      /**
26       * Set the {@link ChannelHandlerContext} for which to apply flow control on.
27       * <p>
28       * This <strong>must</strong> be called to properly initialize the {@link Http2FlowController}.
29       * Not calling this is considered a programming error.
30       * @param ctx The {@link ChannelHandlerContext} for which to apply flow control on.
31       * @throws Http2Exception if any protocol-related error occurred.
32       */
33      void channelHandlerContext(ChannelHandlerContext ctx) throws Http2Exception;
34  
35      /**
36       * Sets the connection-wide initial flow control window and updates all stream windows (but not the connection
37       * stream window) by the delta.
38       * <p>
39       * Represents the value for
40       * <a href="https://tools.ietf.org/html/rfc7540#section-6.5.2">SETTINGS_INITIAL_WINDOW_SIZE</a>. This method should
41       * only be called by Netty (not users) as a result of a receiving a {@code SETTINGS} frame.
42       *
43       * @param newWindowSize the new initial window size.
44       * @throws Http2Exception thrown if any protocol-related error occurred.
45       */
46      void initialWindowSize(int newWindowSize) throws Http2Exception;
47  
48      /**
49       * Gets the connection-wide initial flow control window size that is used as the basis for new stream flow
50       * control windows.
51       * <p>
52       * Represents the value for
53       * <a href="https://tools.ietf.org/html/rfc7540#section-6.5.2">SETTINGS_INITIAL_WINDOW_SIZE</a>. The initial value
54       * returned by this method must be {@link Http2CodecUtil#DEFAULT_WINDOW_SIZE}.
55       */
56      int initialWindowSize();
57  
58      /**
59       * Get the portion of the flow control window for the given stream that is currently available for sending/receiving
60       * frames which are subject to flow control. This quantity is measured in number of bytes.
61       */
62      int windowSize(Http2Stream stream);
63  
64      /**
65       * Increments the size of the stream's flow control window by the given delta.
66       * <p>
67       * In the case of a {@link Http2RemoteFlowController} this is called upon receipt of a
68       * {@code WINDOW_UPDATE} frame from the remote endpoint to mirror the changes to the window
69       * size.
70       * <p>
71       * For a {@link Http2LocalFlowController} this can be called to request the expansion of the
72       * window size published by this endpoint. It is up to the implementation, however, as to when a
73       * {@code WINDOW_UPDATE} is actually sent.
74       *
75       * @param stream The subject stream. Use {@link Http2Connection#connectionStream()} for
76       *            requesting the size of the connection window.
77       * @param delta the change in size of the flow control window.
78       * @throws Http2Exception thrown if a protocol-related error occurred.
79       */
80      void incrementWindowSize(Http2Stream stream, int delta) throws Http2Exception;
81  }