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    *   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.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  
26  import java.net.InetSocketAddress;
27  import java.net.SocketAddress;
28  
29  
30  /**
31   * A nexus to a network socket or a component which is capable of I/O
32   * operations such as read, write, connect, and bind.
33   * <p>
34   * A channel provides a user:
35   * <ul>
36   * <li>the current state of the channel (e.g. is it open? is it connected?),</li>
37   * <li>the {@linkplain ChannelConfig configuration parameters} of the channel (e.g. receive buffer size),</li>
38   * <li>the I/O operations that the channel supports (e.g. read, write, connect, and bind), and</li>
39   * <li>the {@link ChannelPipeline} which handles all I/O events and requests
40   *     associated with the channel.</li>
41   * </ul>
42   *
43   * <h3>All I/O operations are asynchronous.</h3>
44   * <p>
45   * All I/O operations in Netty are asynchronous.  It means any I/O calls will
46   * return immediately with no guarantee that the requested I/O operation has
47   * been completed at the end of the call.  Instead, you will be returned with
48   * a {@link ChannelFuture} instance which will notify you when the requested I/O
49   * operation has succeeded, failed, or canceled.
50   *
51   * <h3>Channels are hierarchical</h3>
52   * <p>
53   * A {@link Channel} can have a {@linkplain #parent() parent} depending on
54   * how it was created.  For instance, a {@link SocketChannel}, that was accepted
55   * by {@link ServerSocketChannel}, will return the {@link ServerSocketChannel}
56   * as its parent on {@link #parent()}.
57   * <p>
58   * The semantics of the hierarchical structure depends on the transport
59   * implementation where the {@link Channel} belongs to.  For example, you could
60   * write a new {@link Channel} implementation that creates the sub-channels that
61   * share one socket connection, as <a href="http://beepcore.org/">BEEP</a> and
62   * <a href="https://en.wikipedia.org/wiki/Secure_Shell">SSH</a> do.
63   *
64   * <h3>Downcast to access transport-specific operations</h3>
65   * <p>
66   * Some transports exposes additional operations that is specific to the
67   * transport.  Down-cast the {@link Channel} to sub-type to invoke such
68   * operations.  For example, with the old I/O datagram transport, multicast
69   * join / leave operations are provided by {@link DatagramChannel}.
70   *
71   * <h3>Release resources</h3>
72   * <p>
73   * It is important to call {@link #close()} or {@link #close(ChannelPromise)} to release all
74   * resources once you are done with the {@link Channel}. This ensures all resources are
75   * released in a proper way, i.e. filehandles.
76   */
77  public interface Channel extends AttributeMap, ChannelOutboundInvoker, Comparable<Channel> {
78  
79      /**
80       * Returns the globally unique identifier of this {@link Channel}.
81       */
82      ChannelId id();
83  
84      /**
85       * Return the {@link EventLoop} this {@link Channel} was registered to.
86       */
87      EventLoop eventLoop();
88  
89      /**
90       * Returns the parent of this channel.
91       *
92       * @return the parent channel.
93       *         {@code null} if this channel does not have a parent channel.
94       */
95      Channel parent();
96  
97      /**
98       * Returns the configuration of this channel.
99       */
100     ChannelConfig config();
101 
102     /**
103      * Returns {@code true} if the {@link Channel} is open and may get active later
104      */
105     boolean isOpen();
106 
107     /**
108      * Returns {@code true} if the {@link Channel} is registered with an {@link EventLoop}.
109      */
110     boolean isRegistered();
111 
112     /**
113      * Return {@code true} if the {@link Channel} is active and so connected.
114      */
115     boolean isActive();
116 
117     /**
118      * Return the {@link ChannelMetadata} of the {@link Channel} which describe the nature of the {@link Channel}.
119      */
120     ChannelMetadata metadata();
121 
122     /**
123      * Returns the local address where this channel is bound to.  The returned
124      * {@link SocketAddress} is supposed to be down-cast into more concrete
125      * type such as {@link InetSocketAddress} to retrieve the detailed
126      * information.
127      *
128      * @return the local address of this channel.
129      *         {@code null} if this channel is not bound.
130      */
131     SocketAddress localAddress();
132 
133     /**
134      * Returns the remote address where this channel is connected to.  The
135      * returned {@link SocketAddress} is supposed to be down-cast into more
136      * concrete type such as {@link InetSocketAddress} to retrieve the detailed
137      * information.
138      *
139      * @return the remote address of this channel.
140      *         {@code null} if this channel is not connected.
141      *         If this channel is not connected but it can receive messages
142      *         from arbitrary remote addresses (e.g. {@link DatagramChannel},
143      *         use {@link DatagramPacket#recipient()} to determine
144      *         the origination of the received message as this method will
145      *         return {@code null}.
146      */
147     SocketAddress remoteAddress();
148 
149     /**
150      * Returns the {@link ChannelFuture} which will be notified when this
151      * channel is closed.  This method always returns the same future instance.
152      */
153     ChannelFuture closeFuture();
154 
155     /**
156      * Returns {@code true} if and only if the I/O thread will perform the
157      * requested write operation immediately.  Any write requests made when
158      * this method returns {@code false} are queued until the I/O thread is
159      * ready to process the queued write requests.
160      *
161      * {@link WriteBufferWaterMark} can be used to configure on which condition
162      * the write buffer would cause this channel to change writability.
163      */
164     boolean isWritable();
165 
166     /**
167      * Get how many bytes can be written until {@link #isWritable()} returns {@code false}.
168      * This quantity will always be non-negative. If {@link #isWritable()} is {@code false} then 0.
169      *
170      * {@link WriteBufferWaterMark} can be used to define writability settings.
171      */
172     long bytesBeforeUnwritable();
173 
174     /**
175      * Get how many bytes must be drained from underlying buffers until {@link #isWritable()} returns {@code true}.
176      * This quantity will always be non-negative. If {@link #isWritable()} is {@code true} then 0.
177      *
178      * {@link WriteBufferWaterMark} can be used to define writability settings.
179      */
180     long bytesBeforeWritable();
181 
182     /**
183      * Returns an <em>internal-use-only</em> object that provides unsafe operations.
184      */
185     Unsafe unsafe();
186 
187     /**
188      * Return the assigned {@link ChannelPipeline}.
189      */
190     ChannelPipeline pipeline();
191 
192     /**
193      * Return the assigned {@link ByteBufAllocator} which will be used to allocate {@link ByteBuf}s.
194      */
195     ByteBufAllocator alloc();
196 
197     @Override
198     Channel read();
199 
200     @Override
201     Channel flush();
202 
203     /**
204      * <em>Unsafe</em> operations that should <em>never</em> be called from user-code. These methods
205      * are only provided to implement the actual transport, and must be invoked from an I/O thread except for the
206      * following methods:
207      * <ul>
208      *   <li>{@link #localAddress()}</li>
209      *   <li>{@link #remoteAddress()}</li>
210      *   <li>{@link #closeForcibly()}</li>
211      *   <li>{@link #register(EventLoop, ChannelPromise)}</li>
212      *   <li>{@link #deregister(ChannelPromise)}</li>
213      *   <li>{@link #voidPromise()}</li>
214      * </ul>
215      */
216     interface Unsafe {
217 
218         /**
219          * Return the assigned {@link RecvByteBufAllocator.Handle} which will be used to allocate {@link ByteBuf}'s when
220          * receiving data.
221          */
222         RecvByteBufAllocator.Handle recvBufAllocHandle();
223 
224         /**
225          * Return the {@link SocketAddress} to which is bound local or
226          * {@code null} if none.
227          */
228         SocketAddress localAddress();
229 
230         /**
231          * Return the {@link SocketAddress} to which is bound remote or
232          * {@code null} if none is bound yet.
233          */
234         SocketAddress remoteAddress();
235 
236         /**
237          * Register the {@link Channel} of the {@link ChannelPromise} and notify
238          * the {@link ChannelFuture} once the registration was complete.
239          */
240         void register(EventLoop eventLoop, ChannelPromise promise);
241 
242         /**
243          * Bind the {@link SocketAddress} to the {@link Channel} of the {@link ChannelPromise} and notify
244          * it once its done.
245          */
246         void bind(SocketAddress localAddress, ChannelPromise promise);
247 
248         /**
249          * Connect the {@link Channel} of the given {@link ChannelFuture} with the given remote {@link SocketAddress}.
250          * If a specific local {@link SocketAddress} should be used it need to be given as argument. Otherwise just
251          * pass {@code null} to it.
252          *
253          * The {@link ChannelPromise} will get notified once the connect operation was complete.
254          */
255         void connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise);
256 
257         /**
258          * Disconnect the {@link Channel} of the {@link ChannelFuture} and notify the {@link ChannelPromise} once the
259          * operation was complete.
260          */
261         void disconnect(ChannelPromise promise);
262 
263         /**
264          * Close the {@link Channel} of the {@link ChannelPromise} and notify the {@link ChannelPromise} once the
265          * operation was complete.
266          */
267         void close(ChannelPromise promise);
268 
269         /**
270          * Closes the {@link Channel} immediately without firing any events.  Probably only useful
271          * when registration attempt failed.
272          */
273         void closeForcibly();
274 
275         /**
276          * Deregister the {@link Channel} of the {@link ChannelPromise} from {@link EventLoop} and notify the
277          * {@link ChannelPromise} once the operation was complete.
278          */
279         void deregister(ChannelPromise promise);
280 
281         /**
282          * Schedules a read operation that fills the inbound buffer of the first {@link ChannelInboundHandler} in the
283          * {@link ChannelPipeline}.  If there's already a pending read operation, this method does nothing.
284          */
285         void beginRead();
286 
287         /**
288          * Schedules a write operation.
289          */
290         void write(Object msg, ChannelPromise promise);
291 
292         /**
293          * Flush out all write operations scheduled via {@link #write(Object, ChannelPromise)}.
294          */
295         void flush();
296 
297         /**
298          * Return a special ChannelPromise which can be reused and passed to the operations in {@link Unsafe}.
299          * It will never be notified of a success or error and so is only a placeholder for operations
300          * that take a {@link ChannelPromise} as argument but for which you not want to get notified.
301          */
302         ChannelPromise voidPromise();
303 
304         /**
305          * Returns the {@link ChannelOutboundBuffer} of the {@link Channel} where the pending write requests are stored.
306          */
307         ChannelOutboundBuffer outboundBuffer();
308     }
309 }