Interface Channel
-
- All Superinterfaces:
Comparable<Channel>
- All Known Subinterfaces:
DatagramChannel
,LocalChannel
,LocalServerChannel
,ServerChannel
,ServerSocketChannel
,SocketChannel
- All Known Implementing Classes:
AbstractChannel
,AbstractServerChannel
,NioDatagramChannel
,NioSocketChannel
public interface Channel extends Comparable<Channel>
A nexus to a network socket or a component which is capable of I/O operations such as read, write, connect, and bind.A channel provides a user:
- the current state of the channel (e.g. is it open? is it connected?),
- the configuration parameters of the channel (e.g. receive buffer size),
- the I/O operations that the channel supports (e.g. read, write, connect, and bind), and
- the
ChannelPipeline
which handles all I/O events and requests associated with the channel.
All I/O operations are asynchronous.
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.Channels are hierarchical
A
Channel
can have a parent depending on how it was created. For instance, aSocketChannel
, that was accepted byServerSocketChannel
, will return theServerSocketChannel
as its parent ongetParent()
.The semantics of the hierarchical structure depends on the transport implementation where the
Channel
belongs to. For example, you could write a newChannel
implementation that creates the sub-channels that share one socket connection, as BEEP and SSH do.Downcast to access transport-specific operations
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 byDatagramChannel
.InterestOps
A
Channel
has a property calledinterestOps
which is similar to that ofNIO 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 theOP_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 theOP_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 ofOP_READ
andOP_WRITE
, which means only write requests are suspended.OP_NONE
- This is a combination of (NOTOP_READ
) and (NOTOP_WRITE
), which means only read operation is suspended.
You can set or clear the
OP_READ
flag to suspend and resume read operation viasetReadable(boolean)
.Please note that you cannot suspend or resume write operation just like you can set or clear
OP_READ
. TheOP_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 anOutOfMemoryError
. For example, the NIO socket transport uses thewriteBufferLowWaterMark
andwriteBufferHighWaterMark
properties inNioSocketChannelConfig
to determine when to set or clear theOP_WRITE
flag.
-
-
Field Summary
Fields Modifier and Type Field Description static int
OP_NONE
TheinterestOps
value which tells that only read operation has been suspended.static int
OP_READ
TheinterestOps
value which tells that neither read nor write operation has been suspended.static int
OP_READ_WRITE
TheinterestOps
value which tells that only write operation has been suspended.static int
OP_WRITE
TheinterestOps
value which tells that both read and write operation has been suspended.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description ChannelFuture
bind(SocketAddress localAddress)
Binds this channel to the specified local address asynchronously.ChannelFuture
close()
Closes this channel asynchronously.ChannelFuture
connect(SocketAddress remoteAddress)
Connects this channel to the specified remote address asynchronously.ChannelFuture
disconnect()
Disconnects this channel from the current remote address asynchronously.Object
getAttachment()
ChannelFuture
getCloseFuture()
Returns theChannelFuture
which will be notified when this channel is closed.ChannelConfig
getConfig()
Returns the configuration of this channel.ChannelFactory
getFactory()
Returns theChannelFactory
which created this channel.Integer
getId()
Returns the unique integer ID of this channel.int
getInterestOps()
Returns the currentinterestOps
of this channel.SocketAddress
getLocalAddress()
Returns the local address where this channel is bound to.Channel
getParent()
Returns the parent of this channel.ChannelPipeline
getPipeline()
Returns theChannelPipeline
which handlesChannelEvent
s associated with this channel.SocketAddress
getRemoteAddress()
Returns the remote address where this channel is connected to.boolean
getUserDefinedWritability(int index)
Returnstrue
if and only if the user-defined writability flag at the specified index is set totrue
.boolean
isBound()
Returnstrue
if and only if this channel is bound to a local address.boolean
isConnected()
Returnstrue
if and only if this channel is connected to a remote address.boolean
isOpen()
Returnstrue
if and only if this channel is open.boolean
isReadable()
Returnstrue
if and only if the I/O thread will read a message from this channel.boolean
isWritable()
Returnstrue
if and only if the I/O thread will perform the requested write operation immediately.void
setAttachment(Object attachment)
Attaches an object to thisChannel
to store a stateful informationChannelFuture
setInterestOps(int interestOps)
Changes theinterestOps
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(Object message)
Sends a message to this channel asynchronously.ChannelFuture
write(Object message, SocketAddress remoteAddress)
Sends a message to this channel asynchronously.-
Methods inherited from interface java.lang.Comparable
compareTo
-
-
-
-
Field Detail
-
OP_NONE
static final int OP_NONE
TheinterestOps
value which tells that only read operation has been suspended.- See Also:
- Constant Field Values
-
OP_READ
static final int OP_READ
TheinterestOps
value which tells that neither read nor write operation has been suspended.- See Also:
- Constant Field Values
-
OP_WRITE
static final int OP_WRITE
TheinterestOps
value which tells that both read and write operation has been suspended.- See Also:
- Constant Field Values
-
OP_READ_WRITE
static final int OP_READ_WRITE
TheinterestOps
value which tells that only write operation has been suspended.- See Also:
- Constant Field Values
-
-
Method Detail
-
getId
Integer getId()
Returns the unique integer ID of this channel.
-
getFactory
ChannelFactory getFactory()
Returns theChannelFactory
which created this channel.
-
getParent
Channel getParent()
Returns the parent of this channel.- Returns:
- the parent channel.
null
if this channel does not have a parent channel.
-
getConfig
ChannelConfig getConfig()
Returns the configuration of this channel.
-
getPipeline
ChannelPipeline getPipeline()
Returns theChannelPipeline
which handlesChannelEvent
s associated with this channel.
-
isOpen
boolean isOpen()
Returnstrue
if and only if this channel is open.
-
isBound
boolean isBound()
Returnstrue
if and only if this channel is bound to a local address.
-
isConnected
boolean isConnected()
Returnstrue
if and only if this channel is connected to a remote address.
-
getLocalAddress
SocketAddress getLocalAddress()
Returns the local address where this channel is bound to. The returnedSocketAddress
is supposed to be down-cast into more concrete type such asInetSocketAddress
to retrieve the detailed information.- Returns:
- the local address of this channel.
null
if this channel is not bound.
-
getRemoteAddress
SocketAddress getRemoteAddress()
Returns the remote address where this channel is connected to. The returnedSocketAddress
is supposed to be down-cast into more concrete type such asInetSocketAddress
to retrieve the detailed information.- Returns:
- the remote address of this channel.
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
, useMessageEvent.getRemoteAddress()
to determine the origination of the received message as this method will returnnull
.
-
write
ChannelFuture write(Object message)
Sends a message to this channel asynchronously. If this channel was created by a connectionless transport (e.g.DatagramChannel
) and is not connected yet, you have to callwrite(Object, SocketAddress)
instead. Otherwise, the write request will fail withNotYetConnectedException
and an'exceptionCaught'
event will be triggered.- Parameters:
message
- the message to write- Returns:
- the
ChannelFuture
which will be notified when the write request succeeds or fails - Throws:
NullPointerException
- if the specified message isnull
-
write
ChannelFuture write(Object message, SocketAddress remoteAddress)
Sends a message to this channel asynchronously. It has an additional parameter that allows a user to specify where to send the specified message instead of this channel's current remote address. If this channel was created by a connectionless transport (e.g.DatagramChannel
) and is not connected yet, you must specify non-null address. Otherwise, the write request will fail withNotYetConnectedException
and an'exceptionCaught'
event will be triggered.- Parameters:
message
- the message to writeremoteAddress
- where to send the specified message. This method is identical towrite(Object)
ifnull
is specified here.- Returns:
- the
ChannelFuture
which will be notified when the write request succeeds or fails - Throws:
NullPointerException
- if the specified message isnull
-
bind
ChannelFuture bind(SocketAddress localAddress)
Binds this channel to the specified local address asynchronously.- Parameters:
localAddress
- where to bind- Returns:
- the
ChannelFuture
which will be notified when the bind request succeeds or fails - Throws:
NullPointerException
- if the specified address isnull
-
connect
ChannelFuture connect(SocketAddress remoteAddress)
Connects this channel to the specified remote address asynchronously.- Parameters:
remoteAddress
- where to connect- Returns:
- the
ChannelFuture
which will be notified when the connection request succeeds or fails - Throws:
NullPointerException
- if the specified address isnull
-
disconnect
ChannelFuture disconnect()
Disconnects this channel from the current remote address asynchronously.- Returns:
- the
ChannelFuture
which will be notified when the disconnection request succeeds or fails
-
unbind
ChannelFuture unbind()
Unbinds this channel from the current local address asynchronously.- Returns:
- the
ChannelFuture
which will be notified when the unbind request succeeds or fails
-
close
ChannelFuture close()
Closes this channel asynchronously. If this channel is bound or connected, it will be disconnected and unbound first. Once a channel is closed, it can not be open again. Calling this method on a closed channel has no effect. Please note that this method always returns the same future instance.- Returns:
- the
ChannelFuture
which will be notified when the close request succeeds or fails
-
getCloseFuture
ChannelFuture getCloseFuture()
Returns theChannelFuture
which will be notified when this channel is closed. This method always returns the same future instance.
-
getInterestOps
int getInterestOps()
Returns the currentinterestOps
of this channel.- Returns:
OP_NONE
,OP_READ
,OP_WRITE
, orOP_READ_WRITE
-
isReadable
boolean isReadable()
Returnstrue
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;
-
isWritable
boolean isWritable()
Returnstrue
if and only if the I/O thread will perform the requested write operation immediately. Any write requests made when this method returnsfalse
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;
-
setInterestOps
ChannelFuture setInterestOps(int interestOps)
Changes theinterestOps
of this channel asynchronously.- Parameters:
interestOps
- the newinterestOps
- Returns:
- the
ChannelFuture
which will be notified when theinterestOps
change request succeeds or fails
-
setReadable
ChannelFuture setReadable(boolean readable)
Suspends or resumes the read operation of the I/O thread asynchronously. This method is a shortcut to the following code:int interestOps = getInterestOps(); if (readable) { setInterestOps(interestOps | OP_READ); } else { setInterestOps(interestOps & ~OP_READ); }
- Parameters:
readable
-true
to resume the read operation andfalse
to suspend the read operation- Returns:
- the
ChannelFuture
which will be notified when theinterestOps
change request succeeds or fails
-
getUserDefinedWritability
boolean getUserDefinedWritability(int index)
Returnstrue
if and only if the user-defined writability flag at the specified index is set totrue
.
-
setUserDefinedWritability
void setUserDefinedWritability(int index, boolean isWritable)
Sets a user-defined writability flag at the specified index.
-
getAttachment
Object getAttachment()
- Returns:
null
if no object was attached ornull
was attached
-
-