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   * <td><strong>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!</strong></td>
75   * </tr>
76   * <tr>
77   * <td>{@code "channelClosed"}</td>
78   * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#OPEN OPEN}, value = {@code false})</td>
79   * <td>a {@link Channel} was closed and all its related resources were released</td>
80   * </tr>
81   * <tr>
82   * <td>{@code "channelBound"}</td>
83   * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress})</td>
84   * <td>a {@link Channel} is open and bound to a local address, but not connected.</td>
85   * <td><strong>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!</strong></td>
86   * </tr>
87   * <tr>
88   * <td>{@code "channelUnbound"}</td>
89   * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@code null})</td>
90   * <td>a {@link Channel} was unbound from the current local address</td>
91   * </tr>
92   * <tr>
93   * <td>{@code "channelConnected"}</td>
94   * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@link SocketAddress})</td>
95   * <td>a {@link Channel} is open, bound to a local address, and connected to a remote address</td>
96   * <td><strong>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!</strong></td>
97   * </tr>
98   * <tr>
99   * <td>{@code "writeComplete"}</td>
100  * <td>{@link WriteCompletionEvent}</td>
101  * <td>something has been written to a remote peer</td>
102  * </tr>
103  * <tr>
104  * <td>{@code "channelDisconnected"}</td>
105  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null})</td>
106  * <td>a {@link Channel} was disconnected from its remote peer</td>
107  * </tr>
108  * <tr>
109  * <td>{@code "channelInterestChanged"}</td>
110  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#INTEREST_OPS INTEREST_OPS}, no value)</td>
111  * <td>a {@link Channel}'s {@link Channel#getInterestOps() interestOps} was changed</td>
112  * </tr>
113  * </table>
114  * <p>
115  * These two additional event types are used only for a parent channel which
116  * can have a child channel (e.g. {@link ServerSocketChannel}).
117  * <p>
118  * <table border="1" cellspacing="0" cellpadding="6">
119  * <tr>
120  * <th>Event name</th><th>Event type and condition</th><th>Meaning</th>
121  * </tr>
122  * <tr>
123  * <td>{@code "childChannelOpen"}</td>
124  * <td>{@link ChildChannelStateEvent}<br/>({@code childChannel.isOpen() = true})</td>
125  * <td>a child {@link Channel} was open (e.g. a server channel accepted a connection.)</td>
126  * </tr>
127  * <tr>
128  * <td>{@code "childChannelClosed"}</td>
129  * <td>{@link ChildChannelStateEvent}<br/>({@code childChannel.isOpen() = false})</td>
130  * <td>a child {@link Channel} was closed (e.g. the accepted connection was closed.)</td>
131  * </tr>
132  * </table>
133  *
134  * <h4>Downstream events</h4>
135  *
136  * <table border="1" cellspacing="0" cellpadding="6">
137  * <tr>
138  * <th>Event name</th><th>Event type and condition</th><th>Meaning</th>
139  * </tr>
140  * <tr>
141  * <td>{@code "write"}</td>
142  * <td>{@link MessageEvent}</td><td>Send a message to the {@link Channel}.</td>
143  * </tr>
144  * <tr>
145  * <td>{@code "bind"}</td>
146  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress})</td>
147  * <td>Bind the {@link Channel} to the specified local address.</td>
148  * </tr>
149  * <tr>
150  * <td>{@code "unbind"}</td>
151  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@code null})</td>
152  * <td>Unbind the {@link Channel} from the current local address.</td>
153  * </tr>
154  * <tr>
155  * <td>{@code "connect"}</td>
156  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@link SocketAddress})</td>
157  * <td>Connect the {@link Channel} to the specified remote address.</td>
158  * </tr>
159  * <tr>
160  * <td>{@code "disconnect"}</td>
161  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null})</td>
162  * <td>Disconnect the {@link Channel} from the current remote address.</td>
163  * </tr>
164  * <tr>
165  * <td>{@code "close"}</td>
166  * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#OPEN OPEN}, value = {@code false})</td>
167  * <td>Close the {@link Channel}.</td>
168  * </tr>
169  * </table>
170  * <p>
171  * Other event types and conditions which were not addressed here will be
172  * ignored and discarded.  Please note that there's no {@code "open"} in the
173  * table.  It is because a {@link Channel} is always open when it is created
174  * by a {@link ChannelFactory}.
175  *
176  * <h3>Additional resources worth reading</h3>
177  * <p>
178  * Please refer to the {@link ChannelHandler} and {@link ChannelPipeline}
179  * documentation to find out how an event flows in a pipeline and how to handle
180  * the event in your application.
181  *
182  * @author <a href="http://www.jboss.org/netty/">The Netty Project</a>
183  * @author <a href="http://gleamynode.net/">Trustin Lee</a>
184  *
185  * @version $Rev: 2080 $, $Date: 2010-01-26 18:04:19 +0900 (Tue, 26 Jan 2010) $
186  *
187  * @apiviz.landmark
188  * @apiviz.composedOf org.jboss.netty.channel.ChannelFuture
189  */
190 public interface ChannelEvent {
191 
192     /**
193      * Returns the {@link Channel} which is associated with this event.
194      */
195     Channel getChannel();
196 
197     /**
198      * Returns the {@link ChannelFuture} which is associated with this event.
199      * If this event is an upstream event, this method will always return a
200      * {@link SucceededChannelFuture} because the event has occurred already.
201      * If this event is a downstream event (i.e. I/O request), the returned
202      * future will be notified when the I/O request succeeds or fails.
203      */
204     ChannelFuture getFuture();
205 }