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 nameEvent type and conditionMeaning
    "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 nameEvent type and conditionMeaning
    "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 nameEvent type and conditionMeaning
    "write" MessageEventSend 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 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.