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 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 }