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  
19  /**
20   * A {@link Http2FlowController} for controlling the flow of outbound {@code DATA} frames to the remote
21   * endpoint.
22   */
23  public interface Http2RemoteFlowController extends Http2FlowController {
24  
25      /**
26       * Writes or queues a payload for transmission to the remote endpoint. There is no
27       * guarantee when the data will be written or whether it will be split into multiple frames
28       * before sending.
29       * <p>
30       * Manually flushing the {@link ChannelHandlerContext} is not required, since the flow
31       * controller will flush as appropriate.
32       *
33       * @param ctx the context from the handler.
34       * @param stream the subject stream. Must not be the connection stream object.
35       * @param payload payload to write subject to flow-control accounting and ordering rules.
36       */
37      void sendFlowControlled(ChannelHandlerContext ctx, Http2Stream stream, FlowControlled payload);
38  
39      /**
40       * Implementations of this interface are used to progressively write chunks of the underlying
41       * payload to the stream. A payload is considered to be fully written if {@link #write} has
42       * been called at least once and it's {@link #size} is now zero.
43       */
44      interface FlowControlled {
45          /**
46           * The size of the payload in terms of bytes applied to the flow-control window.
47           * Some payloads like {@code HEADER} frames have no cost against flow control and would
48           * return 0 for this value even though they produce a non-zero number of bytes on
49           * the wire. Other frames like {@code DATA} frames have both their payload and padding count
50           * against flow-control.
51           */
52          int size();
53  
54          /**
55           * Signal an error and release any retained buffers.
56           * @param cause of the error.
57           */
58          void error(Throwable cause);
59  
60          /**
61           * Writes up to {@code allowedBytes} of the encapsulated payload to the stream. Note that
62           * a value of 0 may be passed which will allow payloads with flow-control size == 0 to be
63           * written. The flow-controller may call this method multiple times with different values until
64           * the payload is fully written.
65           *
66           * @param allowedBytes an upper bound on the number of bytes the payload can write at this time.
67           * @return {@code true} if a flush is required, {@code false} otherwise.
68           */
69          boolean write(int allowedBytes);
70      }
71  }