A {@link ChannelEvent} is handled by a series of {@link ChannelHandler}s in a {@link ChannelPipeline}.
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 {@link 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 {@link ChannelPipeline}, we call it a downstream event and say "an event goes downstream." (Please refer to the diagram in {@link 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 {@link InputStream#read(byte[])}, and downstream events are the request for outbound operations such as {@link OutputStream#write(byte[])}, {@link Socket#connect(SocketAddress)}, and {@link Socket#close()}.
| Event name | Event type and condition | Meaning | |
|---|---|---|---|
| {@code "messageReceived"} | {@link MessageEvent} | a message object (e.g. {@link ChannelBuffer}) was received from a remote peer | |
| {@code "exceptionCaught"} | {@link ExceptionEvent} | an exception was raised by an I/O thread or a {@link ChannelHandler} | |
| {@code "channelOpen"} | {@link ChannelStateEvent} (state = {@link ChannelState#OPEN OPEN}, value = {@code true}) | a {@link Channel} is open, but not bound nor connected | Be aware that this event is fired from within the Boss-Thread so you should not execute any heavy operation in there as it will block the dispatching to other workers! |
| {@code "channelClosed"} | {@link ChannelStateEvent} (state = {@link ChannelState#OPEN OPEN}, value = {@code false}) | a {@link Channel} was closed and all its related resources were released | |
| {@code "channelBound"} | {@link ChannelStateEvent} (state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress}) | a {@link Channel} is open and bound to a local address, but not connected. | Be aware that this event is fired from within the Boss-Thread so you should not execute any heavy operation in there as it will block the dispatching to other workers! |
| {@code "channelUnbound"} | {@link ChannelStateEvent} (state = {@link ChannelState#BOUND BOUND}, value = {@code null}) | a {@link Channel} was unbound from the current local address | |
| {@code "channelConnected"} | {@link ChannelStateEvent} (state = {@link ChannelState#CONNECTED CONNECTED}, value = {@link SocketAddress}) | a {@link Channel} is open, bound to a local address, and connected to a remote address | Be aware that this event is fired from within the Boss-Thread so you should not execute any heavy operation in there as it will block the dispatching to other workers! |
| {@code "writeComplete"} | {@link WriteCompletionEvent} | something has been written to a remote peer | |
| {@code "channelDisconnected"} | {@link ChannelStateEvent} (state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null}) | a {@link Channel} was disconnected from its remote peer | |
| {@code "channelInterestChanged"} | {@link ChannelStateEvent} (state = {@link ChannelState#INTEREST_OPS INTEREST_OPS}, no value) | a {@link Channel}'s {@link Channel#getInterestOps() interestOps} was changed |
These two additional event types are used only for a parent channel which can have a child channel (e.g. {@link ServerSocketChannel}).
| Event name | Event type and condition | Meaning |
|---|---|---|
| {@code "childChannelOpen"} | {@link ChildChannelStateEvent} ( {@code childChannel.isOpen() = true}) | a child {@link Channel} was open (e.g. a server channel accepted a connection.) |
| {@code "childChannelClosed"} | {@link ChildChannelStateEvent} ( {@code childChannel.isOpen() = false}) | a child {@link Channel} was closed (e.g. the accepted connection was closed.) |
| Event name | Event type and condition | Meaning |
|---|---|---|
| {@code "write"} | {@link MessageEvent} | Send a message to the {@link Channel}. |
| {@code "bind"} | {@link ChannelStateEvent} (state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress}) | Bind the {@link Channel} to the specified local address. |
| {@code "unbind"} | {@link ChannelStateEvent} (state = {@link ChannelState#BOUND BOUND}, value = {@code null}) | Unbind the {@link Channel} from the current local address. |
| {@code "connect"} | {@link ChannelStateEvent} (state = {@link ChannelState#CONNECTED CONNECTED}, value = {@link SocketAddress}) | Connect the {@link Channel} to the specified remote address. |
| {@code "disconnect"} | {@link ChannelStateEvent} (state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null}) | Disconnect the {@link Channel} from the current remote address. |
| {@code "close"} | {@link ChannelStateEvent} (state = {@link ChannelState#OPEN OPEN}, value = {@code false}) | Close the {@link Channel}. |
Other event types and conditions which were not addressed here will be ignored and discarded. Please note that there's no {@code "open"} in thetable. It is because a {@link Channel} is always open when it is createdby a {@link ChannelFactory}.
Please refer to the {@link ChannelHandler} and {@link ChannelPipeline}documentation to find out how an event flows in a pipeline and how to handle the event in your application. @apiviz.landmark @apiviz.composedOf com.facebook.presto.jdbc.internal.netty.channel.ChannelFuture
A {@link ChannelEvent} is handled by a series of {@link ChannelHandler}s in a {@link ChannelPipeline}.
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 {@link 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 {@link ChannelPipeline}, we call it a downstream event and say "an event goes downstream." (Please refer to the diagram in {@link 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 {@link InputStream#read(byte[])}, and downstream events are the request for outbound operations such as {@link OutputStream#write(byte[])}, {@link Socket#connect(SocketAddress)}, and {@link Socket#close()}.
| Event name | Event type and condition | Meaning | |
|---|---|---|---|
| {@code "messageReceived"} | {@link MessageEvent} | a message object (e.g. {@link ChannelBuffer}) was received from a remote peer | |
| {@code "exceptionCaught"} | {@link ExceptionEvent} | an exception was raised by an I/O thread or a {@link ChannelHandler} | |
| {@code "channelOpen"} | {@link ChannelStateEvent} (state = {@link ChannelState#OPEN OPEN}, value = {@code true}) | a {@link Channel} is open, but not bound nor connected | Be aware that this event is fired from within the Boss-Thread so you should not execute any heavy operation in there as it will block the dispatching to other workers! |
| {@code "channelClosed"} | {@link ChannelStateEvent} (state = {@link ChannelState#OPEN OPEN}, value = {@code false}) | a {@link Channel} was closed and all its related resources were released | |
| {@code "channelBound"} | {@link ChannelStateEvent} (state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress}) | a {@link Channel} is open and bound to a local address, but not connected | Be aware that this event is fired from within the Boss-Thread so you should not execute any heavy operation in there as it will block the dispatching to other workers! |
| {@code "channelUnbound"} | {@link ChannelStateEvent} (state = {@link ChannelState#BOUND BOUND}, value = {@code null}) | a {@link Channel} was unbound from the current local address | |
| {@code "channelConnected"} | {@link ChannelStateEvent} (state = {@link ChannelState#CONNECTED CONNECTED}, value = {@link SocketAddress}) | a {@link Channel} is open, bound to a local address, and connected to a remote address | |
| {@code "writeComplete"} | {@link WriteCompletionEvent} | something has been written to a remote peer | |
| {@code "channelDisconnected"} | {@link ChannelStateEvent} (state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null}) | a {@link Channel} was disconnected from its remote peer | |
| {@code "channelInterestChanged"} | {@link ChannelStateEvent} (state = {@link ChannelState#INTEREST_OPS INTEREST_OPS}, no value) | a {@link Channel}'s {@link Channel#getInterestOps() interestOps} was changed |
These two additional event types are used only for a parent channel which can have a child channel (e.g. {@link ServerSocketChannel}).
| Event name | Event type and condition | Meaning |
|---|---|---|
| {@code "childChannelOpen"} | {@link ChildChannelStateEvent} ( {@code childChannel.isOpen() = true}) | a child {@link Channel} was open (e.g. a server channel accepted a connection.) |
| {@code "childChannelClosed"} | {@link ChildChannelStateEvent} ( {@code childChannel.isOpen() = false}) | a child {@link Channel} was closed (e.g. the accepted connection was closed.) |
| Event name | Event type and condition | Meaning |
|---|---|---|
| {@code "write"} | {@link MessageEvent} | Send a message to the {@link Channel}. |
| {@code "bind"} | {@link ChannelStateEvent} (state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress}) | Bind the {@link Channel} to the specified local address. |
| {@code "unbind"} | {@link ChannelStateEvent} (state = {@link ChannelState#BOUND BOUND}, value = {@code null}) | Unbind the {@link Channel} from the current local address. |
| {@code "connect"} | {@link ChannelStateEvent} (state = {@link ChannelState#CONNECTED CONNECTED}, value = {@link SocketAddress}) | Connect the {@link Channel} to the specified remote address. |
| {@code "disconnect"} | {@link ChannelStateEvent} (state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null}) | Disconnect the {@link Channel} from the current remote address. |
| {@code "close"} | {@link ChannelStateEvent} (state = {@link ChannelState#OPEN OPEN}, value = {@code false}) | Close the {@link Channel}. |
Other event types and conditions which were not addressed here will be ignored and discarded. Please note that there's no {@code "open"} in thetable. It is because a {@link Channel} is always open when it is createdby a {@link ChannelFactory}.
Please refer to the {@link ChannelHandler} and {@link ChannelPipeline}documentation to find out how an event flows in a pipeline and how to handle the event in your application. @apiviz.landmark @apiviz.composedOf io.netty.channel.ChannelFuture
| |
| |