diff --git a/src/main/java/org/jboss/netty/channel/ChannelFuture.java b/src/main/java/org/jboss/netty/channel/ChannelFuture.java index 31de4a0237..789199fdac 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelFuture.java +++ b/src/main/java/org/jboss/netty/channel/ChannelFuture.java @@ -25,6 +25,11 @@ package org.jboss.netty.channel; import java.util.concurrent.TimeUnit; /** + * The result of an asynchronous {@link Channel} I/O operation. Methods are + * provided to check if the I/O operation is complete, to wait for its + * completion, and to retrieve the result of the I/O operation. It also allows + * you to add more than one {@link ChannelFutureListener} so you can get + * notified when the I/O operation is complete. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -35,25 +40,125 @@ import java.util.concurrent.TimeUnit; * @apiviz.owns org.jboss.netty.channel.ChannelFutureListener - - notifies */ public interface ChannelFuture { + + /** + * Returns a channel where the I/O operation associated with this future + * takes place. + */ Channel getChannel(); + /** + * Returns {@code true} if and only if this future is complete, regardless + * the operation was successful, failed, or canceled. + */ boolean isDone(); + + /** + * Returns {@code true} if and only if this future was canceled by + * a {@link #cancel()} method. + */ boolean isCancelled(); + + /** + * Returns {@code true} if and only if the I/O operation was done + * successfully. + */ boolean isSuccess(); + + /** + * Returns the cause of the failed I/O operation if the I/O operation has + * failed. + * + * @return the cause of the failure. + * {@code null} if succeeded or this future is not done yet. + */ Throwable getCause(); + /** + * Cancels the I/O operation associated with this future and notifies all + * listeners if canceled successfully. + * + * @return {@code true} if and only if the operation has been canceled. + * {@code false} if the operation can't be canceled or is already done. + */ boolean cancel(); + /** + * Marks this future as a success and notifies all listeners. + */ void setSuccess(); + + /** + * Marks this future as a failure and notifies all listeners. + */ void setFailure(Throwable cause); + /** + * Adds the specified listener to this future. The specified listener is + * notified when this future is {@linkplain #isDone() done}. If this + * future is already done, the specified listener is notified immediately. + */ void addListener(ChannelFutureListener listener); + + /** + * Removes the specified listener from this future. The specified + * listener is no longer notified when this future is + * {@linkplain #isDone() done}. If this future is already done, this + * method has no effect and returns silently. + */ void removeListener(ChannelFutureListener listener); + /** + * Waits for this future to be done. + * + * @throws InterruptedException + * if the current thread was interrupted + */ ChannelFuture await() throws InterruptedException; + + /** + * Waits for this future to be done uninterruptibly. This method catches + * an {@link InterruptedException} and discards it silently. + */ ChannelFuture awaitUninterruptibly(); + + /** + * Waits for this future to be done with the specified time limit. + * + * @return {@code true} if and only if the future was done within + * the specified time limit + * + * @throws InterruptedException + * if the current thread was interrupted + */ boolean await(long timeout, TimeUnit unit) throws InterruptedException; + + /** + * Waits for this future to be done with the specified time limit. + * + * @return {@code true} if and only if the future was done within + * the specified time limit + * + * @throws InterruptedException + * if the current thread was interrupted + */ boolean await(long timeoutMillis) throws InterruptedException; + + /** + * Waits for this future to be done with the specified time limit. This + * method catches an {@link InterruptedException} and discards it silently. + * + * @return {@code true} if and only if the future was done within + * the specified time limit + */ boolean awaitUninterruptibly(long timeout, TimeUnit unit); + + /** + * Waits for this future to be done with the specified time limit. This + * method catches an {@link InterruptedException} and discards it silently. + * + * @return {@code true} if and only if the future was done within + * the specified time limit + */ boolean awaitUninterruptibly(long timeoutMillis); } diff --git a/src/main/java/org/jboss/netty/channel/ChannelFutureListener.java b/src/main/java/org/jboss/netty/channel/ChannelFutureListener.java index 1f4de1f52b..1f70980af8 100644 --- a/src/main/java/org/jboss/netty/channel/ChannelFutureListener.java +++ b/src/main/java/org/jboss/netty/channel/ChannelFutureListener.java @@ -25,6 +25,9 @@ package org.jboss.netty.channel; import java.util.EventListener; /** + * Listens to the result of an asynchronous I/O operation. The result of the + * I/O operation is notified by {@link ChannelFuture} once this listener is + * added to the future. * * @author The Netty Project (netty-dev@lists.jboss.org) * @author Trustin Lee (tlee@redhat.com) @@ -34,6 +37,7 @@ import java.util.EventListener; * @apiviz.landmark */ public interface ChannelFutureListener extends EventListener { + /** * An {@link ChannelFutureListener} that closes the {@link Channel} which is * associated with the specified {@link ChannelFuture}. @@ -45,7 +49,7 @@ public interface ChannelFutureListener extends EventListener { }; /** - * Invoked when the operation associated with the {@link ChannelFuture} + * Invoked when the I/O operation associated with the {@link ChannelFuture} * has been completed. * * @param future The source {@link ChannelFuture} which called this diff --git a/src/main/java/org/jboss/netty/channel/CompleteChannelFuture.java b/src/main/java/org/jboss/netty/channel/CompleteChannelFuture.java index 738c0f1185..3f87b5b4c1 100644 --- a/src/main/java/org/jboss/netty/channel/CompleteChannelFuture.java +++ b/src/main/java/org/jboss/netty/channel/CompleteChannelFuture.java @@ -27,6 +27,15 @@ import java.util.concurrent.TimeUnit; import org.jboss.netty.logging.InternalLogger; import org.jboss.netty.logging.InternalLoggerFactory; +/** + * Skeletal {@link ChannelFuture} implementation which represents a future + * which is complete (done) already. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + */ public abstract class CompleteChannelFuture implements ChannelFuture { private static final InternalLogger logger = @@ -34,6 +43,11 @@ public abstract class CompleteChannelFuture implements ChannelFuture { private final Channel channel; + /** + * Creates a new instance. + * + * @param channel the {@link Channel} associated with this future + */ protected CompleteChannelFuture(Channel channel) { if (channel == null) { throw new NullPointerException("channel"); diff --git a/src/main/java/org/jboss/netty/channel/DefaultChannelFuture.java b/src/main/java/org/jboss/netty/channel/DefaultChannelFuture.java index 6af38b64a1..da4817fb07 100644 --- a/src/main/java/org/jboss/netty/channel/DefaultChannelFuture.java +++ b/src/main/java/org/jboss/netty/channel/DefaultChannelFuture.java @@ -29,11 +29,19 @@ import java.util.concurrent.TimeUnit; import org.jboss.netty.logging.InternalLogger; import org.jboss.netty.logging.InternalLoggerFactory; - +/** + * The default {@link ChannelFuture} implementation. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + */ public class DefaultChannelFuture implements ChannelFuture { private static final InternalLogger logger = InternalLoggerFactory.getInstance(DefaultChannelFuture.class); + private static final int DEAD_LOCK_CHECK_INTERVAL = 5000; private static final Throwable CANCELLED = new Throwable(); @@ -46,6 +54,14 @@ public class DefaultChannelFuture implements ChannelFuture { private Throwable cause; private int waiters; + /** + * Creates a new instance. + * + * @param channel + * the {@link Channel} associated with this future + * @param cancellable + * {@code true} if and only if this future can be canceled + */ public DefaultChannelFuture(Channel channel, boolean cancellable) { this.channel = channel; this.cancellable = cancellable; diff --git a/src/main/java/org/jboss/netty/channel/FailedChannelFuture.java b/src/main/java/org/jboss/netty/channel/FailedChannelFuture.java index 98c9505e37..4a3e924bcb 100644 --- a/src/main/java/org/jboss/netty/channel/FailedChannelFuture.java +++ b/src/main/java/org/jboss/netty/channel/FailedChannelFuture.java @@ -22,11 +22,26 @@ */ package org.jboss.netty.channel; - +/** + * The {@link CompleteChannelFuture} which is failed already. It is + * recommended to use {@link Channels#failedFuture(Channel, Throwable)} + * instead of calling the constructor of this future. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + */ public class FailedChannelFuture extends CompleteChannelFuture { private final Throwable cause; + /** + * Creates a new instance. + * + * @param channel the {@link Channel} associated with this future + * @param cause the cause of failure + */ public FailedChannelFuture(Channel channel, Throwable cause) { super(channel); if (cause == null) { diff --git a/src/main/java/org/jboss/netty/channel/SucceededChannelFuture.java b/src/main/java/org/jboss/netty/channel/SucceededChannelFuture.java index 066c3a491f..0e47535e28 100644 --- a/src/main/java/org/jboss/netty/channel/SucceededChannelFuture.java +++ b/src/main/java/org/jboss/netty/channel/SucceededChannelFuture.java @@ -22,9 +22,23 @@ */ package org.jboss.netty.channel; - +/** + * The {@link CompleteChannelFuture} which is succeeded already. It is + * recommended to use {@link Channels#succeededFuture(Channel)} instead of + * calling the constructor of this future. + * + * @author The Netty Project (netty-dev@lists.jboss.org) + * @author Trustin Lee (tlee@redhat.com) + * + * @version $Rev$, $Date$ + */ public class SucceededChannelFuture extends CompleteChannelFuture { + /** + * Creates a new instance. + * + * @param channel the {@link Channel} associated with this future + */ public SucceededChannelFuture(Channel channel) { super(channel); }