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

JavaDoc

Browse Source
This commit is contained in:
Trustin Lee 2008-09-01 14:29:17 +00:00
parent 781a93bd43
commit fefe10f2dd
4 changed files with 286 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -24,6 +24,23 @@ package org.jboss.netty.channel;
/**
* Handles or intercepts a downstream {@link ChannelEvent}, and fires a
* {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
* <p>
* A downstream event is an event which is supposed to be processed from the
* last handler to the first handler in the {@link ChannelPipeline}.
* For example, all I/O requests made by a user application are downstream
* events.
* <p>
* In most common use case of this interface is to intercept an I/O request
* such as {@link Channel#write(Object)} and {@link Channel#close()}.
*
* <h3>Thread safety</h3>
* <p>
* {@link #handleDownstream(ChannelHandlerContext, ChannelEvent) handleDownstream}
* may be invoked by more than one thread simultaneously. If the handler
* accesses a shared resource or stores stateful information, you might need
* proper synchronization in the handler implementation.
*
* @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com)
@ -33,5 +50,12 @@ package org.jboss.netty.channel;
* @apiviz.landmark
*/
public interface ChannelDownstreamHandler extends ChannelHandler {
/**
* Handles the specified downstream event.
*
* @param ctx the context object for this handler
* @param e the downstream event to process or intercept
*/
void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception;
}

13
src/main/java/org/jboss/netty/channel/ChannelHandler.java
View File

@ -23,6 +23,19 @@
package org.jboss.netty.channel;
/**
* Handles or intercepts a {@link ChannelEvent}, and fires a new, modified, or
* existing {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
* <p>
* This is a tag interface. There are two sub-interfaces which processes
* a received event actually, one for upstream events and the other for
* downstream events:
* <ul>
* <li>{@link ChannelUpstreamHandler} handles and intercepts
* a {@link ChannelEvent} fired by an I/O thread.</li>
* <li>{@link ChannelDownstreamHandler} handles and intercepts
* a {@link ChannelEvent} fired by a user via the methods in
* the {@link Channel} interface and the {@link Channels} utility class.</li>
* </ul>
*
* @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com)

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

@ -22,8 +22,56 @@
*/
package org.jboss.netty.channel;
import java.util.concurrent.Executor;
import org.jboss.netty.handler.execution.ExecutionHandler;
import org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor;
/**
* Handles or intercepts a upstream {@link ChannelEvent}, and fires a
* {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
* <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.
* <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
* generic way.
*
* <a name="thread_safety"></a>
* <h3>Thread safety</h3>
* <p>
* If there's no {@link ExecutionHandler} in the {@link ChannelPipeline},
* {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream}
* will be invoked sequentially by the same thread (i.e. an I/O thread).
* Please note that this doesn't necessarily mean that there's a dedicated
* thread per {@link Channel}; the I/O thread of some transport can serve more
* than one {@link Channel} (e.g. NIO transport), while the I/O thread of
* others can serve only one (e.g. OIO transport).
* <p>
* If an {@link ExecutionHandler} is added in the {@link ChannelPipeline},
* {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream}
* may be invoked by different threads at the same time, depending on what
* {@link Executor} implementation is used with the {@link ExecutionHandler}.
* <p>
* {@link OrderedMemoryAwareThreadPoolExecutor} is provided to guarantee the
* order of {@link ChannelEvent}s. It does not guarantee that the invocation
* will be made by the same thread for the same channel, but it does guarantee
* that the invocation will be made sequentially for the events of the same
* channel. For example, the events can be processed as depicted below:
*
* <pre>
* -----------------------------------&gt; Timeline -----------------------------------&gt;
*
* Thread X: --- Channel A (Event 1) --. .-- Channel B (Event 2) --- Channel B (Event 3) ---&gt;
* \ /
* X
* / \
* Thread Y: --- Channel B (Event 1) --' '-- Channel A (Event 2) --- Channel A (Event 3) ---&gt;
* </pre>
*
* @author The Netty Project (netty-dev@lists.jboss.org)
* @author Trustin Lee (tlee@redhat.com)
@ -33,5 +81,12 @@ package org.jboss.netty.channel;
* @apiviz.landmark
*/
public interface ChannelUpstreamHandler extends ChannelHandler {
/**
* Handles the specified upstream event.
*
* @param ctx the context object for this handler
* @param e the upstream event to process or intercept
*/
void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception;
}

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

@ -22,11 +22,122 @@
*/
package org.jboss.netty.channel;
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;
/**
* 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:
*
* <table border="1" cellspacing="0" cellpadding="6">
* <tr>
* <th>Handler method</th><th>Event type</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}</td>
* <td>a {@link Channel} is open, but not bound nor connected</td>
* </tr>
* <tr>
* <td>{@link #channelOpen(ChannelHandlerContext, ChannelStateEvent) channelOpen}</td>
* <td>{@link ChannelStateEvent}</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}</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}</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}</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}</td>
* <td>a {@link Channel} was disconnected from its remote peer</td>
* </tr>
* <tr>
* <td>{@link #channelUnbound(ChannelHandlerContext, ChannelStateEvent) channelUnbound}</td>
* <td>{@link ChannelStateEvent}</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}</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}).
* </p>
*
* <table border="1" cellspacing="0" cellpadding="6">
* <tr>
* <th>Handler method</th><th>Event type</th><th>Invoked when ...</th>
* </tr>
* <tr>
* <td>{@link #childChannelOpen(ChannelHandlerContext, ChildChannelStateEvent) childChannelOpen}</td>
* <td>{@link ChildChannelStateEvent}</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}</td>
* <td>a child {@link Channel} was closed (e.g. the accepted connection was closed.)</td>
* </tr>
* </table>
*
* <h3>Overriding {@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.
* However, please make sure that you call {@code super.handleUpstream()} so
* that other handler methods are invoked properly:
* </p>
* <pre>public class MyChannelHandler extends SimpleChannelHandler {
*
* public void handleUpstream(
* ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
*
* // Log all channel state changes.
* if (e instanceof ChannelStateEvent) {
* logger.info("Channel state changed: " + e);
* }
*
* <strong>super.handleUpstream(ctx, e);</strong>
* }
* }</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)
@ -38,6 +149,11 @@ public class SimpleChannelHandler implements ChannelUpstreamHandler {
private static final InternalLogger logger =
InternalLoggerFactory.getInstance(SimpleChannelHandler.class.getName());
/**
* {@inheritDoc} Down-casts the received upstream event into more
* meaningful sub-type event and calls an appropriate handler method with
* the down-casted event.
*/
public void handleUpstream(
ChannelHandlerContext ctx, ChannelEvent e) throws Exception {
@ -85,46 +201,19 @@ public class SimpleChannelHandler implements ChannelUpstreamHandler {
}
}
public void channelBound(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
public void channelClosed(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
public void channelConnected(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
public void channelInterestChanged(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
public void channelDisconnected(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
public void channelOpen(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
public void channelUnbound(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
/**
* Invoked when a message object (e.g. {@link ChannelBuffer}) was received
* from a remote peer.
*/
public void messageReceived(
ChannelHandlerContext ctx, MessageEvent e) throws Exception {
ctx.sendUpstream(e);
}
/**
* Invoked when an exception was raised by an I/O thread or a
* {@link ChannelHandler}.
*/
public void exceptionCaught(
ChannelHandlerContext ctx, ExceptionEvent e) throws Exception {
if (this == ctx.getPipeline().getLast()) {
@ -135,13 +224,81 @@ public class SimpleChannelHandler implements ChannelUpstreamHandler {
ctx.sendUpstream(e);
}
public void childChannelClosed(
ChannelHandlerContext ctx, ChildChannelStateEvent e) throws Exception {
/**
* Invoked when a {@link Channel} is open, but not bound nor connected.
*/
public void channelOpen(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
/**
* Invoked when a {@link Channel} is open and bound to a local address,
* but not connected.
*/
public void channelBound(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
/**
* Invoked when a {@link Channel} is open, bound to a local address, and
* connected to a remote address.
*/
public void channelConnected(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
/**
* Invoked when a {@link Channel}'s {@link Channel#getInterestOps() interestOps}
* was changed.
*/
public void channelInterestChanged(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
/**
* Invoked when a {@link Channel} was disconnected from its remote peer.
*/
public void channelDisconnected(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
/**
* Invoked when a {@link Channel} was unbound from the current local address.
*/
public void channelUnbound(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
/**
* Invoked when a {@link Channel} was closed and all its related resources
* were released.
*/
public void channelClosed(
ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
/**
* Invoked when a child {@link Channel} was open.
* (e.g. a server channel accepted a connection)
*/
public void childChannelOpen(
ChannelHandlerContext ctx, ChildChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
/**
* Invoked when a child {@link Channel} was closed.
* (e.g. the accepted connection was closed)
*/
public void childChannelClosed(
ChannelHandlerContext ctx, ChildChannelStateEvent e) throws Exception {
ctx.sendUpstream(e);
}
}