查看本类的 API文档回源码主页即时通讯网 - 即时通讯开发者社区!
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  package io.netty.handler.codec.http2;
16  
17  import io.netty.buffer.ByteBuf;
18  import io.netty.channel.ChannelFuture;
19  import io.netty.channel.ChannelHandlerContext;
20  import io.netty.channel.ChannelPromise;
21  import io.netty.util.internal.UnstableApi;
22  
23  /**
24   * Manager for the life cycle of the HTTP/2 connection. Handles graceful shutdown of the channel,
25   * closing only after all of the streams have closed.
26   */
27  @UnstableApi
28  public interface Http2LifecycleManager {
29  
30      /**
31       * Closes the local side of the {@code stream}. Depending on the {@code stream} state this may result in
32       * {@code stream} being closed. See {@link #closeStream(Http2Stream, ChannelFuture)}.
33       * @param stream the stream to be half closed.
34       * @param future See {@link #closeStream(Http2Stream, ChannelFuture)}.
35       */
36      void closeStreamLocal(Http2Stream stream, ChannelFuture future);
37  
38      /**
39       * Closes the remote side of the {@code stream}. Depending on the {@code stream} state this may result in
40       * {@code stream} being closed. See {@link #closeStream(Http2Stream, ChannelFuture)}.
41       * @param stream the stream to be half closed.
42       * @param future See {@link #closeStream(Http2Stream, ChannelFuture)}.
43       */
44      void closeStreamRemote(Http2Stream stream, ChannelFuture future);
45  
46      /**
47       * Closes and deactivates the given {@code stream}. A listener is also attached to {@code future} and upon
48       * completion the underlying channel will be closed if {@link Http2Connection#numActiveStreams()} is 0.
49       * @param stream the stream to be closed and deactivated.
50       * @param future when completed if {@link Http2Connection#numActiveStreams()} is 0 then the underlying channel
51       * will be closed.
52       */
53      void closeStream(Http2Stream stream, ChannelFuture future);
54  
55      /**
56       * Ensure the stream identified by {@code streamId} is reset. If our local state does not indicate the stream has
57       * been reset yet then a {@code RST_STREAM} will be sent to the peer. If our local state indicates the stream
58       * has already been reset then the return status will indicate success without sending anything to the peer.
59       * @param ctx The context used for communication and buffer allocation if necessary.
60       * @param streamId The identifier of the stream to reset.
61       * @param errorCode Justification as to why this stream is being reset. See {@link Http2Error}.
62       * @param promise Used to indicate the return status of this operation.
63       * @return Will be considered successful when the connection and stream state has been updated, and a
64       * {@code RST_STREAM} frame has been sent to the peer. If the stream state has already been updated and a
65       * {@code RST_STREAM} frame has been sent then the return status may indicate success immediately.
66       */
67      ChannelFuture resetStream(ChannelHandlerContext ctx, int streamId, long errorCode,
68              ChannelPromise promise);
69  
70      /**
71       * Prevents the peer from creating streams and close the connection if {@code errorCode} is not
72       * {@link Http2Error#NO_ERROR}. After this call the peer is not allowed to create any new streams and the local
73       * endpoint will be limited to creating streams with {@code stream identifier <= lastStreamId}. This may result in
74       * sending a {@code GO_AWAY} frame (assuming we have not already sent one with
75       * {@code Last-Stream-ID <= lastStreamId}), or may just return success if a {@code GO_AWAY} has previously been
76       * sent.
77       * @param ctx The context used for communication and buffer allocation if necessary.
78       * @param lastStreamId The last stream that the local endpoint is claiming it will accept.
79       * @param errorCode The rational as to why the connection is being closed. See {@link Http2Error}.
80       * @param debugData For diagnostic purposes (carries no semantic value).
81       * @param promise Used to indicate the return status of this operation.
82       * @return Will be considered successful when the connection and stream state has been updated, and a
83       * {@code GO_AWAY} frame has been sent to the peer. If the stream state has already been updated and a
84       * {@code GO_AWAY} frame has been sent then the return status may indicate success immediately.
85       */
86      ChannelFuture goAway(ChannelHandlerContext ctx, int lastStreamId, long errorCode,
87              ByteBuf debugData, ChannelPromise promise);
88  
89      /**
90       * Processes the given error.
91       *
92       * @param ctx The context used for communication and buffer allocation if necessary.
93       * @param outbound {@code true} if the error was caused by an outbound operation and so the corresponding
94       * {@link ChannelPromise} was failed as well.
95       * @param cause the error.
96       */
97      void onError(ChannelHandlerContext ctx, boolean outbound, Throwable cause);
98  }