001: /*
002: * $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 $
003: * $Revision: 480424 $
004: * $Date: 2006-11-29 06:56:49 +0100 (Wed, 29 Nov 2006) $
005: *
006: * ====================================================================
007: *
008: * Licensed to the Apache Software Foundation (ASF) under one or more
009: * contributor license agreements. See the NOTICE file distributed with
010: * this work for additional information regarding copyright ownership.
011: * The ASF licenses this file to You under the Apache License, Version 2.0
012: * (the "License"); you may not use this file except in compliance with
013: * the License. You may obtain a copy of the License at
014: *
015: * http://www.apache.org/licenses/LICENSE-2.0
016: *
017: * Unless required by applicable law or agreed to in writing, software
018: * distributed under the License is distributed on an "AS IS" BASIS,
019: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
020: * See the License for the specific language governing permissions and
021: * limitations under the License.
022: * ====================================================================
023: *
024: * This software consists of voluntary contributions made by many
025: * individuals on behalf of the Apache Software Foundation. For more
026: * information on the Apache Software Foundation, please see
027: * <http://www.apache.org/>.
028: *
029: */
030:
031: package org.apache.commons.httpclient;
032:
033: import org.apache.commons.httpclient.params.HttpConnectionManagerParams;
034:
035: /**
036: * An interface for classes that manage HttpConnections.
037: *
038: * @see org.apache.commons.httpclient.HttpConnection
039: * @see org.apache.commons.httpclient.HttpClient#HttpClient(HttpConnectionManager)
040: *
041: * @author Michael Becke
042: * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
043: * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
044: *
045: * @since 2.0
046: */
047: public interface HttpConnectionManager {
048:
049: /**
050: * Gets an HttpConnection for a given host configuration. If a connection is
051: * not available this method will block until one is.
052: *
053: * The connection manager should be registered with any HttpConnection that
054: * is created.
055: *
056: * @param hostConfiguration the host configuration to use to configure the
057: * connection
058: *
059: * @return an HttpConnection for the given configuration
060: *
061: * @see HttpConnection#setHttpConnectionManager(HttpConnectionManager)
062: */
063: HttpConnection getConnection(HostConfiguration hostConfiguration);
064:
065: /**
066: * Gets an HttpConnection for a given host configuration. If a connection is
067: * not available, this method will block for at most the specified number of
068: * milliseconds or until a connection becomes available.
069: *
070: * The connection manager should be registered with any HttpConnection that
071: * is created.
072: *
073: * @param hostConfiguration the host configuration to use to configure the
074: * connection
075: * @param timeout - the time (in milliseconds) to wait for a connection to
076: * become available, 0 to specify an infinite timeout
077: *
078: * @return an HttpConnection for the given configuraiton
079: *
080: * @throws HttpException if no connection becomes available before the
081: * timeout expires
082: *
083: * @see HttpConnection#setHttpConnectionManager(HttpConnectionManager)
084: *
085: * @deprecated Use #getConnectionWithTimeout(HostConfiguration, long)
086: */
087: HttpConnection getConnection(HostConfiguration hostConfiguration,
088: long timeout) throws HttpException;
089:
090: /**
091: * Gets an HttpConnection for a given host configuration. If a connection is
092: * not available, this method will block for at most the specified number of
093: * milliseconds or until a connection becomes available.
094: *
095: * The connection manager should be registered with any HttpConnection that
096: * is created.
097: *
098: * @param hostConfiguration the host configuration to use to configure the
099: * 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(
113: HostConfiguration hostConfiguration, long timeout)
114: throws ConnectionPoolTimeoutException;
115:
116: /**
117: * Releases the given HttpConnection for use by other requests.
118: *
119: * @param conn - The HttpConnection to make available.
120: */
121: void releaseConnection(HttpConnection conn);
122:
123: /**
124: * Closes connections that have been idle for at least the given amount of time. Only
125: * connections that are currently owned, not checked out, are subject to idle timeouts.
126: *
127: * @param idleTimeout the minimum idle time, in milliseconds, for connections to be closed
128: *
129: * @since 3.0
130: */
131: void closeIdleConnections(long idleTimeout);
132:
133: /**
134: * Returns {@link HttpConnectionManagerParams parameters} associated
135: * with this connection manager.
136: *
137: * @since 3.0
138: *
139: * @see HttpConnectionManagerParams
140: */
141: HttpConnectionManagerParams getParams();
142:
143: /**
144: * Assigns {@link HttpConnectionManagerParams parameters} for this
145: * connection manager.
146: *
147: * @since 3.0
148: *
149: * @see HttpConnectionManagerParams
150: */
151: void setParams(final HttpConnectionManagerParams params);
152: }
|