1 /*
2 * Copyright 2012 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.netty.channel;
17
18 import io.netty.buffer.ByteBufAllocator;
19 import io.netty.channel.socket.SocketChannelConfig;
20
21 import java.nio.ByteBuffer;
22 import java.nio.channels.WritableByteChannel;
23 import java.util.Map;
24
25 /**
26 * A set of configuration properties of a {@link Channel}.
27 * <p>
28 * Please down-cast to more specific configuration type such as
29 * {@link SocketChannelConfig} or use {@link #setOptions(Map)} to set the
30 * transport-specific properties:
31 * <pre>
32 * {@link Channel} ch = ...;
33 * {@link SocketChannelConfig} cfg = <strong>({@link SocketChannelConfig}) ch.getConfig();</strong>
34 * cfg.setTcpNoDelay(false);
35 * </pre>
36 *
37 * <h3>Option map</h3>
38 *
39 * An option map property is a dynamic write-only property which allows
40 * the configuration of a {@link Channel} without down-casting its associated
41 * {@link ChannelConfig}. To update an option map, please call {@link #setOptions(Map)}.
42 * <p>
43 * All {@link ChannelConfig} has the following options:
44 *
45 * <table border="1" cellspacing="0" cellpadding="6">
46 * <tr>
47 * <th>Name</th><th>Associated setter method</th>
48 * </tr><tr>
49 * <td>{@link ChannelOption#CONNECT_TIMEOUT_MILLIS}</td><td>{@link #setConnectTimeoutMillis(int)}</td>
50 * </tr><tr>
51 * <td>{@link ChannelOption#WRITE_SPIN_COUNT}</td><td>{@link #setWriteSpinCount(int)}</td>
52 * </tr><tr>
53 * <td>{@link ChannelOption#WRITE_BUFFER_WATER_MARK}</td><td>{@link #setWriteBufferWaterMark(WriteBufferWaterMark)}</td>
54 * </tr><tr>
55 * <td>{@link ChannelOption#ALLOCATOR}</td><td>{@link #setAllocator(ByteBufAllocator)}</td>
56 * </tr><tr>
57 * <td>{@link ChannelOption#AUTO_READ}</td><td>{@link #setAutoRead(boolean)}</td>
58 * </tr>
59 * </table>
60 * <p>
61 * More options are available in the sub-types of {@link ChannelConfig}. For
62 * example, you can configure the parameters which are specific to a TCP/IP
63 * socket as explained in {@link SocketChannelConfig}.
64 */
65 public interface ChannelConfig {
66
67 /**
68 * Return all set {@link ChannelOption}'s.
69 */
70 Map<ChannelOption<?>, Object> getOptions();
71
72 /**
73 * Sets the configuration properties from the specified {@link Map}.
74 */
75 boolean setOptions(Map<ChannelOption<?>, ?> options);
76
77 /**
78 * Return the value of the given {@link ChannelOption}
79 */
80 <T> T getOption(ChannelOption<T> option);
81
82 /**
83 * Sets a configuration property with the specified name and value.
84 * To override this method properly, you must call the super class:
85 * <pre>
86 * public boolean setOption(ChannelOption<T> option, T value) {
87 * if (super.setOption(option, value)) {
88 * return true;
89 * }
90 *
91 * if (option.equals(additionalOption)) {
92 * ....
93 * return true;
94 * }
95 *
96 * return false;
97 * }
98 * </pre>
99 *
100 * @return {@code true} if and only if the property has been set
101 */
102 <T> boolean setOption(ChannelOption<T> option, T value);
103
104 /**
105 * Returns the connect timeout of the channel in milliseconds. If the
106 * {@link Channel} does not support connect operation, this property is not
107 * used at all, and therefore will be ignored.
108 *
109 * @return the connect timeout in milliseconds. {@code 0} if disabled.
110 */
111 int getConnectTimeoutMillis();
112
113 /**
114 * Sets the connect timeout of the channel in milliseconds. If the
115 * {@link Channel} does not support connect operation, this property is not
116 * used at all, and therefore will be ignored.
117 *
118 * @param connectTimeoutMillis the connect timeout in milliseconds.
119 * {@code 0} to disable.
120 */
121 ChannelConfig setConnectTimeoutMillis(int connectTimeoutMillis);
122
123 /**
124 * @deprecated Use {@link MaxMessagesRecvByteBufAllocator} and
125 * {@link MaxMessagesRecvByteBufAllocator#maxMessagesPerRead()}.
126 * <p>
127 * Returns the maximum number of messages to read per read loop.
128 * a {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object) channelRead()} event.
129 * If this value is greater than 1, an event loop might attempt to read multiple times to procure multiple messages.
130 */
131 @Deprecated
132 int getMaxMessagesPerRead();
133
134 /**
135 * @deprecated Use {@link MaxMessagesRecvByteBufAllocator} and
136 * {@link MaxMessagesRecvByteBufAllocator#maxMessagesPerRead(int)}.
137 * <p>
138 * Sets the maximum number of messages to read per read loop.
139 * If this value is greater than 1, an event loop might attempt to read multiple times to procure multiple messages.
140 */
141 @Deprecated
142 ChannelConfig setMaxMessagesPerRead(int maxMessagesPerRead);
143
144 /**
145 * Returns the maximum loop count for a write operation until
146 * {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
147 * It is similar to what a spin lock is used for in concurrency programming.
148 * It improves memory utilization and write throughput depending on
149 * the platform that JVM runs on. The default value is {@code 16}.
150 */
151 int getWriteSpinCount();
152
153 /**
154 * Sets the maximum loop count for a write operation until
155 * {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
156 * It is similar to what a spin lock is used for in concurrency programming.
157 * It improves memory utilization and write throughput depending on
158 * the platform that JVM runs on. The default value is {@code 16}.
159 *
160 * @throws IllegalArgumentException
161 * if the specified value is {@code 0} or less than {@code 0}
162 */
163 ChannelConfig setWriteSpinCount(int writeSpinCount);
164
165 /**
166 * Returns {@link ByteBufAllocator} which is used for the channel
167 * to allocate buffers.
168 */
169 ByteBufAllocator getAllocator();
170
171 /**
172 * Set the {@link ByteBufAllocator} which is used for the channel
173 * to allocate buffers.
174 */
175 ChannelConfig setAllocator(ByteBufAllocator allocator);
176
177 /**
178 * Returns {@link RecvByteBufAllocator} which is used for the channel to allocate receive buffers.
179 */
180 <T extends RecvByteBufAllocator> T getRecvByteBufAllocator();
181
182 /**
183 * Set the {@link RecvByteBufAllocator} which is used for the channel to allocate receive buffers.
184 */
185 ChannelConfig setRecvByteBufAllocator(RecvByteBufAllocator allocator);
186
187 /**
188 * Returns {@code true} if and only if {@link ChannelHandlerContext#read()} will be invoked automatically so that
189 * a user application doesn't need to call it at all. The default value is {@code true}.
190 */
191 boolean isAutoRead();
192
193 /**
194 * Sets if {@link ChannelHandlerContext#read()} will be invoked automatically so that a user application doesn't
195 * need to call it at all. The default value is {@code true}.
196 */
197 ChannelConfig setAutoRead(boolean autoRead);
198
199 /**
200 * Returns {@code true} if and only if the {@link Channel} will be closed automatically and immediately on
201 * write failure. The default is {@code true}.
202 */
203 boolean isAutoClose();
204
205 /**
206 * Sets whether the {@link Channel} should be closed automatically and immediately on write failure.
207 * The default is {@code true}.
208 */
209 ChannelConfig setAutoClose(boolean autoClose);
210
211 /**
212 * Returns the high water mark of the write buffer. If the number of bytes
213 * queued in the write buffer exceeds this value, {@link Channel#isWritable()}
214 * will start to return {@code false}.
215 */
216 int getWriteBufferHighWaterMark();
217
218 /**
219 * <p>
220 * Sets the high water mark of the write buffer. If the number of bytes
221 * queued in the write buffer exceeds this value, {@link Channel#isWritable()}
222 * will start to return {@code false}.
223 */
224 ChannelConfig setWriteBufferHighWaterMark(int writeBufferHighWaterMark);
225
226 /**
227 * Returns the low water mark of the write buffer. Once the number of bytes
228 * queued in the write buffer exceeded the
229 * {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
230 * dropped down below this value, {@link Channel#isWritable()} will start to return
231 * {@code true} again.
232 */
233 int getWriteBufferLowWaterMark();
234
235 /**
236 * <p>
237 * Sets the low water mark of the write buffer. Once the number of bytes
238 * queued in the write buffer exceeded the
239 * {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
240 * dropped down below this value, {@link Channel#isWritable()} will start to return
241 * {@code true} again.
242 */
243 ChannelConfig setWriteBufferLowWaterMark(int writeBufferLowWaterMark);
244
245 /**
246 * Returns {@link MessageSizeEstimator} which is used for the channel
247 * to detect the size of a message.
248 */
249 MessageSizeEstimator getMessageSizeEstimator();
250
251 /**
252 * Set the {@link MessageSizeEstimator} which is used for the channel
253 * to detect the size of a message.
254 */
255 ChannelConfig setMessageSizeEstimator(MessageSizeEstimator estimator);
256
257 /**
258 * Returns the {@link WriteBufferWaterMark} which is used for setting the high and low
259 * water mark of the write buffer.
260 */
261 WriteBufferWaterMark getWriteBufferWaterMark();
262
263 /**
264 * Set the {@link WriteBufferWaterMark} which is used for setting the high and low
265 * water mark of the write buffer.
266 */
267 ChannelConfig setWriteBufferWaterMark(WriteBufferWaterMark writeBufferWaterMark);
268 }