View Javadoc

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 }