View Javadoc

    1   /*
    2    * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/params/HttpConnectionParams.java,v 1.6 2004/09/15 20:32:21 olegk Exp $
    3    * $Revision: 480424 $
    4    * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
    5    *
    6    * ====================================================================
    7    *
    8    *  Licensed to the Apache Software Foundation (ASF) under one or more
    9    *  contributor license agreements.  See the NOTICE file distributed with
    10   *  this work for additional information regarding copyright ownership.
    11   *  The ASF licenses this file to You under the Apache License, Version 2.0
    12   *  (the "License"); you may not use this file except in compliance with
    13   *  the License.  You may obtain a copy of the License at
    14   *
    15   *      http://www.apache.org/licenses/LICENSE-2.0
    16   *
    17   *  Unless required by applicable law or agreed to in writing, software
    18   *  distributed under the License is distributed on an "AS IS" BASIS,
    19   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    20   *  See the License for the specific language governing permissions and
    21   *  limitations under the License.
    22   * ====================================================================
    23   *
    24   * This software consists of voluntary contributions made by many
    25   * individuals on behalf of the Apache Software Foundation.  For more
    26   * information on the Apache Software Foundation, please see
    27   * <http://www.apache.org/>.
    28   *
    29   */
    30
    31  package org.apache.commons.httpclient.params;
    32
    33  /**
    34   * This class represents a collection of HTTP protocol parameters applicable to
    35   * {@link org.apache.commons.httpclient.HttpConnection HTTP connections}.
    36   * Protocol parameters may be linked together to form a hierarchy. If a particular
    37   * parameter value has not been explicitly defined in the collection itself, its
    38   * value will be drawn from the parent collection of parameters.
    39   *
    40   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
    41   *
    42   * @version $Revision: 480424 $
    43   *
    44   * @since 3.0
    45   */
    46  public class HttpConnectionParams extends DefaultHttpParams {
    47
    48      /**
    49       * Defines the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
    50       * timeout for waiting for data. A timeout value of zero is interpreted as an infinite
    51       * timeout. This value is used when no socket timeout is set in the
    52       * {@link HttpMethodParams HTTP method parameters}.
    53       * <p>
    54       * This parameter expects a value of type {@link Integer}.
    55       * </p>
    56       * @see java.net.SocketOptions#SO_TIMEOUT
    57       */
    58      public static final String SO_TIMEOUT = "http.socket.timeout";
    59
    60      /**
    61       * Determines whether Nagle's algorithm is to be used. The Nagle's algorithm
    62       * tries to conserve bandwidth by minimizing the number of segments that are
    63       * sent. When applications wish to decrease network latency and increase
    64       * performance, they can disable Nagle's algorithm (that is enable TCP_NODELAY).
    65       * Data will be sent earlier, at the cost of an increase in bandwidth consumption.
    66       * <p>
    67       * This parameter expects a value of type {@link Boolean}.
    68       * </p>
    69       * @see java.net.SocketOptions#TCP_NODELAY
    70       */
    71      public static final String TCP_NODELAY = "http.tcp.nodelay";
    72
    73      /**
    74       * Determines a hint the size of the underlying buffers used by the platform
    75       * for outgoing network I/O. This value is a suggestion to the kernel from
    76       * the application about the size of buffers to use for the data to be sent
    77       * over the socket.
    78       * <p>
    79       * This parameter expects a value of type {@link Integer}.
    80       * </p>
    81       * @see java.net.SocketOptions#SO_SNDBUF
    82       */
    83      public static final String SO_SNDBUF = "http.socket.sendbuffer";
    84
    85      /**
    86       * Determines a hint the size of the underlying buffers used by the platform
    87       * for incoming network I/O. This value is a suggestion to the kernel from
    88       * the application about the size of buffers to use for the data to be received
    89       * over the socket.
    90       * <p>
    91       * This parameter expects a value of type {@link Integer}.
    92       * </p>
    93       * @see java.net.SocketOptions#SO_RCVBUF
    94       */
    95      public static final String SO_RCVBUF = "http.socket.receivebuffer";
    96
    97      /**
    98       * Sets SO_LINGER with the specified linger time in seconds. The maximum timeout
    99       * value is platform specific. Value <tt>0</tt> implies that the option is disabled.
    100      * Value <tt>-1</tt> implies that the JRE default is used. The setting only affects
    101      * socket close.
    102      * <p>
    103      * This parameter expects a value of type {@link Integer}.
    104      * </p>
    105      * @see java.net.SocketOptions#SO_LINGER
    106      */
    107     public static final String SO_LINGER = "http.socket.linger";
    108
    109     /**
    110      * Determines the timeout until a connection is etablished. A value of zero
    111      * means the timeout is not used. The default value is zero.
    112      * <p>
    113      * This parameter expects a value of type {@link Integer}.
    114      * </p>
    115      */
    116     public static final String CONNECTION_TIMEOUT = "http.connection.timeout";
    117
    118     /**
    119      * Determines whether stale connection check is to be used. Disabling
    120      * stale connection check may result in slight performance improvement
    121      * at the risk of getting an I/O error when executing a request over a
    122      * connection that has been closed at the server side.
    123      * <p>
    124      * This parameter expects a value of type {@link Boolean}.
    125      * </p>
    126      */
    127     public static final String STALE_CONNECTION_CHECK = "http.connection.stalecheck";
    128
    129     /**
    130      * Creates a new collection of parameters with the collection returned
    131      * by {@link #getDefaultParams()} as a parent. The collection will defer
    132      * to its parent for a default value if a particular parameter is not
    133      * explicitly set in the collection itself.
    134      *
    135      * @see #getDefaultParams()
    136      */
    137     public HttpConnectionParams() {
    138         super();
    139     }
    140
    141     /**
    142      * Returns the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
    143      * timeout for waiting for data. A timeout value of zero is interpreted as an infinite
    144      * timeout. This value is used when no socket timeout is set in the
    145      * {@link HttpMethodParams HTTP method parameters}.
    146      *
    147      * @return timeout in milliseconds
    148      */
    149     public int getSoTimeout() {
    150         return getIntParameter(SO_TIMEOUT, 0);
    151     }
    152
    153     /**
    154      * Sets the default socket timeout (<tt>SO_TIMEOUT</tt>) in milliseconds which is the
    155      * timeout for waiting for data. A timeout value of zero is interpreted as an infinite
    156      * timeout. This value is used when no socket timeout is set in the
    157      * {@link HttpMethodParams HTTP method parameters}.
    158      *
    159      * @param timeout Timeout in milliseconds
    160      */
    161     public void setSoTimeout(int timeout) {
    162         setIntParameter(SO_TIMEOUT, timeout);
    163     }
    164
    165     /**
    166      * Determines whether Nagle's algorithm is to be used. The Nagle's algorithm
    167      * tries to conserve bandwidth by minimizing the number of segments that are
    168      * sent. When applications wish to decrease network latency and increase
    169      * performance, they can disable Nagle's algorithm (that is enable TCP_NODELAY).
    170      * Data will be sent earlier, at the cost of an increase in bandwidth consumption.
    171      *
    172      * @param value <tt>true</tt> if the Nagle's algorithm is to NOT be used
    173      *   (that is enable TCP_NODELAY), <tt>false</tt> otherwise.
    174      */
    175     public void setTcpNoDelay(boolean value) {
    176         setBooleanParameter(TCP_NODELAY, value);
    177     }
    178
    179     /**
    180      * Tests if Nagle's algorithm is to be used.
    181      *
    182      * @return <tt>true</tt> if the Nagle's algorithm is to NOT be used
    183      *   (that is enable TCP_NODELAY), <tt>false</tt> otherwise.
    184      */
    185     public boolean getTcpNoDelay() {
    186         return getBooleanParameter(TCP_NODELAY, true);
    187     }
    188
    189     /**
    190      * Returns a hint the size of the underlying buffers used by the platform for
    191      * outgoing network I/O. This value is a suggestion to the kernel from the
    192      * application about the size of buffers to use for the data to be sent over
    193      * the socket.
    194      *
    195      * @return the hint size of the send buffer
    196      */
    197     public int getSendBufferSize() {
    198         return getIntParameter(SO_SNDBUF, -1);
    199     }
    200
    201     /**
    202      * Sets a hint the size of the underlying buffers used by the platform for
    203      * outgoing network I/O. This value is a suggestion to the kernel from the
    204      * application about the size of buffers to use for the data to be sent over
    205      * the socket.
    206      *
    207      * @param size the hint size of the send buffer
    208      */
    209     public void setSendBufferSize(int size) {
    210         setIntParameter(SO_SNDBUF, size);
    211     }
    212
    213     /**
    214      * Returns a hint the size of the underlying buffers used by the platform
    215      * for incoming network I/O. This value is a suggestion to the kernel from
    216      * the application about the size of buffers to use for the data to be received
    217      * over the socket.
    218      *
    219      * @return the hint size of the send buffer
    220      */
    221     public int getReceiveBufferSize() {
    222         return getIntParameter(SO_RCVBUF, -1);
    223     }
    224
    225     /**
    226      * Sets a hint the size of the underlying buffers used by the platform
    227      * for incoming network I/O. This value is a suggestion to the kernel from
    228      * the application about the size of buffers to use for the data to be received
    229      * over the socket.
    230      *
    231      * @param size the hint size of the send buffer
    232      */
    233     public void setReceiveBufferSize(int size) {
    234         setIntParameter(SO_RCVBUF, size);
    235     }
    236
    237     /**
    238      * Returns linger-on-close timeout. Value <tt>0</tt> implies that the option is
    239      * disabled. Value <tt>-1</tt> implies that the JRE default is used.
    240      *
    241      * @return the linger-on-close timeout
    242      */
    243     public int getLinger() {
    244         return getIntParameter(SO_LINGER, -1);
    245     }
    246
    247     /**
    248      * Returns linger-on-close timeout. This option disables/enables immediate return
    249      * from a close() of a TCP Socket. Enabling this option with a non-zero Integer
    250      * timeout means that a close() will block pending the transmission and
    251      * acknowledgement of all data written to the peer, at which point the socket is
    252      * closed gracefully. Value <tt>0</tt> implies that the option is
    253      * disabled. Value <tt>-1</tt> implies that the JRE default is used.
    254      *
    255      * @param value the linger-on-close timeout
    256      */
    257     public void setLinger(int value) {
    258         setIntParameter(SO_LINGER, value);
    259     }
    260
    261     /**
    262      * Returns the timeout until a connection is etablished. A value of zero
    263      * means the timeout is not used. The default value is zero.
    264      *
    265      * @return timeout in milliseconds.
    266      */
    267     public int getConnectionTimeout() {
    268         return getIntParameter(CONNECTION_TIMEOUT, 0);
    269     }
    270
    271     /**
    272      * Sets the timeout until a connection is etablished. A value of zero
    273      * means the timeout is not used. The default value is zero.
    274      *
    275      * @param timeout Timeout in milliseconds.
    276      */
    277     public void setConnectionTimeout(int timeout) {
    278         setIntParameter(CONNECTION_TIMEOUT, timeout);
    279     }
    280
    281     /**
    282      * Tests whether stale connection check is to be used. Disabling
    283      * stale connection check may result in slight performance improvement
    284      * at the risk of getting an I/O error when executing a request over a
    285      * connection that has been closed at the server side.
    286      *
    287      * @return <tt>true</tt> if stale connection check is to be used,
    288      *   <tt>false</tt> otherwise.
    289      */
    290     public boolean isStaleCheckingEnabled() {
    291         return getBooleanParameter(STALE_CONNECTION_CHECK, true);
    292     }
    293
    294     /**
    295      * Defines whether stale connection check is to be used. Disabling
    296      * stale connection check may result in slight performance improvement
    297      * at the risk of getting an I/O error when executing a request over a
    298      * connection that has been closed at the server side.
    299      *
    300      * @param value <tt>true</tt> if stale connection check is to be used,
    301      *   <tt>false</tt> otherwise.
    302      */
    303     public void setStaleCheckingEnabled(boolean value) {
    304         setBooleanParameter(STALE_CONNECTION_CHECK, value);
    305     }
    306 }