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 io.netty.buffer.ByteBuf;
19  import io.netty.channel.ChannelFuture;
20  import io.netty.channel.ChannelHandlerContext;
21  import io.netty.channel.ChannelPromise;
22  
23  import java.io.Closeable;
24  
25  /**
26   * A writer responsible for marshaling HTTP/2 frames to the channel. All of the write methods in
27   * this interface write to the context, but DO NOT FLUSH. To perform a flush, you must separately
28   * call {@link ChannelHandlerContext#flush()}.
29   */
30  public interface Http2FrameWriter extends Http2DataWriter, Closeable {
31      /**
32       * Configuration specific to {@link Http2FrameWriter}
33       */
34      interface Configuration {
35          /**
36           * Get the {@link Http2HeaderTable} for this {@link Http2FrameWriter}
37           */
38          Http2HeaderTable headerTable();
39  
40          /**
41           * Get the {@link Http2FrameSizePolicy} for this {@link Http2FrameWriter}
42           */
43          Http2FrameSizePolicy frameSizePolicy();
44      }
45  
46      /**
47       * Writes a HEADERS frame to the remote endpoint.
48       *
49       * @param ctx the context to use for writing.
50       * @param streamId the stream for which to send the frame.
51       * @param headers the headers to be sent.
52       * @param padding the amount of padding to be added to the end of the frame
53       * @param endStream indicates if this is the last frame to be sent for the stream.
54       * @param promise the promise for the write.
55       * @return the future for the write.
56       */
57      ChannelFuture writeHeaders(ChannelHandlerContext ctx, int streamId, Http2Headers headers,
58              int padding, boolean endStream, ChannelPromise promise);
59  
60      /**
61       * Writes a HEADERS frame with priority specified to the remote endpoint.
62       *
63       * @param ctx the context to use for writing.
64       * @param streamId the stream for which to send the frame.
65       * @param headers the headers to be sent.
66       * @param streamDependency the stream on which this stream should depend, or 0 if it should
67       *            depend on the connection.
68       * @param weight the weight for this stream.
69       * @param exclusive whether this stream should be the exclusive dependant of its parent.
70       * @param padding the amount of padding to be added to the end of the frame
71       * @param endStream indicates if this is the last frame to be sent for the stream.
72       * @param promise the promise for the write.
73       * @return the future for the write.
74       */
75      ChannelFuture writeHeaders(ChannelHandlerContext ctx, int streamId, Http2Headers headers,
76              int streamDependency, short weight, boolean exclusive, int padding, boolean endStream,
77              ChannelPromise promise);
78  
79      /**
80       * Writes a PRIORITY frame to the remote endpoint.
81       *
82       * @param ctx the context to use for writing.
83       * @param streamId the stream for which to send the frame.
84       * @param streamDependency the stream on which this stream should depend, or 0 if it should
85       *            depend on the connection.
86       * @param weight the weight for this stream.
87       * @param exclusive whether this stream should be the exclusive dependant of its parent.
88       * @param promise the promise for the write.
89       * @return the future for the write.
90       */
91      ChannelFuture writePriority(ChannelHandlerContext ctx, int streamId, int streamDependency,
92              short weight, boolean exclusive, ChannelPromise promise);
93  
94      /**
95       * Writes a RST_STREAM frame to the remote endpoint.
96       *
97       * @param ctx the context to use for writing.
98       * @param streamId the stream for which to send the frame.
99       * @param errorCode the error code indicating the nature of the failure.
100      * @param promise the promise for the write.
101      * @return the future for the write.
102      */
103     ChannelFuture writeRstStream(ChannelHandlerContext ctx, int streamId, long errorCode,
104             ChannelPromise promise);
105 
106     /**
107      * Writes a SETTINGS frame to the remote endpoint.
108      *
109      * @param ctx the context to use for writing.
110      * @param settings the settings to be sent.
111      * @param promise the promise for the write.
112      * @return the future for the write.
113      */
114     ChannelFuture writeSettings(ChannelHandlerContext ctx, Http2Settings settings,
115             ChannelPromise promise);
116 
117     /**
118      * Writes a SETTINGS acknowledgment to the remote endpoint.
119      *
120      * @param ctx the context to use for writing.
121      * @param promise the promise for the write.
122      * @return the future for the write.
123      */
124     ChannelFuture writeSettingsAck(ChannelHandlerContext ctx, ChannelPromise promise);
125 
126     /**
127      * Writes a PING frame to the remote endpoint.
128      *
129      * @param ctx the context to use for writing.
130      * @param ack indicates whether this is an ack of a PING frame previously received from the
131      *            remote endpoint.
132      * @param data the payload of the frame. This will be released by this method.
133      * @param promise the promise for the write.
134      * @return the future for the write.
135      */
136     ChannelFuture writePing(ChannelHandlerContext ctx, boolean ack, ByteBuf data,
137             ChannelPromise promise);
138 
139     /**
140      * Writes a PUSH_PROMISE frame to the remote endpoint.
141      *
142      * @param ctx the context to use for writing.
143      * @param streamId the stream for which to send the frame.
144      * @param promisedStreamId the ID of the promised stream.
145      * @param headers the headers to be sent.
146      * @param padding the amount of padding to be added to the end of the frame
147      * @param promise the promise for the write.
148      * @return the future for the write.
149      */
150     ChannelFuture writePushPromise(ChannelHandlerContext ctx, int streamId, int promisedStreamId,
151             Http2Headers headers, int padding, ChannelPromise promise);
152 
153     /**
154      * Writes a GO_AWAY frame to the remote endpoint.
155      *
156      * @param ctx the context to use for writing.
157      * @param lastStreamId the last known stream of this endpoint.
158      * @param errorCode the error code, if the connection was abnormally terminated.
159      * @param debugData application-defined debug data. This will be released by this method.
160      * @param promise the promise for the write.
161      * @return the future for the write.
162      */
163     ChannelFuture writeGoAway(ChannelHandlerContext ctx, int lastStreamId, long errorCode,
164             ByteBuf debugData, ChannelPromise promise);
165 
166     /**
167      * Writes a WINDOW_UPDATE frame to the remote endpoint.
168      *
169      * @param ctx the context to use for writing.
170      * @param streamId the stream for which to send the frame.
171      * @param windowSizeIncrement the number of bytes by which the local inbound flow control window
172      *            is increasing.
173      * @param promise the promise for the write.
174      * @return the future for the write.
175      */
176     ChannelFuture writeWindowUpdate(ChannelHandlerContext ctx, int streamId,
177             int windowSizeIncrement, ChannelPromise promise);
178 
179     /**
180      * Generic write method for any HTTP/2 frame. This allows writing of non-standard frames.
181      *
182      * @param ctx the context to use for writing.
183      * @param frameType the frame type identifier.
184      * @param streamId the stream for which to send the frame.
185      * @param flags the flags to write for this frame.
186      * @param payload the payload to write for this frame. This will be released by this method.
187      * @param promise the promise for the write.
188      * @return the future for the write.
189      */
190     ChannelFuture writeFrame(ChannelHandlerContext ctx, byte frameType, int streamId,
191             Http2Flags flags, ByteBuf payload, ChannelPromise promise);
192 
193     /**
194      * Get the configuration related elements for this {@link Http2FrameWriter}
195      */
196     Configuration configuration();
197 
198     /**
199      * Closes this writer and frees any allocated resources.
200      */
201     @Override
202     void close();
203 }