Source for org.apache.commons.httpclient.HttpConnectionManager

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