andreacavalli/netty5
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

* Reorganized JavaDoc content

Browse Source 
* Added more missing JavaDoc
This commit is contained in:
Trustin Lee 2008-09-02 13:20:03 +00:00
parent ed8651701d
commit f9778a8dad
11 changed files with 189 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
src/main/java/org/jboss/netty/channel/ChannelDownstreamHandler.java
View File

@ -70,8 +70,10 @@ import java.net.SocketAddress;
* </table>
* <p>
* Other event types and conditions which were not addressed here will be
* ignored and discarded. You also might want to refer to {@link SimpleChannelHandler}
* to see how a {@link ChannelEvent} is interpreted when going upstream.
* ignored and discarded. You also might want to refer to {@link ChannelUpstreamHandler}
* to see how a {@link ChannelEvent} is interpreted when going upstream. Also,
* please refer to {@link ChannelEvent} to understand the fundamental difference
* between a upstream event and a downstream event.
*
* <h3>Firing an event to the previous or next handler</h3>
* <p>

20
src/main/java/org/jboss/netty/channel/ChannelEvent.java
View File

@ -30,6 +30,26 @@ package org.jboss.netty.channel;
* the event belongs to. Once an event is sent to a {@link ChannelPipeline},
* it is handled by a list of {@link ChannelHandler}s.
*
* <h3>Upstream and downstream events, and their interpretation</h3>
* <p>
* If an event flows from the first handler to the last handler, we call it a
* upstream event and say "an event goes upstream". If an event flows from
* the last handler to the first handler, we call it a downstream event and say
* "an event goes downstream".
* <p>
* A {@link ChannelEvent} is interpreted differently by a {@link ChannelHandler}
* depending on whether the event is a upstream event or a downstream event.
* A upstream event represents the notification of what happened in the past.
* By contrast, a downstream event represents the request of what should happen
* in the future. For example, a {@link MessageEvent} represents the
* notification of a received message when it goes upstream, while it
* represents the request of writing a message when it goes downstream.
* <p>
* Please refer to the documentation of {@link ChannelHandler} and its sub-types
* ({@link ChannelUpstreamHandler} for upstream events and
* {@link ChannelDownstreamHandler} for downstream events) to find out how
* a {@link ChannelEvent} is interpreted depending on the type of the handler.
*
* @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com)
*

15
src/main/java/org/jboss/netty/channel/ChannelSink.java
View File

@ -24,6 +24,11 @@ package org.jboss.netty.channel;
/**
* Receives and processes the terminal downstream {@link ChannelEvent}s.
* <p>
* A {@link ChannelSink} is an internal component which is supposed to be
* implemented by a transport provider. Most users will not see this type
* in their code.
*
* @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com)
@ -33,6 +38,16 @@ package org.jboss.netty.channel;
* @apiviz.uses org.jboss.netty.channel.ChannelPipeline - - sends events upstream
*/
public interface ChannelSink {
/**
* Invoked by {@link ChannelPipeline} when a downstream {@link ChannelEvent}
* has reached its terminal (the head of the pipeline).
*/
void eventSunk(ChannelPipeline pipeline, ChannelEvent e) throws Exception;
/**
* Invoked by {@link ChannelPipeline} when an exception was raised while
* one of its {@link ChannelHandler}s process a {@link ChannelEvent}.
*/
void exceptionCaught(ChannelPipeline pipeline, ChannelEvent e, ChannelPipelineException cause) throws Exception;
}

2
src/main/java/org/jboss/netty/channel/ChannelState.java
View File

@ -80,7 +80,7 @@ import java.net.SocketAddress;
* </table>
* <p>
* To see how a {@link ChannelEvent} is interpreted further, please refer to
* {@link SimpleChannelHandler} and {@link ChannelDownstreamHandler}.
* {@link ChannelUpstreamHandler} and {@link ChannelDownstreamHandler}.
*
*
* @author The Netty Project (netty-dev@lists.jboss.org)

14
src/main/java/org/jboss/netty/channel/ChannelStateEvent.java
View File

@ -24,6 +24,10 @@ package org.jboss.netty.channel;
/**
* A {@link ChannelEvent} which represents the change of the {@link Channel}
* state. It can mean the notification of a change or the request for a
* change, depending on whether it is a upstream event or a downstream event
* respectively.
*
* @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com)
@ -33,6 +37,16 @@ package org.jboss.netty.channel;
* @apiviz.has org.jboss.netty.channel.ChannelState
*/
public interface ChannelStateEvent extends ChannelEvent {
/**
* Returns the changed property of the {@link Channel}.
*/
ChannelState getState();
/**
* Returns the value of the changed property of the {@link Channel}.
* Please refer to {@link ChannelState} documentation to find out the
* allowed values for each property.
*/
Object getValue();
}

89
src/main/java/org/jboss/netty/channel/ChannelUpstreamHandler.java
View File

@ -22,8 +22,11 @@
*/
package org.jboss.netty.channel;
import java.net.SocketAddress;
import java.util.concurrent.Executor;
import org.jboss.netty.buffer.ChannelBuffer;
import org.jboss.netty.channel.socket.ServerSocketChannel;
import org.jboss.netty.handler.execution.ExecutionHandler;
import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
@ -35,11 +38,88 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
* <p>
* A upstream event is an event which is supposed to be processed from the
* first handler to the last handler in the {@link ChannelPipeline}.
* For example, all events fired by an I/O thread are upstream events.
* For example, all events fired by an I/O thread are upstream events, and
* they have the following meaning:
*
* <table border="1" cellspacing="0" cellpadding="6">
* <tr>
* <th>Event name</th></th><th>Event type and condition</th><th>Meaning</th>
* </tr>
* <tr>
* <td>{@code "messageReceived"}</td>
* <td>{@link MessageEvent}</td>
* <td>a message object (e.g. {@link ChannelBuffer}) was received from a remote peer</td>
* </tr>
* <tr>
* <td>{@code "exceptionCaught"}</td>
* <td>{@link ExceptionEvent}</td>
* <td>an exception was raised by an I/O thread or a {@link ChannelHandler}</td>
* </tr>
* <tr>
* <td>{@code "channelOpen"}</td>
* <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#OPEN OPEN}, value = {@code true})</td>
* <td>a {@link Channel} is open, but not bound nor connected</td>
* </tr>
* <tr>
* <td>{@code "channelClosed"}</td>
* <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#OPEN OPEN}, value = {@code false})</td>
* <td>a {@link Channel} was closed and all its related resources were released</td>
* </tr>
* <tr>
* <td>{@code "channelBound"}</td>
* <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@link SocketAddress})</td>
* <td>a {@link Channel} is open and bound to a local address, but not connected</td>
* </tr>
* <tr>
* <td>{@code "channelUnbound"}</td>
* <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#BOUND BOUND}, value = {@code null})</td>
* <td>a {@link Channel} was unbound from the current local address</td>
* </tr>
* <tr>
* <td>{@code "channelConnected"}</td>
* <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@link SocketAddress})</td>
* <td>a {@link Channel} is open, bound to a local address, and connected to a remote address</td>
* </tr>
* <tr>
* <td>{@code "channelDisconnected"}</td>
* <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#CONNECTED CONNECTED}, value = {@code null})</td>
* <td>a {@link Channel} was disconnected from its remote peer</td>
* </tr>
* <tr>
* <td>{@code "channelInterestChanged"}</td>
* <td>{@link ChannelStateEvent}<br/>(state = {@link ChannelState#INTEREST_OPS INTEREST_OPS}, value = {@code int}</td>
* <td>a {@link Channel}'s {@link Channel#getInterestOps() interestOps} was changed</td>
* </tr>
* </table>
* <p>
* In most cases, you should use a {@link SimpleChannelHandler} to implement
* this interface more easily. You might want to implement this interface
* directly though, when you want to handle various types of events in more
* These two additional event types are used only for a parent channel which
* can have a child channel (e.g. {@link ServerSocketChannel}).
*
* <table border="1" cellspacing="0" cellpadding="6">
* <tr>
* <th>Event name</th><th>Event type and condition</th><th>Meaning</th>
* </tr>
* <tr>
* <td>{@code "childChannelOpen"}</td>
* <td>{@link ChildChannelStateEvent}<br/>({@code childChannel.isOpen() = true})</td>
* <td>a child {@link Channel} was open (e.g. a server channel accepted a connection.)</td>
* </tr>
* <tr>
* <td>{@code "childChannelClosed"}</td>
* <td>{@link ChildChannelStateEvent}<br/>({@code childChannel.isOpen() = false})</td>
* <td>a child {@link Channel} was closed (e.g. the accepted connection was closed.)</td>
* </tr>
* </table>
* <p>
* You also might want to refer to {@link ChannelDownstreamHandler} to see
* how a {@link ChannelEvent} is interpreted when going downstream. Also,
* please refer to {@link ChannelEvent} to understand the fundamental difference
* between a upstream event and a downstream event.
* <p>
* In most cases, you will get to use a {@link SimpleChannelHandler} to
* implement a upstream handler because it provides an individual handler
* method for each event type. You might want to implement this interface
* directly though if you want to handle various types of events in more
* generic way.
*
* <h3>Firing an event to the next or previous handler</h3>
@ -68,7 +148,6 @@ import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
* You will also find various helper methods in {@link Channels} to be useful
* to generate and fire an artificial or manipulated event.
*
* <a name="thread_safety"></a>
* <h3>Thread safety</h3>
* <p>
* If there's no {@link ExecutionHandler} in the {@link ChannelPipeline},

32
src/main/java/org/jboss/netty/channel/Channels.java
View File

@ -156,9 +156,9 @@ public class Channels {
// event emission methods
/**
* Fires a {@link SimpleChannelHandler channelOpen} event to the specified
* Fires a {@link ChannelUpstreamHandler channelOpen} event to the specified
* {@link Channel}. If the specified channel has a parent, a
* {@link SimpleChannelHandler childChannelOpen} event will be fired too.
* {@link ChannelUpstreamHandler childChannelOpen} event will be fired too.
*/
public static void fireChannelOpen(Channel channel) {
if (channel.getParent() != null) {
@ -171,9 +171,9 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler channelOpen} event to the specified
* Fires a {@link ChannelUpstreamHandler channelOpen} event to the specified
* {@link ChannelHandlerContext}. Please note that this method doesn't
* fire a {@link SimpleChannelHandler childChannelOpen} event unlike
* fire a {@link ChannelUpstreamHandler childChannelOpen} event unlike
* {@link #fireChannelOpen(Channel)} method.
*/
public static void fireChannelOpen(
@ -185,7 +185,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler channelBound} event to the specified
* Fires a {@link ChannelUpstreamHandler channelBound} event to the specified
* {@link Channel}.
*
* @param localAddress
@ -199,7 +199,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler channelBound} event to the specified
* Fires a {@link ChannelUpstreamHandler channelBound} event to the specified
* {@link Channel}.
*
* @param localAddress
@ -214,7 +214,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler channelConnected} event to the
* Fires a {@link ChannelUpstreamHandler channelConnected} event to the
* specified {@link Channel}.
*
* @param remoteAddress
@ -228,7 +228,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler channelConnected} event to the
* Fires a {@link ChannelUpstreamHandler channelConnected} event to the
* specified {@link ChannelHandlerContext}.
*
* @param remoteAddress
@ -243,7 +243,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler messageReceived} event to the
* Fires a {@link ChannelUpstreamHandler messageReceived} event to the
* specified {@link Channel}.
*
* @param message the received message
@ -253,7 +253,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler messageReceived} event to the
* Fires a {@link ChannelUpstreamHandler messageReceived} event to the
* specified {@link Channel}.
*
* @param message the received message
@ -268,7 +268,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler messageReceived} event to the
* Fires a {@link ChannelUpstreamHandler messageReceived} event to the
* specified {@link ChannelHandlerContext}.
*
* @param message the received message
@ -280,7 +280,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler messageReceived} event to the
* Fires a {@link ChannelUpstreamHandler messageReceived} event to the
* specified {@link ChannelHandlerContext}.
*
* @param message the received message
@ -295,7 +295,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler channelInterestChanged} event to the
* Fires a {@link ChannelUpstreamHandler channelInterestChanged} event to the
* specified {@link Channel}.
*
* @param interestOps the new interestOps
@ -309,7 +309,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler channelInterestChanged} event to the
* Fires a {@link ChannelUpstreamHandler channelInterestChanged} event to the
* specified {@link ChannelHandlerContext}.
*
* @param interestOps the new interestOps
@ -325,7 +325,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler channelDisconnected} event to the
* Fires a {@link ChannelUpstreamHandler channelDisconnected} event to the
* specified {@link Channel}.
*/
public static void fireChannelDisconnected(Channel channel) {
@ -336,7 +336,7 @@ public class Channels {
}
/**
* Fires a {@link SimpleChannelHandler channelDisconnected} event to the
* Fires a {@link ChannelUpstreamHandler channelDisconnected} event to the
* specified {@link ChannelHandlerContext}.
*/
public static void fireChannelDisconnected(

6
src/main/java/org/jboss/netty/channel/ChildChannelStateEvent.java
View File

@ -23,6 +23,8 @@
package org.jboss.netty.channel;
/**
* A {@link ChannelEvent} which represents the notification of the state of
* a child {@link Channel}. This event is allowed to go upstream only.
*
* @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com)
@ -30,5 +32,9 @@ package org.jboss.netty.channel;
* @version $Rev$, $Date$
*/
public interface ChildChannelStateEvent extends ChannelEvent {
/**
* Returns the child {@link Channel} whose state has been changed.
*/
Channel getChildChannel();
}

7
src/main/java/org/jboss/netty/channel/ExceptionEvent.java
View File

@ -23,6 +23,9 @@
package org.jboss.netty.channel;
/**
* A {@link ChannelEvent} which represents the notification of an exception
* raised by a {@link ChannelHandler} or an I/O thread. This event is allowed
* to go upstream only.
*
* @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com)
@ -30,5 +33,9 @@ package org.jboss.netty.channel;
* @version $Rev$, $Date$
*/
public interface ExceptionEvent extends ChannelEvent {
/**
* Returns the raised exception.
*/
Throwable getCause();
}

15
src/main/java/org/jboss/netty/channel/MessageEvent.java
View File

@ -25,6 +25,10 @@ package org.jboss.netty.channel;
import java.net.SocketAddress;
/**
* A {@link ChannelEvent} which represents the transmission or reception of a
* message. It can mean the notification of a received message or the request
* for writing a message, depending on whether it is a upstream event or a
* downstream event respectively.
*
* @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com)
@ -32,6 +36,17 @@ import java.net.SocketAddress;
* @version $Rev$, $Date$
*/
public interface MessageEvent extends ChannelEvent {
/**
* Returns the message.
*/
Object getMessage();
/**
* Returns the remote address.
*
* @return the remote address. {@code null} if the remote address is
* same with the default remote address returned by {@link Channel#getRemoteAddress()}.
*/
SocketAddress getRemoteAddress();
}

96
src/main/java/org/jboss/netty/channel/SimpleChannelHandler.java
View File

@ -22,95 +22,20 @@
*/
package org.jboss.netty.channel;
import java.net.SocketAddress;
import org.jboss.netty.buffer.ChannelBuffer;
import org.jboss.netty.channel.socket.ServerSocketChannel;
import org.jboss.netty.logging.InternalLogger;
import org.jboss.netty.logging.InternalLoggerFactory;
/**
* A generic {@link ChannelUpstreamHandler} implementation that satisfies most
* use cases. This handler down-casts the received upstream event into more
* meaningful sub-type event and calls an appropriate handler method with the
* down-casted event. The following table shows the provided handler methods:
* A {@link ChannelUpstreamHandler} which provides an individual handler method
* for each event type. This handler down-casts the received upstream event
* into more meaningful sub-type event and calls an appropriate handler method
* with the down-cast event. The names of the methods are identical to the
* upstream event names, as introduced in the {@link ChannelUpstreamHandler}
* documentation.
*
* <table border="1" cellspacing="0" cellpadding="6">
* <tr>
* <th>Handler method</th><th>Event type and condition</th><th>Invoked when ...</th>
* </tr>
* <tr>
* <td>{@link #messageReceived(ChannelHandlerContext, MessageEvent) messageReceived}</td>
* <td>{@link MessageEvent}</td>
* <td>a message object (e.g. {@link ChannelBuffer}) was received from a remote peer</td>
* </tr>
* <tr>
* <td>{@link #exceptionCaught(ChannelHandlerContext, ExceptionEvent) exceptionCaught}</td>
* <td>{@link ExceptionEvent}</td>
* <td>an exception was raised by an I/O thread or a {@link ChannelHandler}</td>
* </tr>
* <tr>
* <td>{@link #channelOpen(ChannelHandlerContext, ChannelStateEvent) channelOpen}</td>
* <td>{@link ChannelStateEvent}<br/>(state={@link ChannelState#OPEN}, value={@code true})</td>
* <td>a {@link Channel} is open, but not bound nor connected</td>
* </tr>
* <tr>
* <td>{@link #channelBound(ChannelHandlerContext, ChannelStateEvent) channelBound}</td>
* <td>{@link ChannelStateEvent}<br/>(state={@link ChannelState#BOUND}, value={@link SocketAddress})</td>
* <td>a {@link Channel} is open and bound to a local address, but not connected</td>
* </tr>
* <tr>
* <td>{@link #channelConnected(ChannelHandlerContext, ChannelStateEvent) channelConnected}</td>
* <td>{@link ChannelStateEvent}<br/>(state={@link ChannelState#CONNECTED}, value={@link SocketAddress})</td>
* <td>a {@link Channel} is open, bound to a local address, and connected to a remote address</td>
* </tr>
* <tr>
* <td>{@link #channelInterestChanged(ChannelHandlerContext, ChannelStateEvent) channelInterestedChanged}</td>
* <td>{@link ChannelStateEvent}<br/>(state={@link ChannelState#INTEREST_OPS}, value=an integer)</td>
* <td>a {@link Channel}'s {@link Channel#getInterestOps() interestOps} was changed</td>
* </tr>
* <tr>
* <td>{@link #channelDisconnected(ChannelHandlerContext, ChannelStateEvent) channelDisconnected}</td>
* <td>{@link ChannelStateEvent}<br/>(state={@link ChannelState#CONNECTED}, value={@code null})</td>
* <td>a {@link Channel} was disconnected from its remote peer</td>
* </tr>
* <tr>
* <td>{@link #channelUnbound(ChannelHandlerContext, ChannelStateEvent) channelUnbound}</td>
* <td>{@link ChannelStateEvent}<br/>(state={@link ChannelState#BOUND}, value={@code null})</td>
* <td>a {@link Channel} was unbound from the current local address</td>
* </tr>
* <tr>
* <td>{@link #channelClosed(ChannelHandlerContext, ChannelStateEvent) channelClosed}</td>
* <td>{@link ChannelStateEvent}<br/>(state={@link ChannelState#OPEN}, value={@code false})</td>
* <td>a {@link Channel} was closed and all its related resources were released</td>
* </tr>
* </table>
*
* <p>
* These two handler methods are used only for a parent channel which can have
* a child channel (e.g. {@link ServerSocketChannel}).
*
* <table border="1" cellspacing="0" cellpadding="6">
* <tr>
* <th>Handler method</th><th>Event type and condition</th><th>Invoked when ...</th>
* </tr>
* <tr>
* <td>{@link #childChannelOpen(ChannelHandlerContext, ChildChannelStateEvent) childChannelOpen}</td>
* <td>{@link ChildChannelStateEvent}<br/>({@code childChannel.isOpen() = true})</td>
* <td>a child {@link Channel} was open (e.g. a server channel accepted a connection.)</td>
* </tr>
* <tr>
* <td>{@link #childChannelClosed(ChannelHandlerContext, ChildChannelStateEvent) childChannelClosed}</td>
* <td>{@link ChildChannelStateEvent}<br/>({@code childChannel.isOpen() = false})</td>
* <td>a child {@link Channel} was closed (e.g. the accepted connection was closed.)</td>
* </tr>
* </table>
* <p>
* You also might want to refer to {@link ChannelDownstreamHandler} to see
* how a {@link ChannelEvent} is interpreted when going downstream.
*
* <h3>Overriding {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream} method</h3>
* <h3>Overriding the {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream} method</h3>
* <p>
* You can override the {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream}
* method just like you can do with other {@link ChannelUpstreamHandler}s.
@ -131,13 +56,6 @@ import org.jboss.netty.logging.InternalLoggerFactory;
* }
* }</pre>
*
* <h3>Thread safety</h3>
* <p>
* The same rule with {@link ChannelUpstreamHandler} is applied. Please refer
* to the '<a href="ChannelUpstreamHandler.html#thread_safety">thread safety</a>'
* section.
*
*
* @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com)
*