View Javadoc
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#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&lt;T&gt; 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 }