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 }