View Javadoc

    1   /*
    2    * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/HttpConnectionManager.java,v 1.24 2004/07/05 22:46:58 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;
    32
    33  import org.apache.commons.httpclient.params.HttpConnectionManagerParams;
    34
    35  /**
    36   * An interface for classes that manage HttpConnections.
    37   *
    38   * @see org.apache.commons.httpclient.HttpConnection
    39   * @see org.apache.commons.httpclient.HttpClient#HttpClient(HttpConnectionManager)
    40   *
    41   * @author Michael Becke
    42   * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
    43   * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
    44   *
    45   * @since 2.0
    46   */
    47  public interface HttpConnectionManager {
    48
    49      /**
    50       * Gets an HttpConnection for a given host configuration. If a connection is
    51       * not available this method will block until one is.
    52       *
    53       * The connection manager should be registered with any HttpConnection that
    54       * is created.
    55       *
    56       * @param hostConfiguration the host configuration to use to configure the
    57       * connection
    58       *
    59       * @return an HttpConnection for the given configuration
    60       *
    61       * @see HttpConnection#setHttpConnectionManager(HttpConnectionManager)
    62       */
    63      HttpConnection getConnection(HostConfiguration hostConfiguration);
    64
    65      /**
    66       * Gets an HttpConnection for a given host configuration. If a connection is
    67       * not available, this method will block for at most the specified number of
    68       * milliseconds or until a connection becomes available.
    69       *
    70       * The connection manager should be registered with any HttpConnection that
    71       * is created.
    72       *
    73       * @param hostConfiguration the host configuration to use to configure the
    74       * connection
    75       * @param timeout - the time (in milliseconds) to wait for a connection to
    76       * become available, 0 to specify an infinite timeout
    77       *
    78       * @return an HttpConnection for the given configuraiton
    79       *
    80       * @throws HttpException if no connection becomes available before the
    81       * timeout expires
    82       *
    83       * @see HttpConnection#setHttpConnectionManager(HttpConnectionManager)
    84       *
    85       * @deprecated Use #getConnectionWithTimeout(HostConfiguration, long)
    86       */
    87      HttpConnection getConnection(HostConfiguration hostConfiguration, long timeout)
    88          throws HttpException;
    89
    90  	/**
    91  	 * Gets an HttpConnection for a given host configuration. If a connection is
    92  	 * not available, this method will block for at most the specified number of
    93  	 * milliseconds or until a connection becomes available.
    94  	 *
    95  	 * The connection manager should be registered with any HttpConnection that
    96  	 * is created.
    97  	 *
    98  	 * @param hostConfiguration the host configuration to use to configure the
    99  	 * connection
    100 	 * @param timeout - the time (in milliseconds) to wait for a connection to
    101 	 * become available, 0 to specify an infinite timeout
    102 	 *
    103 	 * @return an HttpConnection for the given configuraiton
    104 	 *
    105 	 * @throws ConnectionPoolTimeoutException if no connection becomes available before the
    106 	 * timeout expires
    107 	 *
    108 	 * @see HttpConnection#setHttpConnectionManager(HttpConnectionManager)
    109      *
    110      * @since 3.0
    111 	 */
    112 	HttpConnection getConnectionWithTimeout(HostConfiguration hostConfiguration, long timeout)
    113 		throws ConnectionPoolTimeoutException;
    114
    115     /**
    116      * Releases the given HttpConnection for use by other requests.
    117      *
    118      * @param conn - The HttpConnection to make available.
    119      */
    120     void releaseConnection(HttpConnection conn);
    121
    122     /**
    123      * Closes connections that have been idle for at least the given amount of time.  Only
    124      * connections that are currently owned, not checked out, are subject to idle timeouts.
    125      *
    126      * @param idleTimeout the minimum idle time, in milliseconds, for connections to be closed
    127      *
    128      * @since 3.0
    129      */
    130     void closeIdleConnections(long idleTimeout);
    131
    132     /**
    133      * Returns {@link HttpConnectionManagerParams parameters} associated
    134      * with this connection manager.
    135      *
    136      * @since 3.0
    137      *
    138      * @see HttpConnectionManagerParams
    139      */
    140     HttpConnectionManagerParams getParams();
    141
    142     /**
    143      * Assigns {@link HttpConnectionManagerParams parameters} for this
    144      * connection manager.
    145      *
    146      * @since 3.0
    147      *
    148      * @see HttpConnectionManagerParams
    149      */
    150     void setParams(final HttpConnectionManagerParams params);
    151 }