Package org.jboss.netty.channel

Interface ChannelEvent

All Known Subinterfaces:

ChannelStateEvent, ChildChannelStateEvent, ExceptionEvent, IdleStateEvent, MessageEvent, WriteCompletionEvent

All Known Implementing Classes:

DefaultChildChannelStateEvent, DefaultExceptionEvent, DefaultIdleStateEvent, DefaultWriteCompletionEvent, DownstreamChannelStateEvent, DownstreamMessageEvent, UpstreamChannelStateEvent, UpstreamMessageEvent

public interface ChannelEvent

An I/O event or I/O request associated with a Channel.

A ChannelEvent is handled by a series of ChannelHandlers 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 Type	Method	Description
Channel	getChannel()	Returns the Channel which is associated with this event.
ChannelFuture	getFuture()	Returns the ChannelFuture which is associated with this event.

Method Detail

getChannel

Channel getChannel()

Returns the Channel which is associated with this event.

getFuture

ChannelFuture getFuture()

Returns the ChannelFuture which is associated with this event. If this event is an upstream event, this method will always return a SucceededChannelFuture 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.