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 }