1 /*
2 * Copyright 2012 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the 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 org.jboss.netty.buffer.ChannelBuffer;
19 import org.jboss.netty.channel.socket.ServerSocketChannel;
20
21 import java.io.InputStream;
22 import java.io.OutputStream;
23 import java.net.Socket;
24 import java.net.SocketAddress;
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>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 I/O thread. You should never
75 * execute any heavy operation in there as it will block the dispatching to other workers!</strong></td>
76 * </tr>
77 * <tr>
78 * <td>{@code "channelClosed"}</td>
79 * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#OPEN OPEN}, value = {@code false})</td>
80 * <td>a {@link Channel} was closed and all its related resources were released</td>
81 * </tr>
82 * <tr>
83 * <td>{@code "channelBound"}</td>
84 * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress})</td>
85 * <td>a {@link Channel} is open and bound to a local address, but not connected.</td>
86 * <td><strong>Be aware that this event is fired from within the I/O thread. You should never
87 * execute any heavy operation in there as it will block the dispatching to other workers!</strong></td>
88 * </tr>
89 * <tr>
90 * <td>{@code "channelUnbound"}</td>
91 * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@code null})</td>
92 * <td>a {@link Channel} was unbound from the current local address</td>
93 * </tr>
94 * <tr>
95 * <td>{@code "channelConnected"}</td>
96 * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value =
97 * {@link SocketAddress})</td>
98 * <td>a {@link Channel} is open, bound to a local address, and connected to a remote address</td>
99 * <td><strong>Be aware that this event is fired from within the I/O thread. You should never
100 * execute any heavy operation in there as it will block the dispatching to other workers!</strong></td>
101 * </tr>
102 * <tr>
103 * <td>{@code "writeComplete"}</td>
104 * <td>{@link WriteCompletionEvent}</td>
105 * <td>something has been written to a remote peer</td>
106 * </tr>
107 * <tr>
108 * <td>{@code "channelDisconnected"}</td>
109 * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null})</td>
110 * <td>a {@link Channel} was disconnected from its remote peer</td>
111 * </tr>
112 * <tr>
113 * <td>{@code "channelInterestChanged"}</td>
114 * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#INTEREST_OPS INTEREST_OPS}, no value)</td>
115 * <td>a {@link Channel}'s {@link Channel#getInterestOps() interestOps} was changed</td>
116 * </tr>
117 * </table>
118 * <p>
119 * These two additional event types are used only for a parent channel which
120 * can have a child channel (e.g. {@link ServerSocketChannel}).
121 * <p>
122 * <table border="1" cellspacing="0" cellpadding="6">
123 * <tr>
124 * <th>Event name</th><th>Event type and condition</th><th>Meaning</th>
125 * </tr>
126 * <tr>
127 * <td>{@code "childChannelOpen"}</td>
128 * <td>{@link ChildChannelStateEvent}<br/>({@code childChannel.isOpen() = true})</td>
129 * <td>a child {@link Channel} was open (e.g. a server channel accepted a connection.)</td>
130 * </tr>
131 * <tr>
132 * <td>{@code "childChannelClosed"}</td>
133 * <td>{@link ChildChannelStateEvent}<br/>({@code childChannel.isOpen() = false})</td>
134 * <td>a child {@link Channel} was closed (e.g. the accepted connection was closed.)</td>
135 * </tr>
136 * </table>
137 *
138 * <h4>Downstream events</h4>
139 *
140 * <table border="1" cellspacing="0" cellpadding="6">
141 * <tr>
142 * <th>Event name</th><th>Event type and condition</th><th>Meaning</th>
143 * </tr>
144 * <tr>
145 * <td>{@code "write"}</td>
146 * <td>{@link MessageEvent}</td><td>Send a message to the {@link Channel}.</td>
147 * </tr>
148 * <tr>
149 * <td>{@code "bind"}</td>
150 * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress})</td>
151 * <td>Bind the {@link Channel} to the specified local address.</td>
152 * </tr>
153 * <tr>
154 * <td>{@code "unbind"}</td>
155 * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@code null})</td>
156 * <td>Unbind the {@link Channel} from the current local address.</td>
157 * </tr>
158 * <tr>
159 * <td>{@code "connect"}</td>
160 * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value =
161 * {@link SocketAddress})</td>
162 * <td>Connect the {@link Channel} to the specified remote address.</td>
163 * </tr>
164 * <tr>
165 * <td>{@code "disconnect"}</td>
166 * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null})</td>
167 * <td>Disconnect the {@link Channel} from the current remote address.</td>
168 * </tr>
169 * <tr>
170 * <td>{@code "close"}</td>
171 * <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#OPEN OPEN}, value = {@code false})</td>
172 * <td>Close the {@link Channel}.</td>
173 * </tr>
174 * </table>
175 * <p>
176 * Other event types and conditions which were not addressed here will be
177 * ignored and discarded. Please note that there's no {@code "open"} in the
178 * table. It is because a {@link Channel} is always open when it is created
179 * by a {@link ChannelFactory}.
180 *
181 * <h3>Additional resources worth reading</h3>
182 * <p>
183 * Please refer to the {@link ChannelHandler} and {@link ChannelPipeline}
184 * documentation to find out how an event flows in a pipeline and how to handle
185 * the event in your application.
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 }