diff --git a/transport/src/main/java/io/netty/channel/Channel.java b/transport/src/main/java/io/netty/channel/Channel.java index 39b8417762..1e397be570 100644 --- a/transport/src/main/java/io/netty/channel/Channel.java +++ b/transport/src/main/java/io/netty/channel/Channel.java @@ -15,12 +15,17 @@ */ package io.netty.channel; +import io.netty.buffer.ByteBuf; +import io.netty.buffer.ByteBufAllocator; import io.netty.channel.socket.DatagramChannel; import io.netty.channel.socket.DatagramPacket; import io.netty.channel.socket.ServerSocketChannel; import io.netty.channel.socket.SocketChannel; import io.netty.util.AttributeMap; +import io.netty.util.concurrent.EventExecutor; +import io.netty.util.concurrent.FutureListener; +import java.net.ConnectException; import java.net.InetSocketAddress; import java.net.SocketAddress; @@ -66,7 +71,7 @@ import java.net.SocketAddress; * operations. For example, with the old I/O datagram transport, multicast * join / leave operations are provided by {@link DatagramChannel}. */ -public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPropertyAccess, Comparable { +public interface Channel extends AttributeMap, Comparable { /** * Return the {@link EventLoop} this {@link Channel} was registered too. @@ -147,17 +152,269 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPr */ boolean isWritable(); - @Override - Channel flush(); - - @Override - Channel read(); - /** * Returns an internal-use-only object that provides unsafe operations. */ Unsafe unsafe(); + /** + * Return the assigned {@link ChannelPipeline} + */ + ChannelPipeline pipeline(); + + /** + * Return the assigned {@link ByteBufAllocator} which will be used to allocate {@link ByteBuf}s. + */ + ByteBufAllocator alloc(); + + /** + * Return a new {@link ChannelPromise}. + */ + ChannelPromise newPromise(); + + /** + * Return an new {@link ChannelProgressivePromise} + */ + ChannelProgressivePromise newProgressivePromise(); + + /** + * Create a new {@link ChannelFuture} which is marked as succeeded already. So {@link ChannelFuture#isSuccess()} + * will return {@code true}. All {@link FutureListener} added to it will be notified directly. Also + * every call of blocking methods will just return without blocking. + */ + ChannelFuture newSucceededFuture(); + + /** + * Create a new {@link ChannelFuture} which is marked as failed already. So {@link ChannelFuture#isSuccess()} + * will return {@code false}. All {@link FutureListener} added to it will be notified directly. Also + * every call of blocking methods will just return without blocking. + */ + ChannelFuture newFailedFuture(Throwable cause); + + /** + * Return a special ChannelPromise which can be reused for different operations. + *

+ * It's only supported to use + * it for {@link Channel#write(Object, ChannelPromise)}. + *

+ *

+ * Be aware that the returned {@link ChannelPromise} will not support most operations and should only be used + * if you want to save an object allocation for every write operation. You will not be able to detect if the + * operation was complete, only if it failed as the implementation will call + * {@link ChannelPipeline#fireExceptionCaught(Throwable)} in this case. + *

+ * Be aware this is an expert feature and should be used with care! + */ + ChannelPromise voidPromise(); + + /** + * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method + * called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture bind(SocketAddress localAddress); + + /** + * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + *

+ * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with + * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException} + * will be used. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress); + + /** + * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress); + + /** + * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture disconnect(); + + /** + * Request to close this {@link Channel} and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of + * an error. + * + * After it is closed it is not possible to reuse it again. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture close(); + + /** + * Request to deregister this {@link Channel} from the previous assigned {@link EventExecutor} and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + * + */ + @Deprecated + ChannelFuture deregister(); + + /** + * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + * + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method + * called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture bind(SocketAddress localAddress, ChannelPromise promise); + + /** + * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + * + * The given {@link ChannelFuture} will be notified. + * + *

+ * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with + * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException} + * will be used. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress, ChannelPromise promise); + + /** + * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + * + * The given {@link ChannelPromise} will be notified and also returned. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise); + + /** + * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of an error. + * + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture disconnect(ChannelPromise promise); + + /** + * Request to close this {@link Channel} and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of + * an error. + * + * After it is closed it is not possible to reuse it again. + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture close(ChannelPromise promise); + + /** + * Request to deregister this {@link Channel} from the previous assigned {@link EventExecutor} and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + * + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + @Deprecated + ChannelFuture deregister(ChannelPromise promise); + + /** + * Request to Read data from the {@link Channel} into the first inbound buffer, triggers an + * {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object)} event if data was + * read, and triggers a + * {@link ChannelInboundHandler#channelReadComplete(ChannelHandlerContext) channelReadComplete} event so the + * handler can decide to continue reading. If there's a pending read operation already, this method does nothing. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#read(ChannelHandlerContext)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + Channel read(); + + /** + * Request to write a message via this {@link Channel} through the {@link ChannelPipeline}. + * This method will not request to actual flush, so be sure to call {@link #flush()} + * once you want to request to flush all pending data to the actual transport. + */ + ChannelFuture write(Object msg); + + /** + * Request to write a message via this {@link Channel} through the {@link ChannelPipeline}. + * This method will not request to actual flush, so be sure to call {@link #flush()} + * once you want to request to flush all pending data to the actual transport. + */ + ChannelFuture write(Object msg, ChannelPromise promise); + + /** + * Request to flush all pending messages. + */ + Channel flush(); + + /** + * Shortcut for call {@link #write(Object, ChannelPromise)} and {@link #flush()}. + */ + ChannelFuture writeAndFlush(Object msg, ChannelPromise promise); + + /** + * Shortcut for call {@link #write(Object)} and {@link #flush()}. + */ + ChannelFuture writeAndFlush(Object msg); + /** * Unsafe operations that should never be called from user-code. These methods * are only provided to implement the actual transport, and must be invoked from an I/O thread except for the diff --git a/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java b/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java index 4c24ff1cc3..420f17b0e7 100644 --- a/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java +++ b/transport/src/main/java/io/netty/channel/ChannelHandlerContext.java @@ -16,11 +16,16 @@ package io.netty.channel; +import io.netty.buffer.ByteBuf; +import io.netty.buffer.ByteBufAllocator; import io.netty.util.Attribute; import io.netty.util.AttributeKey; import io.netty.util.AttributeMap; import io.netty.util.concurrent.EventExecutor; +import io.netty.util.concurrent.FutureListener; +import java.net.ConnectException; +import java.net.SocketAddress; import java.nio.channels.Channels; /** @@ -31,8 +36,8 @@ import java.nio.channels.Channels; *

Notify

* * You can notify the closest handler in the - * same {@link ChannelPipeline} by calling one of the various methods which are listed in {@link ChannelInboundInvoker} - * and {@link ChannelOutboundInvoker}. Please refer to {@link ChannelPipeline} to understand how an event flows. + * same {@link ChannelPipeline} by calling one of the various methods provided here. + * Please refer to {@link ChannelPipeline} to understand how an event flows. * *

Modifying a pipeline

* @@ -123,8 +128,7 @@ import java.nio.channels.Channels; * the operation in your application. */ public interface ChannelHandlerContext - extends AttributeMap, ChannelPropertyAccess, - ChannelInboundInvoker, ChannelOutboundInvoker { + extends AttributeMap { /** * Return the {@link Channel} which is bound to the {@link ChannelHandlerContext}. @@ -157,34 +161,338 @@ public interface ChannelHandlerContext */ boolean isRemoved(); - @Override + /** + * A {@link Channel} was registered to its {@link EventLoop}. + * + * This will result in having the {@link ChannelInboundHandler#channelRegistered(ChannelHandlerContext)} method + * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelHandlerContext fireChannelRegistered(); - @Override + /** + * A {@link Channel} was unregistered from its {@link EventLoop}. + * + * This will result in having the {@link ChannelInboundHandler#channelUnregistered(ChannelHandlerContext)} method + * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ @Deprecated ChannelHandlerContext fireChannelUnregistered(); - @Override + /** + * A {@link Channel} is active now, which means it is connected. + * + * This will result in having the {@link ChannelInboundHandler#channelActive(ChannelHandlerContext)} method + * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelHandlerContext fireChannelActive(); - @Override + /** + * A {@link Channel} is inactive now, which means it is closed. + * + * This will result in having the {@link ChannelInboundHandler#channelInactive(ChannelHandlerContext)} method + * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelHandlerContext fireChannelInactive(); - @Override + /** + * A {@link Channel} received an {@link Throwable} in one of its inbound operations. + * + * This will result in having the {@link ChannelInboundHandler#exceptionCaught(ChannelHandlerContext, Throwable)} + * method called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelHandlerContext fireExceptionCaught(Throwable cause); - @Override + /** + * A {@link Channel} received an user defined event. + * + * This will result in having the {@link ChannelInboundHandler#userEventTriggered(ChannelHandlerContext, Object)} + * method called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelHandlerContext fireUserEventTriggered(Object event); - @Override + /** + * A {@link Channel} received a message. + * + * This will result in having the {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object)} + * method called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelHandlerContext fireChannelRead(Object msg); - @Override + /** + * Triggers an {@link ChannelInboundHandler#channelWritabilityChanged(ChannelHandlerContext)} + * event to the next {@link ChannelInboundHandler} in the {@link ChannelPipeline}. + */ ChannelHandlerContext fireChannelReadComplete(); - @Override + /** + * Triggers an {@link ChannelInboundHandler#channelWritabilityChanged(ChannelHandlerContext)} + * event to the next {@link ChannelInboundHandler} in the {@link ChannelPipeline}. + */ ChannelHandlerContext fireChannelWritabilityChanged(); - @Override + /** + * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method + * called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture bind(SocketAddress localAddress); + + /** + * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + *

+ * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with + * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException} + * will be used. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress); + + /** + * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress); + + /** + * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture disconnect(); + + /** + * Request to close the {@link Channel} and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of + * an error. + * + * After it is closed it is not possible to reuse it again. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture close(); + + /** + * Request to deregister from the previous assigned {@link EventExecutor} and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + * + */ + @Deprecated + ChannelFuture deregister(); + + /** + * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + * + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method + * called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture bind(SocketAddress localAddress, ChannelPromise promise); + + /** + * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + * + * The given {@link ChannelFuture} will be notified. + * + *

+ * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with + * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException} + * will be used. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress, ChannelPromise promise); + + /** + * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + * + * The given {@link ChannelPromise} will be notified and also returned. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise); + + /** + * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of an error. + * + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture disconnect(ChannelPromise promise); + + /** + * Request to close the {@link Channel} and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of + * an error. + * + * After it is closed it is not possible to reuse it again. + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture close(ChannelPromise promise); + + /** + * Request to deregister from the previous assigned {@link EventExecutor} and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + * + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + @Deprecated + ChannelFuture deregister(ChannelPromise promise); + + /** + * Request to Read data from the {@link Channel} into the first inbound buffer, triggers an + * {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object)} event if data was + * read, and triggers a + * {@link ChannelInboundHandler#channelReadComplete(ChannelHandlerContext) channelReadComplete} event so the + * handler can decide to continue reading. If there's a pending read operation already, this method does nothing. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#read(ChannelHandlerContext)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelHandlerContext read(); + + /** + * Request to write a message via this {@link ChannelHandlerContext} through the {@link ChannelPipeline}. + * This method will not request to actual flush, so be sure to call {@link #flush()} + * once you want to request to flush all pending data to the actual transport. + */ + ChannelFuture write(Object msg); + + /** + * Request to write a message via this {@link ChannelHandlerContext} through the {@link ChannelPipeline}. + * This method will not request to actual flush, so be sure to call {@link #flush()} + * once you want to request to flush all pending data to the actual transport. + */ + ChannelFuture write(Object msg, ChannelPromise promise); + + /** + * Request to flush all pending messages via this ChannelOutboundInvoker. + */ ChannelHandlerContext flush(); + + /** + * Shortcut for call {@link #write(Object, ChannelPromise)} and {@link #flush()}. + */ + ChannelFuture writeAndFlush(Object msg, ChannelPromise promise); + + /** + * Shortcut for call {@link #write(Object)} and {@link #flush()}. + */ + ChannelFuture writeAndFlush(Object msg); + + /** + * Return the assigned {@link ChannelPipeline} + */ + ChannelPipeline pipeline(); + + /** + * Return the assigned {@link ByteBufAllocator} which will be used to allocate {@link ByteBuf}s. + */ + ByteBufAllocator alloc(); + + /** + * Return a new {@link ChannelPromise}. + */ + ChannelPromise newPromise(); + + /** + * Return an new {@link ChannelProgressivePromise} + */ + ChannelProgressivePromise newProgressivePromise(); + + /** + * Create a new {@link ChannelFuture} which is marked as succeeded already. So {@link ChannelFuture#isSuccess()} + * will return {@code true}. All {@link FutureListener} added to it will be notified directly. Also + * every call of blocking methods will just return without blocking. + */ + ChannelFuture newSucceededFuture(); + + /** + * Create a new {@link ChannelFuture} which is marked as failed already. So {@link ChannelFuture#isSuccess()} + * will return {@code false}. All {@link FutureListener} added to it will be notified directly. Also + * every call of blocking methods will just return without blocking. + */ + ChannelFuture newFailedFuture(Throwable cause); + + /** + * Return a special ChannelPromise which can be reused for different operations. + *

+ * It's only supported to use + * it for {@link ChannelHandlerContext#write(Object, ChannelPromise)}. + *

+ *

+ * Be aware that the returned {@link ChannelPromise} will not support most operations and should only be used + * if you want to save an object allocation for every write operation. You will not be able to detect if the + * operation was complete, only if it failed as the implementation will call + * {@link ChannelPipeline#fireExceptionCaught(Throwable)} in this case. + *

+ * Be aware this is an expert feature and should be used with care! + */ + ChannelPromise voidPromise(); + } diff --git a/transport/src/main/java/io/netty/channel/ChannelInboundInvoker.java b/transport/src/main/java/io/netty/channel/ChannelInboundInvoker.java deleted file mode 100644 index 64086f348e..0000000000 --- a/transport/src/main/java/io/netty/channel/ChannelInboundInvoker.java +++ /dev/null @@ -1,95 +0,0 @@ -/* - * Copyright 2012 The Netty Project - * - * The Netty Project licenses this file to you under the Apache License, - * version 2.0 (the "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at: - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - * License for the specific language governing permissions and limitations - * under the License. - */ -package io.netty.channel; - - -/** - * Interface which is shared by others which need to fire inbound events - */ -interface ChannelInboundInvoker { - - /** - * A {@link Channel} was registered to its {@link EventLoop}. - * - * This will result in having the {@link ChannelInboundHandler#channelRegistered(ChannelHandlerContext)} method - * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelInboundInvoker fireChannelRegistered(); - - /** - * A {@link Channel} was unregistered from its {@link EventLoop}. - * - * This will result in having the {@link ChannelInboundHandler#channelUnregistered(ChannelHandlerContext)} method - * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - @Deprecated - ChannelInboundInvoker fireChannelUnregistered(); - - /** - * A {@link Channel} is active now, which means it is connected. - * - * This will result in having the {@link ChannelInboundHandler#channelActive(ChannelHandlerContext)} method - * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelInboundInvoker fireChannelActive(); - - /** - * A {@link Channel} is inactive now, which means it is closed. - * - * This will result in having the {@link ChannelInboundHandler#channelInactive(ChannelHandlerContext)} method - * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelInboundInvoker fireChannelInactive(); - - /** - * A {@link Channel} received an {@link Throwable} in one of its inbound operations. - * - * This will result in having the {@link ChannelInboundHandler#exceptionCaught(ChannelHandlerContext, Throwable)} - * method called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelInboundInvoker fireExceptionCaught(Throwable cause); - - /** - * A {@link Channel} received an user defined event. - * - * This will result in having the {@link ChannelInboundHandler#userEventTriggered(ChannelHandlerContext, Object)} - * method called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelInboundInvoker fireUserEventTriggered(Object event); - - /** - * A {@link Channel} received a message. - * - * This will result in having the {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object)} - * method called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelInboundInvoker fireChannelRead(Object msg); - - ChannelInboundInvoker fireChannelReadComplete(); - - /** - * Triggers an {@link ChannelInboundHandler#channelWritabilityChanged(ChannelHandlerContext)} - * event to the next {@link ChannelInboundHandler} in the {@link ChannelPipeline}. - */ - ChannelInboundInvoker fireChannelWritabilityChanged(); -} diff --git a/transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java b/transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java deleted file mode 100644 index 64b5ec64cc..0000000000 --- a/transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java +++ /dev/null @@ -1,235 +0,0 @@ -/* - * Copyright 2012 The Netty Project - * - * The Netty Project licenses this file to you under the Apache License, - * version 2.0 (the "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at: - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - * License for the specific language governing permissions and limitations - * under the License. - */ -package io.netty.channel; - -import io.netty.util.concurrent.EventExecutor; - -import java.net.ConnectException; -import java.net.SocketAddress; - -/** - * Interface which is shared by others which need to execute outbound logic. - */ -interface ChannelOutboundInvoker { - - /** - * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation - * completes, either because the operation was successful or because of an error. - *

- * This will result in having the - * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method - * called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelFuture bind(SocketAddress localAddress); - - /** - * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation - * completes, either because the operation was successful or because of an error. - *

- * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with - * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException} - * will be used. - *

- * This will result in having the - * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} - * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelFuture connect(SocketAddress remoteAddress); - - /** - * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the - * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of - * an error. - *

- * This will result in having the - * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} - * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress); - - /** - * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes, - * either because the operation was successful or because of an error. - *

- * This will result in having the - * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)} - * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelFuture disconnect(); - - /** - * Request to close this ChannelOutboundInvoker and notify the {@link ChannelFuture} once the operation completes, - * either because the operation was successful or because of - * an error. - * - * After it is closed it is not possible to reuse it again. - *

- * This will result in having the - * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)} - * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelFuture close(); - - /** - * Request to deregister this ChannelOutboundInvoker from the previous assigned {@link EventExecutor} and notify the - * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of - * an error. - *

- * This will result in having the - * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)} - * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - * - */ - @Deprecated - ChannelFuture deregister(); - - /** - * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation - * completes, either because the operation was successful or because of an error. - * - * The given {@link ChannelPromise} will be notified. - *

- * This will result in having the - * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method - * called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelFuture bind(SocketAddress localAddress, ChannelPromise promise); - - /** - * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation - * completes, either because the operation was successful or because of an error. - * - * The given {@link ChannelFuture} will be notified. - * - *

- * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with - * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException} - * will be used. - *

- * This will result in having the - * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} - * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelFuture connect(SocketAddress remoteAddress, ChannelPromise promise); - - /** - * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the - * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of - * an error. - * - * The given {@link ChannelPromise} will be notified and also returned. - *

- * This will result in having the - * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} - * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise); - - /** - * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes, - * either because the operation was successful or because of an error. - * - * The given {@link ChannelPromise} will be notified. - *

- * This will result in having the - * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)} - * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelFuture disconnect(ChannelPromise promise); - - /** - * Request to close this ChannelOutboundInvoker and notify the {@link ChannelFuture} once the operation completes, - * either because the operation was successful or because of - * an error. - * - * After it is closed it is not possible to reuse it again. - * The given {@link ChannelPromise} will be notified. - *

- * This will result in having the - * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)} - * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelFuture close(ChannelPromise promise); - - /** - * Request to deregister this ChannelOutboundInvoker from the previous assigned {@link EventExecutor} and notify the - * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of - * an error. - * - * The given {@link ChannelPromise} will be notified. - *

- * This will result in having the - * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)} - * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - @Deprecated - ChannelFuture deregister(ChannelPromise promise); - - /** - * Request to Read data from the {@link Channel} into the first inbound buffer, triggers an - * {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object)} event if data was - * read, and triggers a - * {@link ChannelInboundHandler#channelReadComplete(ChannelHandlerContext) channelReadComplete} event so the - * handler can decide to continue reading. If there's a pending read operation already, this method does nothing. - *

- * This will result in having the - * {@link ChannelOutboundHandler#read(ChannelHandlerContext)} - * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the - * {@link Channel}. - */ - ChannelOutboundInvoker read(); - - /** - * Request to write a message via this ChannelOutboundInvoker through the {@link ChannelPipeline}. - * This method will not request to actual flush, so be sure to call {@link #flush()} - * once you want to request to flush all pending data to the actual transport. - */ - ChannelFuture write(Object msg); - - /** - * Request to write a message via this ChannelOutboundInvoker through the {@link ChannelPipeline}. - * This method will not request to actual flush, so be sure to call {@link #flush()} - * once you want to request to flush all pending data to the actual transport. - */ - ChannelFuture write(Object msg, ChannelPromise promise); - - /** - * Request to flush all pending messages via this ChannelOutboundInvoker. - */ - ChannelOutboundInvoker flush(); - - /** - * Shortcut for call {@link #write(Object, ChannelPromise)} and {@link #flush()}. - */ - ChannelFuture writeAndFlush(Object msg, ChannelPromise promise); - - /** - * Shortcut for call {@link #write(Object)} and {@link #flush()}. - */ - ChannelFuture writeAndFlush(Object msg); -} diff --git a/transport/src/main/java/io/netty/channel/ChannelPipeline.java b/transport/src/main/java/io/netty/channel/ChannelPipeline.java index f8e07bc9ee..2ac3e52c48 100644 --- a/transport/src/main/java/io/netty/channel/ChannelPipeline.java +++ b/transport/src/main/java/io/netty/channel/ChannelPipeline.java @@ -17,8 +17,10 @@ package io.netty.channel; import io.netty.buffer.ByteBuf; import io.netty.util.concurrent.DefaultEventExecutorGroup; +import io.netty.util.concurrent.EventExecutor; import io.netty.util.concurrent.EventExecutorGroup; +import java.net.ConnectException; import java.net.SocketAddress; import java.nio.ByteBuffer; import java.nio.channels.SocketChannel; @@ -214,7 +216,7 @@ import java.util.NoSuchElementException; * after the exchange. */ public interface ChannelPipeline - extends ChannelInboundInvoker, ChannelOutboundInvoker, Iterable> { + extends Iterable> { /** * Inserts a {@link ChannelHandler} at the first position of this pipeline. @@ -594,37 +596,287 @@ public interface ChannelPipeline */ Map toMap(); - @Override + /** + * A {@link Channel} was registered to its {@link EventLoop}. + * + * This will result in having the {@link ChannelInboundHandler#channelRegistered(ChannelHandlerContext)} method + * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelPipeline fireChannelRegistered(); - @Override + /** + * A {@link Channel} was unregistered from its {@link EventLoop}. + * + * This will result in having the {@link ChannelInboundHandler#channelUnregistered(ChannelHandlerContext)} method + * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ @Deprecated ChannelPipeline fireChannelUnregistered(); - @Override + /** + * A {@link Channel} is active now, which means it is connected. + * + * This will result in having the {@link ChannelInboundHandler#channelActive(ChannelHandlerContext)} method + * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelPipeline fireChannelActive(); - @Override + /** + * A {@link Channel} is inactive now, which means it is closed. + * + * This will result in having the {@link ChannelInboundHandler#channelInactive(ChannelHandlerContext)} method + * called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelPipeline fireChannelInactive(); - @Override + /** + * A {@link Channel} received an {@link Throwable} in one of its inbound operations. + * + * This will result in having the {@link ChannelInboundHandler#exceptionCaught(ChannelHandlerContext, Throwable)} + * method called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelPipeline fireExceptionCaught(Throwable cause); - @Override + /** + * A {@link Channel} received an user defined event. + * + * This will result in having the {@link ChannelInboundHandler#userEventTriggered(ChannelHandlerContext, Object)} + * method called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelPipeline fireUserEventTriggered(Object event); - @Override + /** + * A {@link Channel} received a message. + * + * This will result in having the {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object)} + * method called of the next {@link ChannelInboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ ChannelPipeline fireChannelRead(Object msg); - @Override + /** + * Triggers an {@link ChannelInboundHandler#channelWritabilityChanged(ChannelHandlerContext)} + * event to the next {@link ChannelInboundHandler} in the {@link ChannelPipeline}. + */ ChannelPipeline fireChannelReadComplete(); - @Override + /** + * Triggers an {@link ChannelInboundHandler#channelWritabilityChanged(ChannelHandlerContext)} + * event to the next {@link ChannelInboundHandler} in the {@link ChannelPipeline}. + */ ChannelPipeline fireChannelWritabilityChanged(); - @Override + /** + * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method + * called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture bind(SocketAddress localAddress); + + /** + * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + *

+ * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with + * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException} + * will be used. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress); + + /** + * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress); + + /** + * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture disconnect(); + + /** + * Request to close the {@link Channel} and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of + * an error. + * + * After it is closed it is not possible to reuse it again. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture close(); + + /** + * Request to deregister the {@link Channel} from the previous assigned {@link EventExecutor} and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + * + */ + @Deprecated + ChannelFuture deregister(); + + /** + * Request to bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + * + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#bind(ChannelHandlerContext, SocketAddress, ChannelPromise)} method + * called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture bind(SocketAddress localAddress, ChannelPromise promise); + + /** + * Request to connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation + * completes, either because the operation was successful or because of an error. + * + * The given {@link ChannelFuture} will be notified. + * + *

+ * If the connection fails because of a connection timeout, the {@link ChannelFuture} will get failed with + * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException} + * will be used. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress, ChannelPromise promise); + + /** + * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the + * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of + * an error. + * + * The given {@link ChannelPromise} will be notified and also returned. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise); + + /** + * Request to disconnect from the remote peer and notify the {@link ChannelFuture} once the operation completes, + * either because the operation was successful or because of an error. + * + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#disconnect(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture disconnect(ChannelPromise promise); + + /** + * Request to close the {@link Channel} bound to this {@link ChannelPipeline} and notify the {@link ChannelFuture} + * once the operation completes, either because the operation was successful or because of + * an error. + * + * After it is closed it is not possible to reuse it again. + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#close(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelFuture close(ChannelPromise promise); + + /** + * Request to deregister the {@link Channel} bound this {@link ChannelPipeline} from the previous assigned + * {@link EventExecutor} and notify the {@link ChannelFuture} once the operation completes, either because the + * operation was successful or because of an error. + * + * The given {@link ChannelPromise} will be notified. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#deregister(ChannelHandlerContext, ChannelPromise)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + @Deprecated + ChannelFuture deregister(ChannelPromise promise); + + /** + * Request to Read data from the {@link Channel} into the first inbound buffer, triggers an + * {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object)} event if data was + * read, and triggers a + * {@link ChannelInboundHandler#channelReadComplete(ChannelHandlerContext) channelReadComplete} event so the + * handler can decide to continue reading. If there's a pending read operation already, this method does nothing. + *

+ * This will result in having the + * {@link ChannelOutboundHandler#read(ChannelHandlerContext)} + * method called of the next {@link ChannelOutboundHandler} contained in the {@link ChannelPipeline} of the + * {@link Channel}. + */ + ChannelPipeline read(); + + /** + * Request to write a message via this {@link ChannelPipeline}. + * This method will not request to actual flush, so be sure to call {@link #flush()} + * once you want to request to flush all pending data to the actual transport. + */ + ChannelFuture write(Object msg); + + /** + * Request to write a message via this {@link ChannelPipeline}. + * This method will not request to actual flush, so be sure to call {@link #flush()} + * once you want to request to flush all pending data to the actual transport. + */ + ChannelFuture write(Object msg, ChannelPromise promise); + + /** + * Request to flush all pending messages. + */ ChannelPipeline flush(); - @Override - ChannelPipeline read(); + /** + * Shortcut for call {@link #write(Object, ChannelPromise)} and {@link #flush()}. + */ + ChannelFuture writeAndFlush(Object msg, ChannelPromise promise); + + /** + * Shortcut for call {@link #write(Object)} and {@link #flush()}. + */ + ChannelFuture writeAndFlush(Object msg); } diff --git a/transport/src/main/java/io/netty/channel/ChannelPropertyAccess.java b/transport/src/main/java/io/netty/channel/ChannelPropertyAccess.java deleted file mode 100644 index 7daa5fb9fe..0000000000 --- a/transport/src/main/java/io/netty/channel/ChannelPropertyAccess.java +++ /dev/null @@ -1,77 +0,0 @@ -/* - * Copyright 2012 The Netty Project - * - * The Netty Project licenses this file to you under the Apache License, - * version 2.0 (the "License"); you may not use this file except in compliance - * with the License. You may obtain a copy of the License at: - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - * License for the specific language governing permissions and limitations - * under the License. - */ -package io.netty.channel; - -import io.netty.buffer.ByteBuf; -import io.netty.buffer.ByteBufAllocator; -import io.netty.util.concurrent.Future; -import io.netty.util.concurrent.FutureListener; - -/** - * Provides common methods between {@link Channel} and {@link ChannelHandlerContext}. - */ -interface ChannelPropertyAccess { - - /** - * Return the assigned {@link ChannelPipeline} - */ - ChannelPipeline pipeline(); - - /** - * Return the assigned {@link ByteBufAllocator} which will be used to allocate {@link ByteBuf}s. - */ - ByteBufAllocator alloc(); - - /** - * Return a new {@link ChannelPromise}. - */ - ChannelPromise newPromise(); - - /** - * Return an new {@link ChannelProgressivePromise} - */ - ChannelProgressivePromise newProgressivePromise(); - - /** - * Create a new {@link ChannelFuture} which is marked as succeeded already. So {@link ChannelFuture#isSuccess()} - * will return {@code true}. All {@link FutureListener} added to it will be notified directly. Also - * every call of blocking methods will just return without blocking. - */ - ChannelFuture newSucceededFuture(); - - /** - * Create a new {@link ChannelFuture} which is marked as failed already. So {@link ChannelFuture#isSuccess()} - * will return {@code false}. All {@link FutureListener} added to it will be notified directly. Also - * every call of blocking methods will just return without blocking. - */ - ChannelFuture newFailedFuture(Throwable cause); - - /** - * Return a special ChannelPromise which can be reused for different operations. - *

- * It's only supported to use - * it for {@link ChannelOutboundInvoker#write(Object, ChannelPromise)}. - *

- *

- * Be aware that the returned {@link ChannelPromise} will not support most operations and should only be used - * if you want to save an object allocation for every write operation. You will not be able to detect if the - * operation was complete, only if it failed as the implementation will call - * {@link ChannelPipeline#fireExceptionCaught(Throwable)} in this case. - *

- * Be aware this is an expert feature and should be used with care! - */ - ChannelPromise voidPromise(); -}