View Javadoc

    1   /*
    2    * Copyright 2009 Red Hat, Inc.
    3    *
    4    * Red Hat licenses this file to you under the Apache License, version 2.0
    5    * (the "License"); you may not use this file except in compliance with the
    6    * License.  You may obtain a copy of the License at:
    7    *
    8    *    http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
    12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
    13   * License for the specific language governing permissions and limitations
    14   * under the License.
    15   */
    16  package org.jboss.netty.channel;
    17
    18  import java.io.InputStream;
    19  import java.io.OutputStream;
    20  import java.net.Socket;
    21  import java.net.SocketAddress;
    22
    23  import org.jboss.netty.buffer.ChannelBuffer;
    24  import org.jboss.netty.channel.socket.ServerSocketChannel;
    25
    26  /**
    27   * An I/O event or I/O request associated with a {@link Channel}.
    28   * <p>
    29   * A {@link ChannelEvent} is handled by a series of {@link ChannelHandler}s in
    30   * a {@link ChannelPipeline}.
    31   *
    32   * <h3>Upstream events and downstream events, and their interpretation</h3>
    33   * <p>
    34   * Every event is either an upstream event or a downstream event.
    35   * If an event flows forward from the first handler to the last handler in a
    36   * {@link ChannelPipeline}, we call it an upstream event and say <strong>"an
    37   * event goes upstream."</strong>  If an event flows backward from the last
    38   * handler to the first handler in a {@link ChannelPipeline}, we call it a
    39   * downstream event and say <strong>"an event goes downstream."</strong>
    40   * (Please refer to the diagram in {@link ChannelPipeline} for more explanation.)
    41   * <p>
    42   * When your server receives a message from a client, the event associated with
    43   * the received message is an upstream event.  When your server sends a message
    44   * or reply to the client, the event associated with the write request is a
    45   * downstream event.  The same rule applies for the client side.  If your client
    46   * sent a request to the server, it means your client triggered a downstream
    47   * event.  If your client received a response from the server, it means
    48   * your client will be notified with an upstream event.  Upstream events are
    49   * often the result of inbound operations such as {@link InputStream#read(byte[])},
    50   * and downstream events are the request for outbound operations such as
    51   * {@link OutputStream#write(byte[])}, {@link Socket#connect(SocketAddress)},
    52   * and {@link Socket#close()}.
    53   *
    54   * <h4>Upstream events</h4>
    55   *
    56   * <table border="1" cellspacing="0" cellpadding="6">
    57   * <tr>
    58   * <th>Event name</th></th><th>Event type and condition</th><th>Meaning</th>
    59   * </tr>
    60   * <tr>
    61   * <td>{@code "messageReceived"}</td>
    62   * <td>{@link MessageEvent}</td>
    63   * <td>a message object (e.g. {@link ChannelBuffer}) was received from a remote peer</td>
    64   * </tr>
    65   * <tr>
    66   * <td>{@code "exceptionCaught"}</td>
    67   * <td>{@link ExceptionEvent}</td>
    68   * <td>an exception was raised by an I/O thread or a {@link ChannelHandler}</td>
    69   * </tr>
    70   * <tr>
    71   * <td>{@code "channelOpen"}</td>
    72   * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#OPEN OPEN}, value = {@code true})</td>
    73   * <td>a {@link Channel} is open, but not bound nor connected</td>
    74   * </tr>
    75   * <tr>
    76   * <td>{@code "channelClosed"}</td>
    77   * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#OPEN OPEN}, value = {@code false})</td>
    78   * <td>a {@link Channel} was closed and all its related resources were released</td>
    79   * </tr>
    80   * <tr>
    81   * <td>{@code "channelBound"}</td>
    82   * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress})</td>
    83   * <td>a {@link Channel} is open and bound to a local address, but not connected</td>
    84   * </tr>
    85   * <tr>
    86   * <td>{@code "channelUnbound"}</td>
    87   * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@code null})</td>
    88   * <td>a {@link Channel} was unbound from the current local address</td>
    89   * </tr>
    90   * <tr>
    91   * <td>{@code "channelConnected"}</td>
    92   * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@link SocketAddress})</td>
    93   * <td>a {@link Channel} is open, bound to a local address, and connected to a remote address</td>
    94   * </tr>
    95   * <tr>
    96   * <td>{@code "writeComplete"}</td>
    97   * <td>{@link WriteCompletionEvent}</td>
    98   * <td>something has been written to a remote peer</td>
    99   * </tr>
    100  * <tr>
    101  * <td>{@code "channelDisconnected"}</td>
    102  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null})</td>
    103  * <td>a {@link Channel} was disconnected from its remote peer</td>
    104  * </tr>
    105  * <tr>
    106  * <td>{@code "channelInterestChanged"}</td>
    107  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#INTEREST_OPS INTEREST_OPS}, no value)</td>
    108  * <td>a {@link Channel}'s {@link Channel#getInterestOps() interestOps} was changed</td>
    109  * </tr>
    110  * </table>
    111  * <p>
    112  * These two additional event types are used only for a parent channel which
    113  * can have a child channel (e.g. {@link ServerSocketChannel}).
    114  * <p>
    115  * <table border="1" cellspacing="0" cellpadding="6">
    116  * <tr>
    117  * <th>Event name</th><th>Event type and condition</th><th>Meaning</th>
    118  * </tr>
    119  * <tr>
    120  * <td>{@code "childChannelOpen"}</td>
    121  * <td>{@link ChildChannelStateEvent}<br/>({@code childChannel.isOpen() = true})</td>
    122  * <td>a child {@link Channel} was open (e.g. a server channel accepted a connection.)</td>
    123  * </tr>
    124  * <tr>
    125  * <td>{@code "childChannelClosed"}</td>
    126  * <td>{@link ChildChannelStateEvent}<br/>({@code childChannel.isOpen() = false})</td>
    127  * <td>a child {@link Channel} was closed (e.g. the accepted connection was closed.)</td>
    128  * </tr>
    129  * </table>
    130  *
    131  * <h4>Downstream events</h4>
    132  *
    133  * <table border="1" cellspacing="0" cellpadding="6">
    134  * <tr>
    135  * <th>Event name</th><th>Event type and condition</th><th>Meaning</th>
    136  * </tr>
    137  * <tr>
    138  * <td>{@code "write"}</td>
    139  * <td>{@link MessageEvent}</td><td>Send a message to the {@link Channel}.</td>
    140  * </tr>
    141  * <tr>
    142  * <td>{@code "bind"}</td>
    143  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress})</td>
    144  * <td>Bind the {@link Channel} to the specified local address.</td>
    145  * </tr>
    146  * <tr>
    147  * <td>{@code "unbind"}</td>
    148  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@code null})</td>
    149  * <td>Unbind the {@link Channel} from the current local address.</td>
    150  * </tr>
    151  * <tr>
    152  * <td>{@code "connect"}</td>
    153  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@link SocketAddress})</td>
    154  * <td>Connect the {@link Channel} to the specified remote address.</td>
    155  * </tr>
    156  * <tr>
    157  * <td>{@code "disconnect"}</td>
    158  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null})</td>
    159  * <td>Disconnect the {@link Channel} from the current remote address.</td>
    160  * </tr>
    161  * <tr>
    162  * <td>{@code "close"}</td>
    163  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#OPEN OPEN}, value = {@code false})</td>
    164  * <td>Close the {@link Channel}.</td>
    165  * </tr>
    166  * </table>
    167  * <p>
    168  * Other event types and conditions which were not addressed here will be
    169  * ignored and discarded.  Please note that there's no {@code "open"} in the
    170  * table.  It is because a {@link Channel} is always open when it is created
    171  * by a {@link ChannelFactory}.
    172  *
    173  * <h3>Additional resources worth reading</h3>
    174  * <p>
    175  * Please refer to the {@link ChannelHandler} and {@link ChannelPipeline}
    176  * documentation to find out how an event flows in a pipeline and how to handle
    177  * the event in your application.
    178  *
    179  * @author <a href="http://www.jboss.org/netty/">The Netty Project</a>
    180  * @author <a href="http://gleamynode.net/">Trustin Lee</a>
    181  *
    182  * @version $Rev: 2080 $, $Date: 2010-01-26 18:04:19 +0900 (Tue, 26 Jan 2010) $
    183  *
    184  * @apiviz.landmark
    185  * @apiviz.composedOf org.jboss.netty.channel.ChannelFuture
    186  */
    187 public interface ChannelEvent {
    188
    189     /**
    190      * Returns the {@link Channel} which is associated with this event.
    191      */
    192     Channel getChannel();
    193
    194     /**
    195      * Returns the {@link ChannelFuture} which is associated with this event.
    196      * If this event is an upstream event, this method will always return a
    197      * {@link SucceededChannelFuture} because the event has occurred already.
    198      * If this event is a downstream event (i.e. I/O request), the returned
    199      * future will be notified when the I/O request succeeds or fails.
    200      */
    201     ChannelFuture getFuture();
    202 }