1 /*
2 * Copyright 2016 The Netty Project
3 *
4 * The Netty Project licenses this file to you under the Apache License,
5 * version 2.0 (the "License"); you may not use this file except in compliance
6 * with the License. You may obtain a copy of the License at:
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package io.netty5.channel;
17
18 import io.netty5.util.concurrent.EventExecutor;
19 import io.netty5.util.concurrent.Future;
20 import io.netty5.util.concurrent.FuturePromiseFactory;
21 import io.netty5.util.concurrent.Promise;
22
23 import java.net.ConnectException;
24 import java.net.SocketAddress;
25
26 public interface ChannelOutboundInvoker extends FuturePromiseFactory {
27
28 /**
29 * Request to bind to the given {@link SocketAddress} and notify the {@link Future} once the operation
30 * completes, either because the operation was successful or because of an error.
31 * <p>
32 * This will result in having the
33 * {@link ChannelHandler#bind(ChannelHandlerContext, SocketAddress)} method
34 * called of the next {@link ChannelHandler} contained in the {@link ChannelPipeline} of the
35 * {@link Channel}.
36 */
37 Future<Void> bind(SocketAddress localAddress);
38
39 /**
40 * Request to connect to the given {@link SocketAddress} and notify the {@link Future} once the operation
41 * completes, either because the operation was successful or because of an error.
42 * <p>
43 * If the connection fails because of a connection timeout, the {@link Future} will get failed with
44 * a {@link ConnectTimeoutException}. If it fails because of connection refused a {@link ConnectException}
45 * will be used.
46 * <p>
47 * This will result in having the
48 * {@link ChannelHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress)}
49 * method called of the next {@link ChannelHandler} contained in the {@link ChannelPipeline} of the
50 * {@link Channel}.
51 */
52 Future<Void> connect(SocketAddress remoteAddress);
53
54 /**
55 * Request to connect to the given {@link SocketAddress} while bind to the localAddress and notify the
56 * {@link Future} once the operation completes, either because the operation was successful or because of
57 * an error.
58 * <p>
59 * This will result in having the
60 * {@link ChannelHandler#connect(ChannelHandlerContext, SocketAddress, SocketAddress)}
61 * method called of the next {@link ChannelHandler} contained in the {@link ChannelPipeline} of the
62 * {@link Channel}.
63 */
64 Future<Void> connect(SocketAddress remoteAddress, SocketAddress localAddress);
65
66 /**
67 * Request to disconnect from the remote peer and notify the {@link Future} once the operation completes,
68 * either because the operation was successful or because of an error.
69 * <p>
70 * This will result in having the
71 * {@link ChannelHandler#disconnect(ChannelHandlerContext)}
72 * method called of the next {@link ChannelHandler} contained in the {@link ChannelPipeline} of the
73 * {@link Channel}.
74 */
75 Future<Void> disconnect();
76
77 /**
78 * Request to close the {@link Channel} and notify the {@link Future} once the operation completes,
79 * either because the operation was successful or because of
80 * an error.
81 *
82 * After it is closed it is not possible to reuse it again.
83 * <p>
84 * This will result in having the
85 * {@link ChannelHandler#close(ChannelHandlerContext)}
86 * method called of the next {@link ChannelHandler} contained in the {@link ChannelPipeline} of the
87 * {@link Channel}.
88 */
89 Future<Void> close();
90
91 /**
92 * Request shutdown one direction of the {@link Channel} and notify the {@link Future} once the operation completes,
93 * either because the operation was successful or because of an error.
94 * <p>
95 * When completed, the channel will either not produce any inbound data anymore, or it will not be
96 * possible to write data anymore, depending on the given {@link ChannelShutdownDirection}.
97 * <p>
98 * Depending on the transport implementation shutting down the {@link ChannelShutdownDirection#Outbound}
99 * or {@link ChannelShutdownDirection#Inbound} might also result in data transferred over the network. Like for
100 * example in case of TCP shutting down the {@link ChannelShutdownDirection#Outbound} will result in a {@code FIN}
101 * that is transmitted to the remote peer that will as a result shutdown {@link ChannelShutdownDirection#Inbound}.
102 * <p>
103 * This will result in having the
104 * {@link ChannelHandler#shutdown(ChannelHandlerContext, ChannelShutdownDirection)}.
105 * method called of the next {@link ChannelHandler} contained in the {@link ChannelPipeline} of the
106 * {@link Channel}.
107 */
108 Future<Void> shutdown(ChannelShutdownDirection direction);
109
110 /**
111 * Request to register on the {@link EventExecutor} for I/O processing.
112 * {@link Future} once the operation completes, either because the operation was successful or because of
113 * an error.
114 * <p>
115 * This will result in having the
116 * {@link ChannelHandler#register(ChannelHandlerContext)}
117 * method called of the next {@link ChannelHandler} contained in the {@link ChannelPipeline} of the
118 * {@link Channel}.
119 */
120 Future<Void> register();
121
122 /**
123 * Request to deregister from the previous assigned {@link EventExecutor} and notify the
124 * {@link Future} once the operation completes, either because the operation was successful or because of
125 * an error.
126 * <p>
127 * This will result in having the
128 * {@link ChannelHandler#deregister(ChannelHandlerContext)}
129 * method called of the next {@link ChannelHandler} contained in the {@link ChannelPipeline} of the
130 * {@link Channel}.
131 *
132 */
133 Future<Void> deregister();
134
135 /**
136 * Request to Read data from the {@link Channel} into the first inbound buffer, triggers an
137 * {@link ChannelHandler#channelRead(ChannelHandlerContext, Object)} event if data was
138 * read, and triggers a
139 * {@link ChannelHandler#channelReadComplete(ChannelHandlerContext) channelReadComplete} event so the
140 * handler can decide to continue reading. If there's a pending read operation already, this method does nothing.
141 * <p>
142 * This will result in having the
143 * {@link ChannelHandler#read(ChannelHandlerContext)}
144 * method called of the next {@link ChannelHandler} contained in the {@link ChannelPipeline} of the
145 * {@link Channel}.
146 */
147 ChannelOutboundInvoker read();
148
149 /**
150 * Request to write a message via this {@link ChannelHandlerContext} through the {@link ChannelPipeline}.
151 * This method will not request to actual flush, so be sure to call {@link #flush()}
152 * once you want to request to flush all pending data to the actual transport.
153 */
154 Future<Void> write(Object msg);
155
156 /**
157 * Request to flush all pending messages via this ChannelOutboundInvoker.
158 */
159 ChannelOutboundInvoker flush();
160
161 /**
162 * Shortcut for call {@link #write(Object)} and {@link #flush()}.
163 */
164 Future<Void> writeAndFlush(Object msg);
165
166 /**
167 * Send a custom outbound event via this {@link ChannelOutboundInvoker} through the
168 * {@link ChannelPipeline}.
169 * <p>
170 * This will result in having the
171 * {@link ChannelHandler#sendOutboundEvent(ChannelHandlerContext, Object)}
172 * method called of the next {@link ChannelHandler} contained in the {@link ChannelPipeline} of the
173 * {@link Channel}.
174 */
175 Future<Void> sendOutboundEvent(Object event);
176
177 @Override
178 default <V> Promise<V> newPromise() {
179 return executor().newPromise();
180 }
181
182 @Override
183 default <V> Future<V> newSucceededFuture(V value) {
184 return executor().newSucceededFuture(value);
185 }
186
187 @Override
188 default <V> Future<V> newFailedFuture(Throwable cause) {
189 return executor().newFailedFuture(cause);
190 }
191
192 @Override
193 default Future<Void> newSucceededFuture() {
194 return executor().newSucceededFuture();
195 }
196
197 /**
198 * Returns the {@link EventExecutor} that is used to execute the operations of this {@link ChannelOutboundInvoker}.
199 *
200 * @return the executor.
201 */
202 EventExecutor executor();
203 }