io.netty.channel

接口 Channel

所有超级接口:

AttributeMap, java.lang.Comparable<Channel>

所有已知子接口:

DatagramChannel, DomainSocketChannel, DuplexChannel, SctpChannel, SctpServerChannel, ServerChannel, ServerDomainSocketChannel, ServerSocketChannel, SocketChannel, UdtChannel, UdtServerChannel, UnixChannel

所有已知实现类:

AbstractChannel, AbstractEpollServerChannel, AbstractEpollStreamChannel, AbstractNioByteChannel, AbstractNioChannel, AbstractNioMessageChannel, AbstractOioByteChannel, AbstractOioChannel, AbstractOioMessageChannel, AbstractServerChannel, EmbeddedChannel, EpollDatagramChannel, EpollDomainSocketChannel, EpollServerDomainSocketChannel, EpollServerSocketChannel, EpollSocketChannel, LocalChannel, LocalServerChannel, NioDatagramChannel, NioSctpChannel, NioSctpServerChannel, NioServerSocketChannel, NioSocketChannel, NioUdtAcceptorChannel, NioUdtByteAcceptorChannel, NioUdtByteConnectorChannel, NioUdtByteRendezvousChannel, NioUdtMessageAcceptorChannel, NioUdtMessageConnectorChannel, NioUdtMessageRendezvousChannel, OioByteStreamChannel, OioDatagramChannel, OioSctpChannel, OioSctpServerChannel, OioServerSocketChannel, OioSocketChannel, RxtxChannel

public interface Channel
extends AttributeMap, java.lang.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, a SocketChannel, that was accepted by ServerSocketChannel, will return the ServerSocketChannel as its parent on parent().

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.

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 by DatagramChannel.

Release resources

It is important to call close() or close(ChannelPromise) to release all resources once you are done with the Channel. This ensures all resources are released in a proper way, i.e. filehandles.

嵌套类概要

嵌套类

限定符和类型	接口和说明
static interface	Channel.Unsafe Unsafe operations that should never be called from user-code.

方法概要

方法

限定符和类型	方法和说明
ByteBufAllocator	alloc() Return the assigned ByteBufAllocator which will be used to allocate ByteBufs.
ChannelFuture	bind(java.net.SocketAddress localAddress) Request to bind to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
ChannelFuture	bind(java.net.SocketAddress localAddress, ChannelPromise promise) Request to bind to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
ChannelFuture	close() Request to close this Channel and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
ChannelFuture	close(ChannelPromise promise) Request to close this Channel and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
ChannelFuture	closeFuture() Returns the ChannelFuture which will be notified when this channel is closed.
ChannelConfig	config() Returns the configuration of this channel.
ChannelFuture	connect(java.net.SocketAddress remoteAddress) Request to connect to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
ChannelFuture	connect(java.net.SocketAddress remoteAddress, ChannelPromise promise) Request to connect to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
ChannelFuture	connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress) Request to connect to the given SocketAddress while bind to the localAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
ChannelFuture	connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress, ChannelPromise promise) Request to connect to the given SocketAddress while bind to the localAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
ChannelFuture	deregister() Request to deregister this Channel from the previous assigned EventExecutor and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
ChannelFuture	deregister(ChannelPromise promise) Request to deregister this Channel from the previous assigned EventExecutor and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
ChannelFuture	disconnect() Request to disconnect from the remote peer and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
ChannelFuture	disconnect(ChannelPromise promise) Request to disconnect from the remote peer and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.
EventLoop	eventLoop() Return the EventLoop this Channel was registered to.
Channel	flush() Request to flush all pending messages.
boolean	isActive() Return true if the Channel is active and so connected.
boolean	isOpen() Returns true if the Channel is open and may get active later
boolean	isRegistered() Returns true if the Channel is registered with an EventLoop.
boolean	isWritable() Returns true if and only if the I/O thread will perform the requested write operation immediately.
java.net.SocketAddress	localAddress() Returns the local address where this channel is bound to.
ChannelMetadata	metadata() Return the ChannelMetadata of the Channel which describe the nature of the Channel.
ChannelFuture	newFailedFuture(java.lang.Throwable cause) Create a new ChannelFuture which is marked as failed already.
ChannelProgressivePromise	newProgressivePromise() Return an new ChannelProgressivePromise.
ChannelPromise	newPromise() Return a new ChannelPromise.
ChannelFuture	newSucceededFuture() Create a new ChannelFuture which is marked as succeeded already.
Channel	parent() Returns the parent of this channel.
ChannelPipeline	pipeline() Return the assigned ChannelPipeline.
Channel	read() Request to Read data from the Channel into the first inbound buffer, triggers an ChannelInboundHandler.channelRead(ChannelHandlerContext, Object) event if data was read, and triggers a channelReadComplete event so the handler can decide to continue reading.
java.net.SocketAddress	remoteAddress() Returns the remote address where this channel is connected to.
Channel.Unsafe	unsafe() Returns an internal-use-only object that provides unsafe operations.
ChannelPromise	voidPromise() Return a special ChannelPromise which can be reused for different operations.
ChannelFuture	write(java.lang.Object msg) Request to write a message via this Channel through the ChannelPipeline.
ChannelFuture	write(java.lang.Object msg, ChannelPromise promise) Request to write a message via this Channel through the ChannelPipeline.
ChannelFuture	writeAndFlush(java.lang.Object msg) Shortcut for call write(Object) and flush().
ChannelFuture	writeAndFlush(java.lang.Object msg, ChannelPromise promise) Shortcut for call write(Object, ChannelPromise) and flush().

从接口继承的方法 io.netty.util.AttributeMap

attr

从接口继承的方法 java.lang.Comparable

compareTo

方法详细资料

eventLoop

EventLoop eventLoop()

Return the EventLoop this Channel was registered to.

parent

Channel parent()

Returns the parent of this channel.

返回:

the parent channel. null if this channel does not have a parent channel.

config

ChannelConfig config()

Returns the configuration of this channel.

isOpen

boolean isOpen()

Returns true if the Channel is open and may get active later

isRegistered

boolean isRegistered()

Returns true if the Channel is registered with an EventLoop.

isActive

boolean isActive()

Return true if the Channel is active and so connected.

metadata

ChannelMetadata metadata()

Return the ChannelMetadata of the Channel which describe the nature of the Channel.

localAddress

java.net.SocketAddress localAddress()

Returns the local address where this channel is bound to. The returned SocketAddress is supposed to be down-cast into more concrete type such as InetSocketAddress to retrieve the detailed information.

返回:

the local address of this channel. null if this channel is not bound.

remoteAddress

java.net.SocketAddress remoteAddress()

Returns the remote address where this channel is connected to. The returned SocketAddress is supposed to be down-cast into more concrete type such as InetSocketAddress to retrieve the detailed information.

返回:

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, use DefaultAddressedEnvelope.recipient() to determine the origination of the received message as this method will return null.

closeFuture

ChannelFuture closeFuture()

Returns the ChannelFuture which will be notified when this channel is closed. This method always returns the same future instance.

isWritable

boolean isWritable()

Returns 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.

unsafe

Channel.Unsafe unsafe()

Returns an internal-use-only object that provides unsafe operations.

pipeline

ChannelPipeline pipeline()

Return the assigned ChannelPipeline.

alloc

ByteBufAllocator alloc()

Return the assigned ByteBufAllocator which will be used to allocate ByteBufs.

newPromise

ChannelPromise newPromise()

Return a new ChannelPromise.

newProgressivePromise

ChannelProgressivePromise newProgressivePromise()

Return an new ChannelProgressivePromise.

newSucceededFuture

ChannelFuture newSucceededFuture()

Create a new ChannelFuture which is marked as succeeded already. So Future.isSuccess() will return true. All FutureListener added to it will be notified directly. Also every call of blocking methods will just return without blocking.

newFailedFuture

ChannelFuture newFailedFuture(java.lang.Throwable cause)

Create a new ChannelFuture which is marked as failed already. So Future.isSuccess() will return false. All FutureListener added to it will be notified directly. Also every call of blocking methods will just return without blocking.

voidPromise

ChannelPromise voidPromise()

Return a special ChannelPromise which can be reused for different operations.

It's only supported to use it for write(Object, ChannelPromise).

Be aware that the returned ChannelPromise will not support most operations and should only be used if you want to save an object allocation for every write operation. You will not be able to detect if the operation was complete, only if it failed as the implementation will call ChannelPipeline.fireExceptionCaught(Throwable) in this case.

Be aware this is an expert feature and should be used with care!

bind

ChannelFuture bind(java.net.SocketAddress localAddress)

Request to bind to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.

This will result in having the ChannelOutboundHandler.bind(ChannelHandlerContext, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

connect

ChannelFuture connect(java.net.SocketAddress remoteAddress)

Request to connect to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.

If the connection fails because of a connection timeout, the ChannelFuture will get failed with a ConnectTimeoutException. If it fails because of connection refused a ConnectException will be used.

This will result in having the ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

connect

ChannelFuture connect(java.net.SocketAddress remoteAddress,
                    java.net.SocketAddress localAddress)

Request to connect to the given SocketAddress while bind to the localAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.

This will result in having the ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

disconnect

ChannelFuture disconnect()

Request to disconnect from the remote peer and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.

This will result in having the ChannelOutboundHandler.disconnect(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

close

ChannelFuture close()

Request to close this Channel and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. After it is closed it is not possible to reuse it again.

This will result in having the ChannelOutboundHandler.close(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

deregister

ChannelFuture deregister()

Request to deregister this Channel from the previous assigned EventExecutor and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error.

This will result in having the ChannelOutboundHandler.deregister(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

bind

ChannelFuture bind(java.net.SocketAddress localAddress,
                 ChannelPromise promise)

Request to bind to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise will be notified.

This will result in having the ChannelOutboundHandler.bind(ChannelHandlerContext, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

connect

ChannelFuture connect(java.net.SocketAddress remoteAddress,
                    ChannelPromise promise)

Request to connect to the given SocketAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. The given ChannelFuture will be notified.

If the connection fails because of a connection timeout, the ChannelFuture will get failed with a ConnectTimeoutException. If it fails because of connection refused a ConnectException will be used.

This will result in having the ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

connect

ChannelFuture connect(java.net.SocketAddress remoteAddress,
                    java.net.SocketAddress localAddress,
                    ChannelPromise promise)

Request to connect to the given SocketAddress while bind to the localAddress and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise will be notified and also returned.

This will result in having the ChannelOutboundHandler.connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

disconnect

ChannelFuture disconnect(ChannelPromise promise)

Request to disconnect from the remote peer and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise will be notified.

This will result in having the ChannelOutboundHandler.disconnect(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

close

ChannelFuture close(ChannelPromise promise)

Request to close this Channel and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. After it is closed it is not possible to reuse it again. The given ChannelPromise will be notified.

This will result in having the ChannelOutboundHandler.close(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

deregister

ChannelFuture deregister(ChannelPromise promise)

Request to deregister this Channel from the previous assigned EventExecutor and notify the ChannelFuture once the operation completes, either because the operation was successful or because of an error. The given ChannelPromise will be notified.

This will result in having the ChannelOutboundHandler.deregister(ChannelHandlerContext, ChannelPromise) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

read

Channel read()

Request to Read data from the Channel into the first inbound buffer, triggers an ChannelInboundHandler.channelRead(ChannelHandlerContext, Object) event if data was read, and triggers a channelReadComplete event so the handler can decide to continue reading. If there's a pending read operation already, this method does nothing.

This will result in having the ChannelOutboundHandler.read(ChannelHandlerContext) method called of the next ChannelOutboundHandler contained in the ChannelPipeline of the Channel.

write

ChannelFuture write(java.lang.Object msg)

Request to write a message via this Channel through the ChannelPipeline. This method will not request to actual flush, so be sure to call flush() once you want to request to flush all pending data to the actual transport.

write

ChannelFuture write(java.lang.Object msg,
                  ChannelPromise promise)

Request to write a message via this Channel through the ChannelPipeline. This method will not request to actual flush, so be sure to call flush() once you want to request to flush all pending data to the actual transport.

flush

Channel flush()

Request to flush all pending messages.

writeAndFlush

ChannelFuture writeAndFlush(java.lang.Object msg,
                          ChannelPromise promise)

Shortcut for call write(Object, ChannelPromise) and flush().

writeAndFlush

ChannelFuture writeAndFlush(java.lang.Object msg)

Shortcut for call write(Object) and flush().