View Javadoc
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    *   http://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 }