Interface ChannelEvent
- All Known Subinterfaces:
ChannelStateEvent
,ChildChannelStateEvent
,ExceptionEvent
,IdleStateEvent
,MessageEvent
,WriteCompletionEvent
- All Known Implementing Classes:
DefaultChildChannelStateEvent
,DefaultExceptionEvent
,DefaultIdleStateEvent
,DefaultWriteCompletionEvent
,DownstreamChannelStateEvent
,DownstreamMessageEvent
,UpstreamChannelStateEvent
,UpstreamMessageEvent
Channel
.
A ChannelEvent
is handled by a series of ChannelHandler
s in
a ChannelPipeline
.
Upstream events and downstream events, and their interpretation
Every event is either an upstream event or a downstream event.
If an event flows forward from the first handler to the last handler in a
ChannelPipeline
, we call it an upstream event and say "an
event goes upstream." If an event flows backward from the last
handler to the first handler in a ChannelPipeline
, we call it a
downstream event and say "an event goes downstream."
(Please refer to the diagram in ChannelPipeline
for more explanation.)
When your server receives a message from a client, the event associated with
the received message is an upstream event. When your server sends a message
or reply to the client, the event associated with the write request is a
downstream event. The same rule applies for the client side. If your client
sent a request to the server, it means your client triggered a downstream
event. If your client received a response from the server, it means
your client will be notified with an upstream event. Upstream events are
often the result of inbound operations such as InputStream.read(byte[])
,
and downstream events are the request for outbound operations such as
OutputStream.write(byte[])
, Socket.connect(SocketAddress)
,
and Socket.close()
.
Upstream events
Event name | Event type and condition | Meaning | |
---|---|---|---|
"messageReceived" |
MessageEvent |
a message object (e.g. ChannelBuffer ) was received from a remote peer |
|
"exceptionCaught" |
ExceptionEvent |
an exception was raised by an I/O thread or a ChannelHandler |
|
"channelOpen" |
ChannelStateEvent (state = OPEN , value = true ) |
a Channel is open, but not bound nor connected |
Be aware that this event is fired from within the I/O thread. You should never execute any heavy operation in there as it will block the dispatching to other workers! |
"channelClosed" |
ChannelStateEvent (state = OPEN , value = false ) |
a Channel was closed and all its related resources were released |
|
"channelBound" |
ChannelStateEvent (state = BOUND , value = SocketAddress ) |
a Channel is open and bound to a local address, but not connected. |
Be aware that this event is fired from within the I/O thread. You should never execute any heavy operation in there as it will block the dispatching to other workers! |
"channelUnbound" |
ChannelStateEvent (state = BOUND , value = null ) |
a Channel was unbound from the current local address |
|
"channelConnected" |
ChannelStateEvent (state = CONNECTED , value =
SocketAddress ) |
a Channel is open, bound to a local address, and connected to a remote address |
Be aware that this event is fired from within the I/O thread. You should never execute any heavy operation in there as it will block the dispatching to other workers! |
"writeComplete" |
WriteCompletionEvent |
something has been written to a remote peer | |
"channelDisconnected" |
ChannelStateEvent (state = CONNECTED , value = null ) |
a Channel was disconnected from its remote peer |
|
"channelInterestChanged" |
ChannelStateEvent (state = INTEREST_OPS , no value) |
a Channel 's interestOps was changed |
These two additional event types are used only for a parent channel which
can have a child channel (e.g. ServerSocketChannel
).
Event name | Event type and condition | Meaning |
---|---|---|
"childChannelOpen" |
ChildChannelStateEvent ( childChannel.isOpen() = true ) |
a child Channel was open (e.g. a server channel accepted a connection.) |
"childChannelClosed" |
ChildChannelStateEvent ( childChannel.isOpen() = false ) |
a child Channel was closed (e.g. the accepted connection was closed.) |
Downstream events
Event name | Event type and condition | Meaning |
---|---|---|
"write" |
MessageEvent | Send a message to the Channel . |
"bind" |
ChannelStateEvent (state = BOUND , value = SocketAddress ) |
Bind the Channel to the specified local address. |
"unbind" |
ChannelStateEvent (state = BOUND , value = null ) |
Unbind the Channel from the current local address. |
"connect" |
ChannelStateEvent (state = CONNECTED , value =
SocketAddress ) |
Connect the Channel to the specified remote address. |
"disconnect" |
ChannelStateEvent (state = CONNECTED , value = null ) |
Disconnect the Channel from the current remote address. |
"close" |
ChannelStateEvent (state = OPEN , value = false ) |
Close the Channel . |
Other event types and conditions which were not addressed here will be
ignored and discarded. Please note that there's no "open"
in the
table. It is because a Channel
is always open when it is created
by a ChannelFactory
.
Additional resources worth reading
Please refer to the ChannelHandler
and ChannelPipeline
documentation to find out how an event flows in a pipeline and how to handle
the event in your application.
-
Method Summary
Modifier and TypeMethodDescriptionReturns theChannel
which is associated with this event.Returns theChannelFuture
which is associated with this event.
-
Method Details
-
getChannel
Channel getChannel()Returns theChannel
which is associated with this event. -
getFuture
ChannelFuture getFuture()Returns theChannelFuture
which is associated with this event. If this event is an upstream event, this method will always return aSucceededChannelFuture
because the event has occurred already. If this event is a downstream event (i.e. I/O request), the returned future will be notified when the I/O request succeeds or fails.
-