public interface Channel extends java.lang.Comparable<Channel>
A channel provides a user:
ChannelPipeline
which handles all I/O events and requests
associated with the channel.
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
a ChannelFuture
instance which will notify you when the requested I/O
operation has succeeded, failed, or canceled.
A Channel
can have a parent depending on
how it was created. For instance, a SocketChannel
, that was accepted
by ServerSocketChannel
, will return the ServerSocketChannel
as its parent on getParent()
.
The semantics of the hierarchical structure depends on the transport
implementation where the Channel
belongs to. For example, you could
write a new Channel
implementation that creates the sub-channels that
share one socket connection, as BEEP and
SSH do.
Some transports exposes additional operations that is specific to the
transport. Down-cast the Channel
to sub-type to invoke such
operations. For example, with the old I/O datagram transport, multicast
join / leave operations are provided by DatagramChannel
.
A Channel
has a property called interestOps
which is similar to that of NIO SelectionKey
.
It is represented as a bit
field which is composed of the two flags.
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 OP_READ
flag is set again (i.e. read suspension).OP_WRITE
- If set, a write request will not be sent to a remote
peer until the 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.OP_READ_WRITE
- This is a combination of OP_READ
and
OP_WRITE
, which means only write requests are suspended.OP_NONE
- This is a combination of (NOT OP_READ
) and
(NOT OP_WRITE
), which means only read operation is suspended.
You can set or clear the OP_READ
flag to suspend and resume read
operation via setReadable(boolean)
.
Please note that you cannot suspend or resume write operation just like you
can set or clear OP_READ
. The 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 OutOfMemoryError
. For example, the
NIO socket transport uses the writeBufferLowWaterMark
and
writeBufferHighWaterMark
properties in NioSocketChannelConfig
to determine when to set or clear the OP_WRITE
flag.
限定符和类型 | 字段和说明 |
---|---|
static int |
OP_NONE
The
interestOps value which tells that only
read operation has been suspended. |
static int |
OP_READ
The
interestOps value which tells that neither
read nor write operation has been suspended. |
static int |
OP_READ_WRITE
The
interestOps value which tells that only
write operation has been suspended. |
static int |
OP_WRITE
The
interestOps value which tells that both
read and write operation has been suspended. |
限定符和类型 | 方法和说明 |
---|---|
ChannelFuture |
bind(java.net.SocketAddress localAddress)
Binds this channel to the specified local address asynchronously.
|
ChannelFuture |
close()
Closes this channel asynchronously.
|
ChannelFuture |
connect(java.net.SocketAddress remoteAddress)
Connects this channel to the specified remote address asynchronously.
|
ChannelFuture |
disconnect()
Disconnects this channel from the current remote address asynchronously.
|
java.lang.Object |
getAttachment()
|
ChannelFuture |
getCloseFuture()
Returns the
ChannelFuture which will be notified when this
channel is closed. |
ChannelConfig |
getConfig()
Returns the configuration of this channel.
|
ChannelFactory |
getFactory()
Returns the
ChannelFactory which created this channel. |
java.lang.Integer |
getId()
Returns the unique integer ID of this channel.
|
int |
getInterestOps()
Returns the current
interestOps of this channel. |
java.net.SocketAddress |
getLocalAddress()
Returns the local address where this channel is bound to.
|
Channel |
getParent()
Returns the parent of this channel.
|
ChannelPipeline |
getPipeline()
Returns the
ChannelPipeline which handles ChannelEvent s
associated with this channel. |
java.net.SocketAddress |
getRemoteAddress()
Returns the remote address where this channel is connected to.
|
boolean |
getUserDefinedWritability(int index)
Returns
true if and only if the user-defined writability flag at the specified index is set to
true . |
boolean |
isBound()
Returns
true if and only if this channel is bound to a
local address. |
boolean |
isConnected()
Returns
true if and only if this channel is connected to a
remote address. |
boolean |
isOpen()
Returns
true if and only if this channel is open. |
boolean |
isReadable()
Returns
true if and only if the I/O thread will read a message
from this channel. |
boolean |
isWritable()
Returns
true if and only if the I/O thread will perform the
requested write operation immediately. |
void |
setAttachment(java.lang.Object attachment)
Attaches an object to this
Channel to store a stateful
information |
ChannelFuture |
setInterestOps(int interestOps)
Changes the
interestOps of this channel asynchronously. |
ChannelFuture |
setReadable(boolean readable)
Suspends or resumes the read operation of the I/O thread asynchronously.
|
void |
setUserDefinedWritability(int index,
boolean isWritable)
Sets a user-defined writability flag at the specified index.
|
ChannelFuture |
unbind()
Unbinds this channel from the current local address asynchronously.
|
ChannelFuture |
write(java.lang.Object message)
Sends a message to this channel asynchronously.
|
ChannelFuture |
write(java.lang.Object message,
java.net.SocketAddress remoteAddress)
Sends a message to this channel asynchronously.
|
static final int OP_NONE
interestOps
value which tells that only
read operation has been suspended.static final int OP_READ
interestOps
value which tells that neither
read nor write operation has been suspended.static final int OP_WRITE
interestOps
value which tells that both
read and write operation has been suspended.static final int OP_READ_WRITE
interestOps
value which tells that only
write operation has been suspended.java.lang.Integer getId()
ChannelFactory getFactory()
ChannelFactory
which created this channel.Channel getParent()
null
if this channel does not have a parent channel.ChannelConfig getConfig()
ChannelPipeline getPipeline()
ChannelPipeline
which handles ChannelEvent
s
associated with this channel.boolean isOpen()
true
if and only if this channel is open.boolean isBound()
true
if and only if this channel is bound to a
local address.boolean isConnected()
true
if and only if this channel is connected to a
remote address.java.net.SocketAddress getLocalAddress()
SocketAddress
is supposed to be down-cast into more concrete
type such as InetSocketAddress
to retrieve the detailed
information.null
if this channel is not bound.java.net.SocketAddress getRemoteAddress()
SocketAddress
is supposed to be down-cast into more
concrete type such as InetSocketAddress
to retrieve the detailed
information.null
if this channel is not connected.
If this channel is not connected but it can receive messages
from arbitrary remote addresses (e.g. DatagramChannel
,
use MessageEvent.getRemoteAddress()
to determine
the origination of the received message as this method will
return null
.ChannelFuture write(java.lang.Object message)
DatagramChannel
)
and is not connected yet, you have to call write(Object, SocketAddress)
instead. Otherwise, the write request will fail with
NotYetConnectedException
and an 'exceptionCaught'
event
will be triggered.message
- the message to writeChannelFuture
which will be notified when the
write request succeeds or failsjava.lang.NullPointerException
- if the specified message is null
ChannelFuture write(java.lang.Object message, java.net.SocketAddress remoteAddress)
DatagramChannel
)
and is not connected yet, you must specify non-null address. Otherwise,
the write request will fail with NotYetConnectedException
and
an 'exceptionCaught'
event will be triggered.message
- the message to writeremoteAddress
- where to send the specified message.
This method is identical to write(Object)
if null
is specified here.ChannelFuture
which will be notified when the
write request succeeds or failsjava.lang.NullPointerException
- if the specified message is null
ChannelFuture bind(java.net.SocketAddress localAddress)
localAddress
- where to bindChannelFuture
which will be notified when the
bind request succeeds or failsjava.lang.NullPointerException
- if the specified address is null
ChannelFuture connect(java.net.SocketAddress remoteAddress)
remoteAddress
- where to connectChannelFuture
which will be notified when the
connection request succeeds or failsjava.lang.NullPointerException
- if the specified address is null
ChannelFuture disconnect()
ChannelFuture
which will be notified when the
disconnection request succeeds or failsChannelFuture unbind()
ChannelFuture
which will be notified when the
unbind request succeeds or failsChannelFuture close()
ChannelFuture
which will be notified when the
close request succeeds or failsChannelFuture getCloseFuture()
ChannelFuture
which will be notified when this
channel is closed. This method always returns the same future instance.int getInterestOps()
interestOps
of this channel.OP_NONE
, OP_READ
, OP_WRITE
, or
OP_READ_WRITE
boolean isReadable()
true
if and only if the I/O thread will read a message
from this channel. This method is a shortcut to the following code:
return (getInterestOps() & OP_READ) != 0;
boolean isWritable()
true
if and only if the I/O thread will perform the
requested write operation immediately. Any write requests made when
this method returns false
are queued until the I/O thread is
ready to process the queued write requests. This method is a shortcut
to the following code:
return (getInterestOps() & OP_WRITE) == 0;
ChannelFuture setInterestOps(int interestOps)
interestOps
of this channel asynchronously.interestOps
- the new interestOps
ChannelFuture
which will be notified when the
interestOps
change request succeeds or failsChannelFuture setReadable(boolean readable)
int interestOps = getInterestOps(); if (readable) { setInterestOps(interestOps | OP_READ); } else { setInterestOps(interestOps & ~OP_READ); }
readable
- true
to resume the read operation and
false
to suspend the read operationChannelFuture
which will be notified when the
interestOps
change request succeeds or failsboolean getUserDefinedWritability(int index)
true
if and only if the user-defined writability flag at the specified index is set to
true
.void setUserDefinedWritability(int index, boolean isWritable)
java.lang.Object getAttachment()
null
if no object was attached or null
was
attachedvoid setAttachment(java.lang.Object attachment)
Channel
to store a stateful
information