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 * http://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#ALLOCATOR}</td><td>{@link #setAllocator(ByteBufAllocator)}</td>
54 * </tr><tr>
55 * <td>{@link ChannelOption#AUTO_READ}</td><td>{@link #setAutoRead(boolean)}</td>
56 * </tr>
57 * </table>
58 * <p>
59 * More options are available in the sub-types of {@link ChannelConfig}. For
60 * example, you can configure the parameters which are specific to a TCP/IP
61 * socket as explained in {@link SocketChannelConfig}.
62 */
63 public interface ChannelConfig {
64
65 /**
66 * Return all set {@link ChannelOption}'s.
67 */
68 Map<ChannelOption<?>, Object> getOptions();
69
70 /**
71 * Sets the configuration properties from the specified {@link Map}.
72 */
73 boolean setOptions(Map<ChannelOption<?>, ?> options);
74
75 /**
76 * Return the value of the given {@link ChannelOption}
77 */
78 <T> T getOption(ChannelOption<T> option);
79
80 /**
81 * Sets a configuration property with the specified name and value.
82 * To override this method properly, you must call the super class:
83 * <pre>
84 * public boolean setOption(ChannelOption<T> option, T value) {
85 * if (super.setOption(option, value)) {
86 * return true;
87 * }
88 *
89 * if (option.equals(additionalOption)) {
90 * ....
91 * return true;
92 * }
93 *
94 * return false;
95 * }
96 * </pre>
97 *
98 * @return {@code true} if and only if the property has been set
99 */
100 <T> boolean setOption(ChannelOption<T> option, T value);
101
102 /**
103 * Returns the connect timeout of the channel in milliseconds. If the
104 * {@link Channel} does not support connect operation, this property is not
105 * used at all, and therefore will be ignored.
106 *
107 * @return the connect timeout in milliseconds. {@code 0} if disabled.
108 */
109 int getConnectTimeoutMillis();
110
111 /**
112 * Sets the connect timeout of the channel in milliseconds. If the
113 * {@link Channel} does not support connect operation, this property is not
114 * used at all, and therefore will be ignored.
115 *
116 * @param connectTimeoutMillis the connect timeout in milliseconds.
117 * {@code 0} to disable.
118 */
119 ChannelConfig setConnectTimeoutMillis(int connectTimeoutMillis);
120
121 /**
122 * Returns the maximum number of messages to read per read loop.
123 * a {@link ChannelInboundHandler#channelRead(ChannelHandlerContext, Object) channelRead()} event.
124 * If this value is greater than 1, an event loop might attempt to read multiple times to procure multiple messages.
125 */
126 int getMaxMessagesPerRead();
127
128 /**
129 * Sets the maximum number of messages to read per read loop.
130 * If this value is greater than 1, an event loop might attempt to read multiple times to procure multiple messages.
131 */
132 ChannelConfig setMaxMessagesPerRead(int maxMessagesPerRead);
133
134 /**
135 * Returns the maximum loop count for a write operation until
136 * {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
137 * It is similar to what a spin lock is used for in concurrency programming.
138 * It improves memory utilization and write throughput depending on
139 * the platform that JVM runs on. The default value is {@code 16}.
140 */
141 int getWriteSpinCount();
142
143 /**
144 * Sets the maximum loop count for a write operation until
145 * {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
146 * It is similar to what a spin lock is used for in concurrency programming.
147 * It improves memory utilization and write throughput depending on
148 * the platform that JVM runs on. The default value is {@code 16}.
149 *
150 * @throws IllegalArgumentException
151 * if the specified value is {@code 0} or less than {@code 0}
152 */
153 ChannelConfig setWriteSpinCount(int writeSpinCount);
154
155 /**
156 * Returns {@link ByteBufAllocator} which is used for the channel
157 * to allocate buffers.
158 */
159 ByteBufAllocator getAllocator();
160
161 /**
162 * Set the {@link ByteBufAllocator} which is used for the channel
163 * to allocate buffers.
164 */
165 ChannelConfig setAllocator(ByteBufAllocator allocator);
166
167 /**
168 * Returns {@link RecvByteBufAllocator} which is used for the channel
169 * to allocate receive buffers.
170 */
171 RecvByteBufAllocator getRecvByteBufAllocator();
172
173 /**
174 * Set the {@link ByteBufAllocator} which is used for the channel
175 * to allocate receive buffers.
176 */
177 ChannelConfig setRecvByteBufAllocator(RecvByteBufAllocator allocator);
178
179 /**
180 * Returns {@code true} if and only if {@link ChannelHandlerContext#read()} will be invoked automatically so that
181 * a user application doesn't need to call it at all. The default value is {@code true}.
182 */
183 boolean isAutoRead();
184
185 /**
186 * Sets if {@link ChannelHandlerContext#read()} will be invoked automatically so that a user application doesn't
187 * need to call it at all. The default value is {@code true}.
188 */
189 ChannelConfig setAutoRead(boolean autoRead);
190
191 /**
192 * @deprecated Auto close will be removed in a future release.
193 *
194 * Returns {@code true} if and only if the {@link Channel} will be closed automatically and immediately on
195 * write failure. The default is {@code false}.
196 */
197 @Deprecated
198 boolean isAutoClose();
199
200 /**
201 * @deprecated Auto close will be removed in a future release.
202 *
203 * Sets whether the {@link Channel} should be closed automatically and immediately on write failure.
204 * The default is {@code false}.
205 */
206 @Deprecated
207 ChannelConfig setAutoClose(boolean autoClose);
208
209 /**
210 * Returns the high water mark of the write buffer. If the number of bytes
211 * queued in the write buffer exceeds this value, {@link Channel#isWritable()}
212 * will start to return {@code false}.
213 */
214 int getWriteBufferHighWaterMark();
215
216 /**
217 * Sets the high water mark of the write buffer. If the number of bytes
218 * queued in the write buffer exceeds this value, {@link Channel#isWritable()}
219 * will start to return {@code false}.
220 */
221 ChannelConfig setWriteBufferHighWaterMark(int writeBufferHighWaterMark);
222
223 /**
224 * Returns the low water mark of the write buffer. Once the number of bytes
225 * queued in the write buffer exceeded the
226 * {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
227 * dropped down below this value, {@link Channel#isWritable()} will start to return
228 * {@code true} again.
229 */
230 int getWriteBufferLowWaterMark();
231
232 /**
233 * Sets the low water mark of the write buffer. Once the number of bytes
234 * queued in the write buffer exceeded the
235 * {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
236 * dropped down below this value, {@link Channel#isWritable()} will start to return
237 * {@code true} again.
238 */
239 ChannelConfig setWriteBufferLowWaterMark(int writeBufferLowWaterMark);
240
241 /**
242 * Returns {@link MessageSizeEstimator} which is used for the channel
243 * to detect the size of a message.
244 */
245 MessageSizeEstimator getMessageSizeEstimator();
246
247 /**
248 * Set the {@link MessageSizeEstimator} which is used for the channel
249 * to detect the size of a message.
250 */
251 ChannelConfig setMessageSizeEstimator(MessageSizeEstimator estimator);
252 }