diff --git a/src/main/java/org/jboss/netty/handler/timeout/DefaultIdleStateEvent.java b/src/main/java/org/jboss/netty/handler/timeout/DefaultIdleStateEvent.java index d60086748a..7e97b43184 100644 --- a/src/main/java/org/jboss/netty/handler/timeout/DefaultIdleStateEvent.java +++ b/src/main/java/org/jboss/netty/handler/timeout/DefaultIdleStateEvent.java @@ -32,6 +32,8 @@ import org.jboss.netty.channel.Channel; import org.jboss.netty.channel.ChannelFuture; /** + * The default {@link IdleStateEvent} implementation. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ @@ -42,6 +44,9 @@ public class DefaultIdleStateEvent implements IdleStateEvent { private final IdleState state; private final long lastActivityTimeMillis; + /** + * Creates a new instance. + */ public DefaultIdleStateEvent( Channel channel, IdleState state, long lastActivityTimeMillis) { if (channel == null) { diff --git a/src/main/java/org/jboss/netty/handler/timeout/IdleState.java b/src/main/java/org/jboss/netty/handler/timeout/IdleState.java index a7a5eae095..30b564b9bb 100644 --- a/src/main/java/org/jboss/netty/handler/timeout/IdleState.java +++ b/src/main/java/org/jboss/netty/handler/timeout/IdleState.java @@ -22,14 +22,27 @@ */ package org.jboss.netty.handler.timeout; +import org.jboss.netty.channel.Channel; + /** + * An {@link Enum} that represents the idle state of a {@link Channel}. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ */ public enum IdleState { + /** + * No data was received for a while. + */ READER_IDLE, + /** + * No data was sent for a while. + */ WRITER_IDLE, + /** + * No data was either received or sent for a while. + */ ALL_IDLE; } diff --git a/src/main/java/org/jboss/netty/handler/timeout/IdleStateAwareChannelHandler.java b/src/main/java/org/jboss/netty/handler/timeout/IdleStateAwareChannelHandler.java index 005956d4c7..a496fae64d 100644 --- a/src/main/java/org/jboss/netty/handler/timeout/IdleStateAwareChannelHandler.java +++ b/src/main/java/org/jboss/netty/handler/timeout/IdleStateAwareChannelHandler.java @@ -22,11 +22,15 @@ */ package org.jboss.netty.handler.timeout; +import org.jboss.netty.channel.Channel; import org.jboss.netty.channel.ChannelEvent; import org.jboss.netty.channel.ChannelHandlerContext; import org.jboss.netty.channel.SimpleChannelHandler; /** + * An extended {@link SimpleChannelHandler} that adds the handler method for + * an {@link IdleStateEvent}. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ @@ -43,6 +47,9 @@ public class IdleStateAwareChannelHandler extends SimpleChannelHandler { } } + /** + * Invoked when a {@link Channel} has been idle for a while. + */ public void channelIdle(ChannelHandlerContext ctx, IdleStateEvent e) { ctx.sendUpstream(e); } diff --git a/src/main/java/org/jboss/netty/handler/timeout/IdleStateAwareChannelUpstreamHandler.java b/src/main/java/org/jboss/netty/handler/timeout/IdleStateAwareChannelUpstreamHandler.java index 84100bd63a..e749c5e267 100644 --- a/src/main/java/org/jboss/netty/handler/timeout/IdleStateAwareChannelUpstreamHandler.java +++ b/src/main/java/org/jboss/netty/handler/timeout/IdleStateAwareChannelUpstreamHandler.java @@ -22,11 +22,15 @@ */ package org.jboss.netty.handler.timeout; +import org.jboss.netty.channel.Channel; import org.jboss.netty.channel.ChannelEvent; import org.jboss.netty.channel.ChannelHandlerContext; import org.jboss.netty.channel.SimpleChannelUpstreamHandler; /** + * An extended {@link SimpleChannelUpstreamHandler} that adds the handler method + * for an {@link IdleStateEvent}. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ @@ -43,6 +47,9 @@ public class IdleStateAwareChannelUpstreamHandler extends SimpleChannelUpstreamH } } + /** + * Invoked when a {@link Channel} has been idle for a while. + */ public void channelIdle(ChannelHandlerContext ctx, IdleStateEvent e) { ctx.sendUpstream(e); } diff --git a/src/main/java/org/jboss/netty/handler/timeout/IdleStateEvent.java b/src/main/java/org/jboss/netty/handler/timeout/IdleStateEvent.java index c50be88a9a..60c4d55efa 100644 --- a/src/main/java/org/jboss/netty/handler/timeout/IdleStateEvent.java +++ b/src/main/java/org/jboss/netty/handler/timeout/IdleStateEvent.java @@ -22,14 +22,25 @@ */ package org.jboss.netty.handler.timeout; +import org.jboss.netty.channel.Channel; import org.jboss.netty.channel.ChannelEvent; /** + * A {@link ChannelEvent} that is triggered when a {@link Channel} has been idle + * for a while. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ */ public interface IdleStateEvent extends ChannelEvent { + /** + * Returns the detailed idle state. + */ IdleState getState(); + + /** + * Returns the last time when I/O occurred in milliseconds. + */ long getLastActivityTimeMillis(); } diff --git a/src/main/java/org/jboss/netty/handler/timeout/IdleStateHandler.java b/src/main/java/org/jboss/netty/handler/timeout/IdleStateHandler.java index 397d50f19b..4e7eb64821 100644 --- a/src/main/java/org/jboss/netty/handler/timeout/IdleStateHandler.java +++ b/src/main/java/org/jboss/netty/handler/timeout/IdleStateHandler.java @@ -26,6 +26,7 @@ import static org.jboss.netty.channel.Channels.*; import java.util.concurrent.TimeUnit; +import org.jboss.netty.channel.Channel; import org.jboss.netty.channel.ChannelHandlerContext; import org.jboss.netty.channel.ChannelPipelineCoverage; import org.jboss.netty.channel.ChannelStateEvent; @@ -39,6 +40,34 @@ import org.jboss.netty.util.Timer; import org.jboss.netty.util.TimerTask; /** + * Triggers an {@link IdleStateEvent} when a {@link Channel} has not performed + * read, write, or both operation for a while. + * + *

Supported idle states

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyMeaning
{@code readerIdleTime}an {@link IdleStateEvent} whose state is {@link IdleState#READER_IDLE} + * will be triggered when no read was performed for the specified period of + * time. Specify {@code 0} to disable.
{@code writerIdleTime}an {@link IdleStateEvent} whose state is {@link IdleState#WRITER_IDLE} + * will be triggered when no write was performed for the specified period of + * time. Specify {@code 0} to disable.
{@code allIdleTime}an {@link IdleStateEvent} whose state is {@link IdleState#ALL_IDLE} + * will be triggered when neither read nor write was performed for the + * specified period of time. Specify {@code 0} to disable.
+ * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ @@ -64,6 +93,24 @@ public class IdleStateHandler extends SimpleChannelUpstreamHandler volatile Timeout allIdleTimeout; private volatile AllIdleTimeoutTask allIdleTimeoutTask; + /** + * Creates a new instance. + * + * @param timer + * the {@link Timer} that is used to trigger the scheduled event + * @param readerIdleTimeSeconds + * an {@link IdleStateEvent} whose state is {@link IdleState#READER_IDLE} + * will be triggered when no read was performed for the specified + * period of time. Specify {@code 0} to disable. + * @param writerIdleTimeSeconds + * an {@link IdleStateEvent} whose state is {@link IdleState#WRITER_IDLE} + * will be triggered when no write was performed for the specified + * period of time. Specify {@code 0} to disable. + * @param allIdleTimeSeconds + * an {@link IdleStateEvent} whose state is {@link IdleState#ALL_IDLE} + * will be triggered when neither read nor write was performed for + * the specified period of time. Specify {@code 0} to disable. + */ public IdleStateHandler( Timer timer, int readerIdleTimeSeconds, @@ -75,6 +122,27 @@ public class IdleStateHandler extends SimpleChannelUpstreamHandler TimeUnit.SECONDS); } + /** + * Creates a new instance. + * + * @param timer + * the {@link Timer} that is used to trigger the scheduled event + * @param readerIdleTime + * an {@link IdleStateEvent} whose state is {@link IdleState#READER_IDLE} + * will be triggered when no read was performed for the specified + * period of time. Specify {@code 0} to disable. + * @param writerIdleTime + * an {@link IdleStateEvent} whose state is {@link IdleState#WRITER_IDLE} + * will be triggered when no write was performed for the specified + * period of time. Specify {@code 0} to disable. + * @param allIdleTime + * an {@link IdleStateEvent} whose state is {@link IdleState#ALL_IDLE} + * will be triggered when neither read nor write was performed for + * the specified period of time. Specify {@code 0} to disable. + * @param unit + * the {@link TimeUnit} of {@code readerIdleTime}, + * {@code writeIdleTime}, and {@code allIdleTime} + */ public IdleStateHandler( Timer timer, long readerIdleTime, long writerIdleTime, long allIdleTime, @@ -93,6 +161,11 @@ public class IdleStateHandler extends SimpleChannelUpstreamHandler allIdleTimeMillis = unit.toMillis(allIdleTime); } + /** + * Stops the {@link Timer} which was specified in the constructor of this + * handler. You should not call this method if the {@link Timer} is in use + * by other objects. + */ public void releaseExternalResources() { timer.stop(); } diff --git a/src/main/java/org/jboss/netty/handler/timeout/ReadTimeoutException.java b/src/main/java/org/jboss/netty/handler/timeout/ReadTimeoutException.java index 5efbdebdba..32e790dc9e 100644 --- a/src/main/java/org/jboss/netty/handler/timeout/ReadTimeoutException.java +++ b/src/main/java/org/jboss/netty/handler/timeout/ReadTimeoutException.java @@ -22,8 +22,10 @@ */ package org.jboss.netty.handler.timeout; - /** + * A {@link TimeoutException} raised by {@link ReadTimeoutHandler} when no data + * was read within a certain period of time. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ diff --git a/src/main/java/org/jboss/netty/handler/timeout/ReadTimeoutHandler.java b/src/main/java/org/jboss/netty/handler/timeout/ReadTimeoutHandler.java index 52d84eaeea..5d5a3195f8 100644 --- a/src/main/java/org/jboss/netty/handler/timeout/ReadTimeoutHandler.java +++ b/src/main/java/org/jboss/netty/handler/timeout/ReadTimeoutHandler.java @@ -72,6 +72,11 @@ public class ReadTimeoutHandler extends SimpleChannelUpstreamHandler timeoutMillis = unit.toMillis(timeout); } + /** + * Stops the {@link Timer} which was specified in the constructor of this + * handler. You should not call this method if the {@link Timer} is in use + * by other objects. + */ public void releaseExternalResources() { timer.stop(); } diff --git a/src/main/java/org/jboss/netty/handler/timeout/TimeoutException.java b/src/main/java/org/jboss/netty/handler/timeout/TimeoutException.java index e6383d9067..881aded665 100644 --- a/src/main/java/org/jboss/netty/handler/timeout/TimeoutException.java +++ b/src/main/java/org/jboss/netty/handler/timeout/TimeoutException.java @@ -25,6 +25,9 @@ package org.jboss.netty.handler.timeout; import org.jboss.netty.channel.ChannelException; /** + * A {@link TimeoutException} when no data was either read or written within a + * certain period of time. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ diff --git a/src/main/java/org/jboss/netty/handler/timeout/WriteTimeoutException.java b/src/main/java/org/jboss/netty/handler/timeout/WriteTimeoutException.java index 917ef80b4b..119bbef631 100644 --- a/src/main/java/org/jboss/netty/handler/timeout/WriteTimeoutException.java +++ b/src/main/java/org/jboss/netty/handler/timeout/WriteTimeoutException.java @@ -24,6 +24,9 @@ package org.jboss.netty.handler.timeout; /** + * A {@link TimeoutException} raised by {@link WriteTimeoutHandler} when no data + * was written within a certain period of time. + * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) * @version $Rev$, $Date$ diff --git a/src/main/java/org/jboss/netty/handler/timeout/WriteTimeoutHandler.java b/src/main/java/org/jboss/netty/handler/timeout/WriteTimeoutHandler.java index b2eda9640a..dc6bfcd525 100644 --- a/src/main/java/org/jboss/netty/handler/timeout/WriteTimeoutHandler.java +++ b/src/main/java/org/jboss/netty/handler/timeout/WriteTimeoutHandler.java @@ -68,6 +68,11 @@ public class WriteTimeoutHandler extends SimpleChannelDownstreamHandler timeoutMillis = unit.toMillis(timeout); } + /** + * Stops the {@link Timer} which was specified in the constructor of this + * handler. You should not call this method if the {@link Timer} is in use + * by other objects. + */ public void releaseExternalResources() { timer.stop(); } @@ -136,11 +141,11 @@ public class WriteTimeoutHandler extends SimpleChannelDownstreamHandler */ private static final class TimeoutCanceller implements ChannelFutureListener { private final Timeout timeout; - + TimeoutCanceller(Timeout timeout) { this.timeout = timeout; } - + public void operationComplete(ChannelFuture future) throws Exception { timeout.cancel(); } diff --git a/src/main/java/org/jboss/netty/handler/timeout/package-info.java b/src/main/java/org/jboss/netty/handler/timeout/package-info.java new file mode 100644 index 0000000000..eab4cd8cd6 --- /dev/null +++ b/src/main/java/org/jboss/netty/handler/timeout/package-info.java @@ -0,0 +1,28 @@ +/* + * JBoss, Home of Professional Open Source + * + * Copyright 2008, Red Hat Middleware LLC, and individual contributors + * by the @author tags. See the COPYRIGHT.txt in the distribution for a + * full listing of individual contributors. + * + * This is free software; you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation; either version 2.1 of + * the License, or (at your option) any later version. + * + * This software is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this software; if not, write to the Free + * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + * 02110-1301 USA, or see the FSF site: http://www.fsf.org. + */ + +/** + * Adds support for read and write timeout and idle connection notification + * using a {@link org.jboss.netty.util.Timer}. + */ +package org.jboss.netty.handler.timeout; \ No newline at end of file