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 org.jboss.netty.channel;
17
18 import java.nio.ByteOrder;
19 import java.util.Map;
20
21 import org.jboss.netty.buffer.ChannelBuffer;
22 import org.jboss.netty.buffer.ChannelBufferFactory;
23 import org.jboss.netty.buffer.HeapChannelBufferFactory;
24 import org.jboss.netty.channel.socket.SocketChannelConfig;
25 import org.jboss.netty.channel.socket.nio.NioSocketChannelConfig;
26
27 /**
28 * A set of configuration properties of a {@link Channel}.
29 * <p>
30 * Please down-cast to more specific configuration type such as
31 * {@link SocketChannelConfig} or use {@link #setOptions(Map)} to set the
32 * transport-specific properties:
33 * <pre>
34 * {@link Channel} ch = ...;
35 * {@link SocketChannelConfig} cfg = <strong>({@link SocketChannelConfig}) ch.getConfig();</strong>
36 * cfg.setTcpNoDelay(false);
37 * </pre>
38 *
39 * <h3>Option map</h3>
40 *
41 * An option map property is a dynamic write-only property which allows
42 * the configuration of a {@link Channel} without down-casting its associated
43 * {@link ChannelConfig}. To update an option map, please call {@link #setOptions(Map)}.
44 * <p>
45 * All {@link ChannelConfig} has the following options:
46 *
47 * <table border="1" cellspacing="0" cellpadding="6">
48 * <tr>
49 * <th>Name</th><th>Associated setter method</th>
50 * </tr><tr>
51 * <td>{@code "bufferFactory"}</td><td>{@link #setBufferFactory(ChannelBufferFactory)}</td>
52 * </tr><tr>
53 * <td>{@code "connectTimeoutMillis"}</td><td>{@link #setConnectTimeoutMillis(int)}</td>
54 * </tr><tr>
55 * <td>{@code "pipelineFactory"}</td><td>{@link #setPipelineFactory(ChannelPipelineFactory)}</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} or {@link NioSocketChannelConfig}.
62 *
63 * @apiviz.has org.jboss.netty.channel.ChannelPipelineFactory
64 * @apiviz.composedOf org.jboss.netty.channel.ReceiveBufferSizePredictor
65 *
66 * @apiviz.excludeSubtypes
67 */
68 public interface ChannelConfig {
69
70 /**
71 * Sets the configuration properties from the specified {@link Map}.
72 */
73 void setOptions(Map<String, Object> options);
74
75 /**
76 * Sets a configuration property with the specified name and value.
77 * To override this method properly, you must call the super class:
78 * <pre>
79 * public boolean setOption(String name, Object value) {
80 * if (super.setOption(name, value)) {
81 * return true;
82 * }
83 *
84 * if (name.equals("additionalOption")) {
85 * ....
86 * return true;
87 * }
88 *
89 * return false;
90 * }
91 * </pre>
92 *
93 * @return {@code true} if and only if the property has been set
94 */
95 boolean setOption(String name, Object value);
96
97 /**
98 * Returns the default {@link ChannelBufferFactory} used to create a new
99 * {@link ChannelBuffer}. The default is {@link HeapChannelBufferFactory}.
100 * You can specify a different factory to change the default
101 * {@link ByteOrder} for example.
102 */
103 ChannelBufferFactory getBufferFactory();
104
105 /**
106 * Sets the default {@link ChannelBufferFactory} used to create a new
107 * {@link ChannelBuffer}. The default is {@link HeapChannelBufferFactory}.
108 * You can specify a different factory to change the default
109 * {@link ByteOrder} for example.
110 */
111 void setBufferFactory(ChannelBufferFactory bufferFactory);
112
113 /**
114 * Returns the {@link ChannelPipelineFactory} which will be used when
115 * a child channel is created. If the {@link Channel} does not create
116 * a child channel, this property is not used at all, and therefore will
117 * be ignored.
118 */
119 ChannelPipelineFactory getPipelineFactory();
120
121 /**
122 * Sets the {@link ChannelPipelineFactory} which will be used when
123 * a child channel is created. If the {@link Channel} does not create
124 * a child channel, this property is not used at all, and therefore will
125 * be ignored.
126 */
127 void setPipelineFactory(ChannelPipelineFactory pipelineFactory);
128
129 /**
130 * Returns the connect timeout of the channel in milliseconds. If the
131 * {@link Channel} does not support connect operation, this property is not
132 * used at all, and therefore will be ignored.
133 *
134 * @return the connect timeout in milliseconds. {@code 0} if disabled.
135 */
136 int getConnectTimeoutMillis();
137
138 /**
139 * Sets the connect timeout of the channel in milliseconds. If the
140 * {@link Channel} does not support connect operation, this property is not
141 * used at all, and therefore will be ignored.
142 *
143 * @param connectTimeoutMillis the connect timeout in milliseconds.
144 * {@code 0} to disable.
145 */
146 void setConnectTimeoutMillis(int connectTimeoutMillis);
147 }