View Javadoc
1   /*
2    * Copyright 2012 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.buffer.ByteBuf;
19  import io.netty.buffer.ByteBufAllocator;
20  import io.netty.channel.socket.DatagramChannel;
21  import io.netty.channel.socket.DatagramPacket;
22  import io.netty.channel.socket.ServerSocketChannel;
23  import io.netty.channel.socket.SocketChannel;
24  import io.netty.util.AttributeMap;
25  import io.netty.util.concurrent.EventExecutor;
26  import io.netty.util.concurrent.FutureListener;
27  
28  import java.net.ConnectException;
29  import java.net.InetSocketAddress;
30  import java.net.SocketAddress;
31  
32  
33  /**
34   * A nexus to a network socket or a component which is capable of I/O
35   * operations such as read, write, connect, and bind.
36   * <p>
37   * A channel provides a user:
38   * <ul>
39   * <li>the current state of the channel (e.g. is it open? is it connected?),</li>
40   * <li>the {@linkplain ChannelConfig configuration parameters} of the channel (e.g. receive buffer size),</li>
41   * <li>the I/O operations that the channel supports (e.g. read, write, connect, and bind), and</li>
42   * <li>the {@link ChannelPipeline} which handles all I/O events and requests
43   *     associated with the channel.</li>
44   * </ul>
45   *
46   * <h3>All I/O operations are asynchronous.</h3>
47   * <p>
48   * All I/O operations in Netty are asynchronous.  It means any I/O calls will
49   * return immediately with no guarantee that the requested I/O operation has
50   * been completed at the end of the call.  Instead, you will be returned with
51   * a {@link ChannelFuture} instance which will notify you when the requested I/O
52   * operation has succeeded, failed, or canceled.
53   *
54   * <h3>Channels are hierarchical</h3>
55   * <p>
56   * A {@link Channel} can have a {@linkplain #parent() parent} depending on
57   * how it was created.  For instance, a {@link SocketChannel}, that was accepted
58   * by {@link ServerSocketChannel}, will return the {@link ServerSocketChannel}
59   * as its parent on {@link #parent()}.
60   * <p>
61   * The semantics of the hierarchical structure depends on the transport
62   * implementation where the {@link Channel} belongs to.  For example, you could
63   * write a new {@link Channel} implementation that creates the sub-channels that
64   * share one socket connection, as <a href="http://beepcore.org/">BEEP</a> and
65   * <a href="http://en.wikipedia.org/wiki/Secure_Shell">SSH</a> do.
66   *
67   * <h3>Downcast to access transport-specific operations</h3>
68   * <p>
69   * Some transports exposes additional operations that is specific to the
70   * transport.  Down-cast the {@link Channel} to sub-type to invoke such
71   * operations.  For example, with the old I/O datagram transport, multicast
72   * join / leave operations are provided by {@link DatagramChannel}.
73   *
74   * <h3>Release resources</h3>
75   * <p>
76   * It is important to call {@link #close()} or {@link #close(ChannelPromise)} to release all
77   * resources once you are done with the {@link Channel}. This ensures all resources are
78   * released in a proper way, i.e. filehandles.
79   */
80  public interface Channel extends AttributeMap, Comparable<Channel> {
81  
82      /**
83       * Return the {@link EventLoop} this {@link Channel} was registered to.
84       */
85      EventLoop eventLoop();
86  
87      /**
88       * Returns the parent of this channel.
89       *
90       * @return the parent channel.
91       *         {@code null} if this channel does not have a parent channel.
92       */
93      Channel parent();
94  
95      /**
96       * Returns the configuration of this channel.
97       */
98      ChannelConfig config();
99  
100     /**
101      * Returns {@code true} if the {@link Channel} is open and may get active later
102      */
103     boolean isOpen();
104 
105     /**
106      * Returns {@code true} if the {@link Channel} is registered with an {@link EventLoop}.
107      */
108     boolean isRegistered();
109 
110     /**
111      * Return {@code true} if the {@link Channel} is active and so connected.
112      */
113     boolean isActive();
114 
115     /**
116      * Return the {@link ChannelMetadata} of the {@link Channel} which describe the nature of the {@link Channel}.
117      */
118     ChannelMetadata metadata();
119 
120     /**
121      * Returns the local address where this channel is bound to.  The returned
122      * {@link SocketAddress} is supposed to be down-cast into more concrete
123      * type such as {@link InetSocketAddress} to retrieve the detailed
124      * information.
125      *
126      * @return the local address of this channel.
127      *         {@code null} if this channel is not bound.
128      */
129     SocketAddress localAddress();
130 
131     /**
132      * Returns the remote address where this channel is connected to.  The
133      * returned {@link SocketAddress} is supposed to be down-cast into more
134      * concrete type such as {@link InetSocketAddress} to retrieve the detailed
135      * information.
136      *
137      * @return the remote address of this channel.
138      *         {@code null} if this channel is not connected.
139      *         If this channel is not connected but it can receive messages
140      *         from arbitrary remote addresses (e.g. {@link DatagramChannel},
141      *         use {@link DatagramPacket#recipient()} to determine
142      *         the origination of the received message as this method will
143      *         return {@code null}.
144      */
145     SocketAddress remoteAddress();
146 
147     /**
148      * Returns the {@link ChannelFuture} which will be notified when this
149      * channel is closed.  This method always returns the same future instance.
150      */
151     ChannelFuture closeFuture();
152 
153     /**
154      * Returns {@code true} if and only if the I/O thread will perform the
155      * requested write operation immediately.  Any write requests made when
156      * this method returns {@code false} are queued until the I/O thread is
157      * ready to process the queued write requests.
158      */
159     boolean isWritable();
160 
161     /**
162      * Returns an <em>internal-use-only</em> object that provides unsafe operations.
163      */
164     Unsafe unsafe();
165 
166     /**
167      * Return the assigned {@link ChannelPipeline}.
168      */
169     ChannelPipeline pipeline();
170 
171     /**
172      * Return the assigned {@link ByteBufAllocator} which will be used to allocate {@link ByteBuf}s.
173      */
174     ByteBufAllocator alloc();
175 
176     /**
177      * Return a new {@link ChannelPromise}.
178      */
179     ChannelPromise newPromise();
180 
181     /**
182      * Return an new {@link ChannelProgressivePromise}.
183      */
184     ChannelProgressivePromise newProgressivePromise();
185 
186     /**
187      * Create a new {@link ChannelFuture} which is marked as succeeded already. So {@link ChannelFuture#isSuccess()}
188      * will return {@code true}. All {@link FutureListener} added to it will be notified directly. Also
189      * every call of blocking methods will just return without blocking.
190      */
191     ChannelFuture newSucceededFuture();
192 
193     /**
194      * Create a new {@link ChannelFuture} which is marked as failed already. So {@link ChannelFuture#isSuccess()}
195      * will return {@code false}. All {@link FutureListener} added to it will be notified directly. Also
196      * every call of blocking methods will just return without blocking.
197      */
198     ChannelFuture newFailedFuture(Throwable cause);
199 
200     /**
201      * Return a special ChannelPromise which can be reused for different operations.
202      * <p>
203      * It's only supported to use
204      * it for {@link Channel#write(Object, ChannelPromise)}.
205      * </p>
206      * <p>
207      * Be aware that the returned {@link ChannelPromise} will not support most operations and should only be used
208      * if you want to save an object allocation for every write operation. You will not be able to detect if the
209      * operation  was complete, only if it failed as the implementation will call
210      * {@link ChannelPipeline#fireExceptionCaught(Throwable)} in this case.
211      * </p>
212      * <strong>Be aware this is an expert feature and should be used with care!</strong>
213      */
214     ChannelPromise voidPromise();
215 
216     /**
217      * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation
218      * completes, either because the operation was successful or because of an error.
219      * <p>
220      * This will result in having the
221      * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method
222      * called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
223      * {@link Channel}.
224      */
225     ChannelFuture bind(SocketAddress localAddress);
226 
227     /**
228      * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation
229      * completes, either because the operation was successful or because of an error.
230      * <p>
231      * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with
232      * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException}
233      * will be used.
234      * <p>
235      * This will result in having the
236      * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)}
237      * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
238      * {@link Channel}.
239      */
240     ChannelFuture connect(SocketAddress remoteAddress);
241 
242     /**
243      * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the
244      * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
245      * an error.
246      * <p>
247      * This will result in having the
248      * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)}
249      * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
250      * {@link Channel}.
251      */
252     ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress);
253 
254     /**
255      * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes,
256      * either because the operation was successful or because of an error.
257      * <p>
258      * This will result in having the
259      * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)}
260      * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
261      * {@link Channel}.
262      */
263     ChannelFuture disconnect();
264 
265     /**
266      * Request to close this {@link Channel} and notify the {@link ChannelFuture} once the operation completes,
267      * either because the operation was successful or because of
268      * an error.
269      *
270      * After it is closed it is not possible to reuse it again.
271      * <p>
272      * This will result in having the
273      * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)}
274      * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
275      * {@link Channel}.
276      */
277     ChannelFuture close();
278 
279     /**
280      * Request to deregister this {@link Channel} from the previous assigned {@link EventExecutor} and notify the
281      * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
282      * an error.
283      * <p>
284      * This will result in having the
285      * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)}
286      * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
287      * {@link Channel}.
288      *
289      */
290     ChannelFuture deregister();
291 
292     /**
293      * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation
294      * completes, either because the operation was successful or because of an error.
295      *
296      * The given {@link ChannelPromise} will be notified.
297      * <p>
298      * This will result in having the
299      * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method
300      * called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
301      * {@link Channel}.
302      */
303     ChannelFuture bind(SocketAddress localAddress, ChannelPromise promise);
304 
305     /**
306      * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation
307      * completes, either because the operation was successful or because of an error.
308      *
309      * The given {@link ChannelFuture} will be notified.
310      *
311      * <p>
312      * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with
313      * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException}
314      * will be used.
315      * <p>
316      * This will result in having the
317      * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)}
318      * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
319      * {@link Channel}.
320      */
321     ChannelFuture connect(SocketAddress remoteAddress, ChannelPromise promise);
322 
323     /**
324      * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the
325      * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
326      * an error.
327      *
328      * The given {@link ChannelPromise} will be notified and also returned.
329      * <p>
330      * This will result in having the
331      * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)}
332      * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
333      * {@link Channel}.
334      */
335     ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise);
336 
337     /**
338      * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes,
339      * either because the operation was successful or because of an error.
340      *
341      * The given {@link ChannelPromise} will be notified.
342      * <p>
343      * This will result in having the
344      * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)}
345      * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
346      * {@link Channel}.
347      */
348     ChannelFuture disconnect(ChannelPromise promise);
349 
350     /**
351      * Request to close this {@link Channel} and notify the {@link ChannelFuture} once the operation completes,
352      * either because the operation was successful or because of
353      * an error.
354      *
355      * After it is closed it is not possible to reuse it again.
356      * The given {@link ChannelPromise} will be notified.
357      * <p>
358      * This will result in having the
359      * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)}
360      * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
361      * {@link Channel}.
362      */
363     ChannelFuture close(ChannelPromise promise);
364 
365     /**
366      * Request to deregister this {@link Channel} from the previous assigned {@link EventExecutor} and notify the
367      * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
368      * an error.
369      *
370      * The given {@link ChannelPromise} will be notified.
371      * <p>
372      * This will result in having the
373      * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)}
374      * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
375      * {@link Channel}.
376      */
377     ChannelFuture deregister(ChannelPromise promise);
378 
379     /**
380      * Request to Read data from the {@link Channel} into the first inbound buffer, triggers an
381      * {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object)} event if data was
382      * read, and triggers a
383      * {@link ChannelInboundHandler#channelReadComplete(ChannelHandlerContext) channelReadComplete} event so the
384      * handler can decide to continue reading.  If there's a pending read operation already, this method does nothing.
385      * <p>
386      * This will result in having the
387      * {@link ChannelOutboundHandler#read(ChannelHandlerContext)}
388      * method called of the next {@link ChannelOutboundHandler} contained in the  {@link ChannelPipeline} of the
389      * {@link Channel}.
390      */
391     Channel read();
392 
393     /**
394      * Request to write a message via this {@link Channel} through the {@link ChannelPipeline}.
395      * This method will not request to actual flush, so be sure to call {@link #flush()}
396      * once you want to request to flush all pending data to the actual transport.
397      */
398     ChannelFuture write(Object msg);
399 
400     /**
401      * Request to write a message via this {@link Channel} through the {@link ChannelPipeline}.
402      * This method will not request to actual flush, so be sure to call {@link #flush()}
403      * once you want to request to flush all pending data to the actual transport.
404      */
405     ChannelFuture write(Object msg, ChannelPromise promise);
406 
407     /**
408      * Request to flush all pending messages.
409      */
410     Channel flush();
411 
412     /**
413      * Shortcut for call {@link #write(Object, ChannelPromise)} and {@link #flush()}.
414      */
415     ChannelFuture writeAndFlush(Object msg, ChannelPromise promise);
416 
417     /**
418      * Shortcut for call {@link #write(Object)} and {@link #flush()}.
419      */
420     ChannelFuture writeAndFlush(Object msg);
421 
422     /**
423      * <em>Unsafe</em> operations that should <em>never</em> be called from user-code. These methods
424      * are only provided to implement the actual transport, and must be invoked from an I/O thread except for the
425      * following methods:
426      * <ul>
427      *   <li>{@link #localAddress()}</li>
428      *   <li>{@link #remoteAddress()}</li>
429      *   <li>{@link #closeForcibly()}</li>
430      *   <li>{@link #register(EventLoop, ChannelPromise)}</li>
431      *   <li>{@link #voidPromise()}</li>
432      * </ul>
433      */
434     interface Unsafe {
435         /**
436          * Return the {@link SocketAddress} to which is bound local or
437          * {@code null} if none.
438          */
439         SocketAddress localAddress();
440 
441         /**
442          * Return the {@link SocketAddress} to which is bound remote or
443          * {@code null} if none is bound yet.
444          */
445         SocketAddress remoteAddress();
446 
447         /**
448          * Register the {@link Channel} of the {@link ChannelPromise} with the {@link EventLoop} and notify
449          * the {@link ChannelFuture} once the registration was complete.
450          */
451         void register(EventLoop eventLoop, ChannelPromise promise);
452 
453         /**
454          * Bind the {@link SocketAddress} to the {@link Channel} of the {@link ChannelPromise} and notify
455          * it once its done.
456          */
457         void bind(SocketAddress localAddress, ChannelPromise promise);
458 
459         /**
460          * Connect the {@link Channel} of the given {@link ChannelFuture} with the given remote {@link SocketAddress}.
461          * If a specific local {@link SocketAddress} should be used it need to be given as argument. Otherwise just
462          * pass {@code null} to it.
463          *
464          * The {@link ChannelPromise} will get notified once the connect operation was complete.
465          */
466         void connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise);
467 
468         /**
469          * Disconnect the {@link Channel} of the {@link ChannelFuture} and notify the {@link ChannelPromise} once the
470          * operation was complete.
471          */
472         void disconnect(ChannelPromise promise);
473 
474         /**
475          * Close the {@link Channel} of the {@link ChannelPromise} and notify the {@link ChannelPromise} once the
476          * operation was complete.
477          */
478         void close(ChannelPromise promise);
479 
480         /**
481          * Closes the {@link Channel} immediately without firing any events.  Probably only useful
482          * when registration attempt failed.
483          */
484         void closeForcibly();
485 
486         /**
487          * Deregister the {@link Channel} of the {@link ChannelPromise} from {@link EventLoop} and notify the
488          * {@link ChannelPromise} once the operation was complete.
489          */
490         void deregister(ChannelPromise promise);
491 
492         /**
493          * Schedules a read operation that fills the inbound buffer of the first {@link ChannelInboundHandler} in the
494          * {@link ChannelPipeline}.  If there's already a pending read operation, this method does nothing.
495          */
496         void beginRead();
497 
498         /**
499          * Schedules a write operation.
500          */
501         void write(Object msg, ChannelPromise promise);
502 
503         /**
504          * Flush out all write operations scheduled via {@link #write(Object, ChannelPromise)}.
505          */
506         void flush();
507 
508         /**
509          * Return a special ChannelPromise which can be reused and passed to the operations in {@link Unsafe}.
510          * It will never be notified of a success or error and so is only a placeholder for operations
511          * that take a {@link ChannelPromise} as argument but for which you not want to get notified.
512          */
513         ChannelPromise voidPromise();
514 
515         /**
516          * Returns the {@link ChannelOutboundBuffer} of the {@link Channel} where the pending write requests are stored.
517          */
518         ChannelOutboundBuffer outboundBuffer();
519     }
520 }