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