1 /*
2 * Copyright 2009 Red Hat, Inc.
3 *
4 * Red Hat licenses this file to you under the Apache License, version 2.0
5 * (the "License"); you may not use this file except in compliance with the
6 * 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 * @author <a href="http://www.jboss.org/netty/">The Netty Project</a>
64 * @author <a href="http://gleamynode.net/">Trustin Lee</a>
65 *
66 * @version $Rev: 2122 $, $Date: 2010-02-02 11:00:04 +0900 (Tue, 02 Feb 2010) $
67 *
68 * @apiviz.has org.jboss.netty.channel.ChannelPipelineFactory
69 * @apiviz.composedOf org.jboss.netty.channel.ReceiveBufferSizePredictor
70 *
71 * @apiviz.excludeSubtypes
72 */
73 public interface ChannelConfig {
74
75 /**
76 * Sets the configuration properties from the specified {@link Map}.
77 */
78 void setOptions(Map<String, Object> options);
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(String name, Object value) {
85 * if (super.setOption(name, value)) {
86 * return true;
87 * }
88 *
89 * if (name.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 boolean setOption(String name, Object value);
101
102 /**
103 * Returns the default {@link ChannelBufferFactory} used to create a new
104 * {@link ChannelBuffer}. The default is {@link HeapChannelBufferFactory}.
105 * You can specify a different factory to change the default
106 * {@link ByteOrder} for example.
107 */
108 ChannelBufferFactory getBufferFactory();
109
110 /**
111 * Sets the default {@link ChannelBufferFactory} used to create a new
112 * {@link ChannelBuffer}. The default is {@link HeapChannelBufferFactory}.
113 * You can specify a different factory to change the default
114 * {@link ByteOrder} for example.
115 */
116 void setBufferFactory(ChannelBufferFactory bufferFactory);
117
118 /**
119 * Returns the {@link ChannelPipelineFactory} which will be used when
120 * a child channel is created. If the {@link Channel} does not create
121 * a child channel, this property is not used at all, and therefore will
122 * be ignored.
123 */
124 ChannelPipelineFactory getPipelineFactory();
125
126 /**
127 * Sets the {@link ChannelPipelineFactory} which will be used when
128 * a child channel is created. If the {@link Channel} does not create
129 * a child channel, this property is not used at all, and therefore will
130 * be ignored.
131 */
132 void setPipelineFactory(ChannelPipelineFactory pipelineFactory);
133
134 /**
135 * Returns the connect timeout of the channel in milliseconds. If the
136 * {@link Channel} does not support connect operation, this property is not
137 * used at all, and therefore will be ignored.
138 *
139 * @return the connect timeout in milliseconds. {@code 0} if disabled.
140 */
141 int getConnectTimeoutMillis();
142
143 /**
144 * Sets the connect timeout of the channel in milliseconds. If the
145 * {@link Channel} does not support connect operation, this property is not
146 * used at all, and therefore will be ignored.
147 *
148 * @param connectTimeoutMillis the connect timeout in milliseconds.
149 * {@code 0} to disable.
150 */
151 void setConnectTimeoutMillis(int connectTimeoutMillis);
152 }