2008-08-08 02:37:18 +02:00
|
|
|
/*
|
2012-06-04 22:31:44 +02:00
|
|
|
* Copyright 2012 The Netty Project
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
2011-12-09 06:18:34 +01:00
|
|
|
* The Netty Project licenses this file to you under the Apache License,
|
|
|
|
* version 2.0 (the "License"); you may not use this file except in compliance
|
|
|
|
* with the License. You may obtain a copy of the License at:
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
2012-06-04 22:31:44 +02:00
|
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
2008-08-08 03:27:24 +02:00
|
|
|
*
|
2009-08-28 09:15:49 +02:00
|
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
|
|
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
2011-12-09 06:18:34 +01:00
|
|
|
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
2009-08-28 09:15:49 +02:00
|
|
|
* License for the specific language governing permissions and limitations
|
|
|
|
* under the License.
|
2008-08-08 02:37:18 +02:00
|
|
|
*/
|
2011-12-09 04:38:59 +01:00
|
|
|
package io.netty.channel;
|
2008-08-08 02:37:18 +02:00
|
|
|
|
2012-06-02 02:51:19 +02:00
|
|
|
import io.netty.buffer.ChannelBuffer;
|
2011-12-09 04:38:59 +01:00
|
|
|
import io.netty.channel.socket.DatagramChannel;
|
|
|
|
import io.netty.channel.socket.ServerSocketChannel;
|
|
|
|
import io.netty.channel.socket.SocketChannel;
|
2012-05-01 10:19:41 +02:00
|
|
|
import io.netty.util.AttributeMap;
|
2009-07-18 09:20:03 +02:00
|
|
|
|
2012-04-03 15:03:04 +02:00
|
|
|
import java.net.InetSocketAddress;
|
|
|
|
import java.net.SocketAddress;
|
|
|
|
import java.nio.channels.SelectionKey;
|
2012-06-02 02:51:19 +02:00
|
|
|
import java.util.Queue;
|
2012-04-03 15:03:04 +02:00
|
|
|
|
2008-08-08 02:37:18 +02:00
|
|
|
|
|
|
|
/**
|
2008-09-02 09:22:16 +02:00
|
|
|
* A nexus to a network socket or a component which is capable of I/O
|
|
|
|
* operations such as read, write, connect, and bind.
|
2008-09-02 09:13:20 +02:00
|
|
|
* <p>
|
|
|
|
* A channel provides a user:
|
|
|
|
* <ul>
|
2008-09-02 15:45:14 +02:00
|
|
|
* <li>the current state of the channel (e.g. is it open? is it connected?),</li>
|
2008-09-03 03:09:40 +02:00
|
|
|
* <li>the {@linkplain ChannelConfig configuration parameters} of the channel (e.g. receive buffer size),</li>
|
2008-09-02 09:22:16 +02:00
|
|
|
* <li>the I/O operations that the channel supports (e.g. read, write, connect, and bind), and</li>
|
2008-09-03 12:57:17 +02:00
|
|
|
* <li>the {@link ChannelPipeline} which handles all {@linkplain ChannelEvent I/O events and requests}
|
2008-09-02 15:45:14 +02:00
|
|
|
* associated with the channel.</li>
|
2008-09-02 09:13:20 +02:00
|
|
|
* </ul>
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
2008-09-24 12:49:39 +02:00
|
|
|
* <h3>All I/O operations are asynchronous.</h3>
|
2009-07-23 10:26:54 +02:00
|
|
|
* <p>
|
2008-09-24 12:49:39 +02:00
|
|
|
* All I/O operations in Netty are asynchronous. It means any I/O calls will
|
|
|
|
* return immediately with no guarantee that the requested I/O operation has
|
|
|
|
* been completed at the end of the call. Instead, you will be returned with
|
2009-07-23 10:26:54 +02:00
|
|
|
* a {@link ChannelFuture} instance which will notify you when the requested I/O
|
2008-09-24 12:49:39 +02:00
|
|
|
* operation has succeeded, failed, or canceled.
|
|
|
|
*
|
2009-07-23 10:26:54 +02:00
|
|
|
* <h3>Channels are hierarchical</h3>
|
|
|
|
* <p>
|
|
|
|
* A {@link Channel} can have a {@linkplain #getParent() parent} depending on
|
|
|
|
* how it was created. For instance, a {@link SocketChannel}, that was accepted
|
|
|
|
* by {@link ServerSocketChannel}, will return the {@link ServerSocketChannel}
|
|
|
|
* as its parent on {@link #getParent()}.
|
|
|
|
* <p>
|
|
|
|
* The semantics of the hierarchical structure depends on the transport
|
|
|
|
* implementation where the {@link Channel} belongs to. For example, you could
|
|
|
|
* write a new {@link Channel} implementation that creates the sub-channels that
|
|
|
|
* share one socket connection, as <a href="http://beepcore.org/">BEEP</a> and
|
|
|
|
* <a href="http://en.wikipedia.org/wiki/Secure_Shell">SSH</a> do.
|
|
|
|
*
|
2010-04-16 07:07:37 +02:00
|
|
|
* <h3>Downcast to access transport-specific operations</h3>
|
|
|
|
* <p>
|
|
|
|
* Some transports exposes additional operations that is specific to the
|
|
|
|
* transport. Down-cast the {@link Channel} to sub-type to invoke such
|
|
|
|
* operations. For example, with the old I/O datagram transport, multicast
|
|
|
|
* join / leave operations are provided by {@link DatagramChannel}.
|
|
|
|
*
|
2009-08-25 11:10:22 +02:00
|
|
|
* <h3>InterestOps</h3>
|
|
|
|
* <p>
|
|
|
|
* A {@link Channel} has a property called {@link #getInterestOps() interestOps}
|
2009-08-25 11:13:58 +02:00
|
|
|
* which is similar to that of {@link SelectionKey#interestOps() NIO SelectionKey}.
|
|
|
|
* It is represented as a <a href="http://en.wikipedia.org/wiki/Bit_field">bit
|
|
|
|
* field</a> which is composed of the two flags.
|
2009-08-25 11:10:22 +02:00
|
|
|
* <ul>
|
|
|
|
* <li>{@link #OP_READ} - If set, a message sent by a remote peer will be read
|
|
|
|
* immediately. If unset, the message from the remote peer will not be read
|
|
|
|
* until the {@link #OP_READ} flag is set again (i.e. read suspension).</li>
|
|
|
|
* <li>{@link #OP_WRITE} - If set, a write request will not be sent to a remote
|
|
|
|
* peer until the {@link #OP_WRITE} flag is cleared and the write request
|
|
|
|
* will be pending in a queue. If unset, the write request will be flushed
|
|
|
|
* out as soon as possible from the queue.</li>
|
|
|
|
* <li>{@link #OP_READ_WRITE} - This is a combination of {@link #OP_READ} and
|
|
|
|
* {@link #OP_WRITE}, which means only write requests are suspended.</li>
|
|
|
|
* <li>{@link #OP_NONE} - This is a combination of (NOT {@link #OP_READ}) and
|
|
|
|
* (NOT {@link #OP_WRITE}), which means only read operation is suspended.</li>
|
|
|
|
* </ul>
|
|
|
|
* </p><p>
|
|
|
|
* You can set or clear the {@link #OP_READ} flag to suspend and resume read
|
|
|
|
* operation via {@link #setReadable(boolean)}.
|
|
|
|
* </p><p>
|
|
|
|
* Please note that you cannot suspend or resume write operation just like you
|
|
|
|
* can set or clear {@link #OP_READ}. The {@link #OP_WRITE} flag is read only
|
|
|
|
* and provided simply as a mean to tell you if the size of pending write
|
|
|
|
* requests exceeded a certain threshold or not so that you don't issue too many
|
|
|
|
* pending writes that lead to an {@link OutOfMemoryError}. For example, the
|
|
|
|
* NIO socket transport uses the {@code writeBufferLowWaterMark} and
|
|
|
|
* {@code writeBufferHighWaterMark} properties in {@link NioSocketChannelConfig}
|
|
|
|
* to determine when to set or clear the {@link #OP_WRITE} flag.
|
|
|
|
* </p>
|
2008-08-08 02:37:18 +02:00
|
|
|
* @apiviz.landmark
|
2011-12-09 04:38:59 +01:00
|
|
|
* @apiviz.composedOf io.netty.channel.ChannelConfig
|
|
|
|
* @apiviz.composedOf io.netty.channel.ChannelPipeline
|
2009-04-28 14:11:01 +02:00
|
|
|
*
|
2011-12-09 05:59:41 +01:00
|
|
|
* @apiviz.exclude ^io\.netty\.channel\.([a-z]+\.)+[^\.]+Channel$
|
2008-08-08 02:37:18 +02:00
|
|
|
*/
|
2012-05-09 15:09:06 +02:00
|
|
|
public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelFutureFactory, Comparable<Channel> {
|
2008-08-08 02:37:18 +02:00
|
|
|
|
2008-09-02 09:13:20 +02:00
|
|
|
/**
|
2009-02-16 12:59:33 +01:00
|
|
|
* Returns the unique integer ID of this channel.
|
2008-09-02 09:13:20 +02:00
|
|
|
*/
|
2012-05-01 10:19:41 +02:00
|
|
|
Integer id();
|
2008-09-02 09:13:20 +02:00
|
|
|
|
2012-06-02 10:58:15 +02:00
|
|
|
ChannelType type();
|
|
|
|
|
2012-04-03 15:03:04 +02:00
|
|
|
EventLoop eventLoop();
|
|
|
|
|
2008-09-02 09:13:20 +02:00
|
|
|
/**
|
|
|
|
* Returns the parent of this channel.
|
|
|
|
*
|
|
|
|
* @return the parent channel.
|
2008-11-14 08:45:53 +01:00
|
|
|
* {@code null} if this channel does not have a parent channel.
|
2008-09-02 09:13:20 +02:00
|
|
|
*/
|
2012-05-01 10:19:41 +02:00
|
|
|
Channel parent();
|
2008-09-02 09:13:20 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the configuration of this channel.
|
|
|
|
*/
|
2012-05-01 10:19:41 +02:00
|
|
|
ChannelConfig config();
|
2008-09-02 09:13:20 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the {@link ChannelPipeline} which handles {@link ChannelEvent}s
|
|
|
|
* associated with this channel.
|
|
|
|
*/
|
2012-05-01 10:19:41 +02:00
|
|
|
ChannelPipeline pipeline();
|
2008-09-02 09:13:20 +02:00
|
|
|
|
2012-05-09 15:09:06 +02:00
|
|
|
boolean isOpen();
|
2012-05-01 10:19:41 +02:00
|
|
|
boolean isRegistered();
|
|
|
|
boolean isActive();
|
2008-08-08 02:37:18 +02:00
|
|
|
|
2012-06-02 02:51:19 +02:00
|
|
|
ChannelBuffer outboundByteBuffer();
|
|
|
|
Queue<Object> outboundMessageBuffer();
|
2012-05-29 21:09:29 +02:00
|
|
|
|
2008-09-02 09:13:20 +02:00
|
|
|
/**
|
2008-09-02 12:39:57 +02:00
|
|
|
* Returns the local address where this channel is bound to. The returned
|
|
|
|
* {@link SocketAddress} is supposed to be down-cast into more concrete
|
|
|
|
* type such as {@link InetSocketAddress} to retrieve the detailed
|
|
|
|
* information.
|
2008-09-02 09:13:20 +02:00
|
|
|
*
|
|
|
|
* @return the local address of this channel.
|
|
|
|
* {@code null} if this channel is not bound.
|
|
|
|
*/
|
2012-05-01 10:19:41 +02:00
|
|
|
SocketAddress localAddress();
|
2008-09-02 09:13:20 +02:00
|
|
|
|
|
|
|
/**
|
2008-09-02 12:39:57 +02:00
|
|
|
* Returns the remote address where this channel is connected to. The
|
|
|
|
* returned {@link SocketAddress} is supposed to be down-cast into more
|
|
|
|
* concrete type such as {@link InetSocketAddress} to retrieve the detailed
|
|
|
|
* information.
|
2008-09-02 09:13:20 +02:00
|
|
|
*
|
|
|
|
* @return the remote address of this channel.
|
|
|
|
* {@code null} if this channel is not connected.
|
2009-07-18 09:20:03 +02:00
|
|
|
* If this channel is not connected but it can receive messages
|
|
|
|
* from arbitrary remote addresses (e.g. {@link DatagramChannel},
|
|
|
|
* use {@link MessageEvent#getRemoteAddress()} to determine
|
|
|
|
* the origination of the received message as this method will
|
|
|
|
* return {@code null}.
|
2008-09-02 09:13:20 +02:00
|
|
|
*/
|
2012-05-01 10:19:41 +02:00
|
|
|
SocketAddress remoteAddress();
|
2008-08-08 02:37:18 +02:00
|
|
|
|
2012-05-12 18:37:16 +02:00
|
|
|
/**
|
|
|
|
* Returns the {@link ChannelFuture} which will be notified when this
|
|
|
|
* channel is closed. This method always returns the same future instance.
|
|
|
|
*/
|
|
|
|
ChannelFuture closeFuture();
|
2012-04-03 15:29:26 +02:00
|
|
|
|
2012-04-03 15:03:04 +02:00
|
|
|
Unsafe unsafe();
|
|
|
|
|
|
|
|
public interface Unsafe {
|
2012-05-30 09:38:23 +02:00
|
|
|
ChannelBufferHolder<Object> directOutbound();
|
2012-05-10 17:57:42 +02:00
|
|
|
ChannelFuture voidFuture();
|
2012-05-01 10:19:41 +02:00
|
|
|
|
2012-05-02 08:01:58 +02:00
|
|
|
SocketAddress localAddress();
|
|
|
|
SocketAddress remoteAddress();
|
|
|
|
|
2012-05-01 16:18:29 +02:00
|
|
|
void register(EventLoop eventLoop, ChannelFuture future);
|
2012-05-01 10:19:41 +02:00
|
|
|
void bind(SocketAddress localAddress, ChannelFuture future);
|
|
|
|
void connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelFuture future);
|
|
|
|
void disconnect(ChannelFuture future);
|
|
|
|
void close(ChannelFuture future);
|
|
|
|
void deregister(ChannelFuture future);
|
2012-04-03 15:03:04 +02:00
|
|
|
|
2012-05-09 15:09:06 +02:00
|
|
|
void flush(ChannelFuture future);
|
2012-05-27 07:48:48 +02:00
|
|
|
void flushNow();
|
2012-04-03 15:03:04 +02:00
|
|
|
}
|
2008-08-08 02:37:18 +02:00
|
|
|
}
|