1 /*
2 * Copyright 2016 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a 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
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty.channel;
17
18 import io.netty.util.concurrent.EventExecutor;
19 import io.netty.util.concurrent.FutureListener;
20
21 import java.net.ConnectException;
22 import java.net.SocketAddress;
23
24 public interface ChannelOutboundInvoker {
25
26 /**
27 * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation
28 * completes, either because the operation was successful or because of an error.
29 * <p>
30 * This will result in having the
31 * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method
32 * called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
33 * {@link Channel}.
34 */
35 ChannelFuture bind(SocketAddress localAddress);
36
37 /**
38 * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation
39 * completes, either because the operation was successful or because of an error.
40 * <p>
41 * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with
42 * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException}
43 * will be used.
44 * <p>
45 * This will result in having the
46 * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)}
47 * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
48 * {@link Channel}.
49 */
50 ChannelFuture connect(SocketAddress remoteAddress);
51
52 /**
53 * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the
54 * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
55 * an error.
56 * <p>
57 * This will result in having the
58 * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)}
59 * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
60 * {@link Channel}.
61 */
62 ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress);
63
64 /**
65 * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes,
66 * either because the operation was successful or because of an error.
67 * <p>
68 * This will result in having the
69 * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)}
70 * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
71 * {@link Channel}.
72 */
73 ChannelFuture disconnect();
74
75 /**
76 * Request to close the {@link Channel} and notify the {@link ChannelFuture} once the operation completes,
77 * either because the operation was successful or because of
78 * an error.
79 *
80 * After it is closed it is not possible to reuse it again.
81 * <p>
82 * This will result in having the
83 * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)}
84 * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
85 * {@link Channel}.
86 */
87 ChannelFuture close();
88
89 /**
90 * Request to deregister from the previous assigned {@link EventExecutor} and notify the
91 * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
92 * an error.
93 * <p>
94 * This will result in having the
95 * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)}
96 * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
97 * {@link Channel}.
98 *
99 */
100 ChannelFuture deregister();
101
102 /**
103 * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation
104 * completes, either because the operation was successful or because of an error.
105 *
106 * The given {@link ChannelPromise} will be notified.
107 * <p>
108 * This will result in having the
109 * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method
110 * called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
111 * {@link Channel}.
112 */
113 ChannelFuture bind(SocketAddress localAddress, ChannelPromise promise);
114
115 /**
116 * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation
117 * completes, either because the operation was successful or because of an error.
118 *
119 * The given {@link ChannelFuture} will be notified.
120 *
121 * <p>
122 * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with
123 * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException}
124 * will be used.
125 * <p>
126 * This will result in having the
127 * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)}
128 * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
129 * {@link Channel}.
130 */
131 ChannelFuture connect(SocketAddress remoteAddress, ChannelPromise promise);
132
133 /**
134 * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the
135 * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
136 * an error.
137 *
138 * The given {@link ChannelPromise} will be notified and also returned.
139 * <p>
140 * This will result in having the
141 * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)}
142 * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
143 * {@link Channel}.
144 */
145 ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise);
146
147 /**
148 * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes,
149 * either because the operation was successful or because of an error.
150 *
151 * The given {@link ChannelPromise} will be notified.
152 * <p>
153 * This will result in having the
154 * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)}
155 * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
156 * {@link Channel}.
157 */
158 ChannelFuture disconnect(ChannelPromise promise);
159
160 /**
161 * Request to close the {@link Channel} and notify the {@link ChannelFuture} once the operation completes,
162 * either because the operation was successful or because of
163 * an error.
164 *
165 * After it is closed it is not possible to reuse it again.
166 * The given {@link ChannelPromise} will be notified.
167 * <p>
168 * This will result in having the
169 * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)}
170 * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
171 * {@link Channel}.
172 */
173 ChannelFuture close(ChannelPromise promise);
174
175 /**
176 * Request to deregister from the previous assigned {@link EventExecutor} and notify the
177 * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
178 * an error.
179 *
180 * The given {@link ChannelPromise} will be notified.
181 * <p>
182 * This will result in having the
183 * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)}
184 * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
185 * {@link Channel}.
186 */
187 ChannelFuture deregister(ChannelPromise promise);
188
189 /**
190 * Request to Read data from the {@link Channel} into the first inbound buffer, triggers an
191 * {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object)} event if data was
192 * read, and triggers a
193 * {@link ChannelInboundHandler#channelReadComplete(ChannelHandlerContext) channelReadComplete} event so the
194 * handler can decide to continue reading. If there's a pending read operation already, this method does nothing.
195 * <p>
196 * This will result in having the
197 * {@link ChannelOutboundHandler#read(ChannelHandlerContext)}
198 * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the
199 * {@link Channel}.
200 */
201 ChannelOutboundInvoker read();
202
203 /**
204 * Request to write a message via this {@link ChannelHandlerContext} through the {@link ChannelPipeline}.
205 * This method will not request to actual flush, so be sure to call {@link #flush()}
206 * once you want to request to flush all pending data to the actual transport.
207 */
208 ChannelFuture write(Object msg);
209
210 /**
211 * Request to write a message via this {@link ChannelHandlerContext} through the {@link ChannelPipeline}.
212 * This method will not request to actual flush, so be sure to call {@link #flush()}
213 * once you want to request to flush all pending data to the actual transport.
214 */
215 ChannelFuture write(Object msg, ChannelPromise promise);
216
217 /**
218 * Request to flush all pending messages via this ChannelOutboundInvoker.
219 */
220 ChannelOutboundInvoker flush();
221
222 /**
223 * Shortcut for call {@link #write(Object, ChannelPromise)} and {@link #flush()}.
224 */
225 ChannelFuture writeAndFlush(Object msg, ChannelPromise promise);
226
227 /**
228 * Shortcut for call {@link #write(Object)} and {@link #flush()}.
229 */
230 ChannelFuture writeAndFlush(Object msg);
231
232 /**
233 * Return a new {@link ChannelPromise}.
234 */
235 ChannelPromise newPromise();
236
237 /**
238 * Return an new {@link ChannelProgressivePromise}
239 */
240 ChannelProgressivePromise newProgressivePromise();
241
242 /**
243 * Create a new {@link ChannelFuture} which is marked as succeeded already. So {@link ChannelFuture#isSuccess()}
244 * will return {@code true}. All {@link FutureListener} added to it will be notified directly. Also
245 * every call of blocking methods will just return without blocking.
246 */
247 ChannelFuture newSucceededFuture();
248
249 /**
250 * Create a new {@link ChannelFuture} which is marked as failed already. So {@link ChannelFuture#isSuccess()}
251 * will return {@code false}. All {@link FutureListener} added to it will be notified directly. Also
252 * every call of blocking methods will just return without blocking.
253 */
254 ChannelFuture newFailedFuture(Throwable cause);
255
256 /**
257 * Return a special ChannelPromise which can be reused for different operations.
258 * <p>
259 * It's only supported to use
260 * it for {@link ChannelOutboundInvoker#write(Object, ChannelPromise)}.
261 * </p>
262 * <p>
263 * Be aware that the returned {@link ChannelPromise} will not support most operations and should only be used
264 * if you want to save an object allocation for every write operation. You will not be able to detect if the
265 * operation was complete, only if it failed as the implementation will call
266 * {@link ChannelPipeline#fireExceptionCaught(Throwable)} in this case.
267 * </p>
268 * <strong>Be aware this is an expert feature and should be used with care!</strong>
269 */
270 ChannelPromise voidPromise();
271 }