1. /*
  2. * $Header: /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: 1.24 $
  4. * $Date: 2004/07/05 22:46:58 $
  5. *
  6. * ====================================================================
  7. *
  8. * Copyright 1999-2004 The Apache Software Foundation
  9. *
  10. * Licensed under the Apache License, Version 2.0 (the "License");
  11. * you may not use this file except in compliance with the License.
  12. * You may obtain a copy of the License at
  13. *
  14. * http://www.apache.org/licenses/LICENSE-2.0
  15. *
  16. * Unless required by applicable law or agreed to in writing, software
  17. * distributed under the License is distributed on an "AS IS" BASIS,
  18. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19. * See the License for the specific language governing permissions and
  20. * limitations under the License.
  21. * ====================================================================
  22. *
  23. * This software consists of voluntary contributions made by many
  24. * individuals on behalf of the Apache Software Foundation. For more
  25. * information on the Apache Software Foundation, please see
  26. * <http://www.apache.org/>.
  27. *
  28. */
  29. package org.apache.commons.httpclient;
  30. import org.apache.commons.httpclient.params.HttpConnectionManagerParams;
  31. /**
  32. * An interface for classes that manage HttpConnections.
  33. *
  34. * @see org.apache.commons.httpclient.HttpConnection
  35. * @see org.apache.commons.httpclient.HttpClient#HttpClient(HttpConnectionManager)
  36. *
  37. * @author Michael Becke
  38. * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
  39. * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
  40. *
  41. * @since 2.0
  42. */
  43. public interface HttpConnectionManager {
  44. /**
  45. * Gets an HttpConnection for a given host configuration. If a connection is
  46. * not available this method will block until one is.
  47. *
  48. * The connection manager should be registered with any HttpConnection that
  49. * is created.
  50. *
  51. * @param hostConfiguration the host configuration to use to configure the
  52. * connection
  53. *
  54. * @return an HttpConnection for the given configuration
  55. *
  56. * @see HttpConnection#setHttpConnectionManager(HttpConnectionManager)
  57. */
  58. HttpConnection getConnection(HostConfiguration hostConfiguration);
  59. /**
  60. * Gets an HttpConnection for a given host configuration. If a connection is
  61. * not available, this method will block for at most the specified number of
  62. * milliseconds or until a connection becomes available.
  63. *
  64. * The connection manager should be registered with any HttpConnection that
  65. * is created.
  66. *
  67. * @param hostConfiguration the host configuration to use to configure the
  68. * connection
  69. * @param timeout - the time (in milliseconds) to wait for a connection to
  70. * become available, 0 to specify an infinite timeout
  71. *
  72. * @return an HttpConnection for the given configuraiton
  73. *
  74. * @throws HttpException if no connection becomes available before the
  75. * timeout expires
  76. *
  77. * @see HttpConnection#setHttpConnectionManager(HttpConnectionManager)
  78. *
  79. * @deprecated Use #getConnectionWithTimeout(HostConfiguration, long)
  80. */
  81. HttpConnection getConnection(HostConfiguration hostConfiguration, long timeout)
  82. throws HttpException;
  83. /**
  84. * Gets an HttpConnection for a given host configuration. If a connection is
  85. * not available, this method will block for at most the specified number of
  86. * milliseconds or until a connection becomes available.
  87. *
  88. * The connection manager should be registered with any HttpConnection that
  89. * is created.
  90. *
  91. * @param hostConfiguration the host configuration to use to configure the
  92. * connection
  93. * @param timeout - the time (in milliseconds) to wait for a connection to
  94. * become available, 0 to specify an infinite timeout
  95. *
  96. * @return an HttpConnection for the given configuraiton
  97. *
  98. * @throws ConnectionPoolTimeoutException if no connection becomes available before the
  99. * timeout expires
  100. *
  101. * @see HttpConnection#setHttpConnectionManager(HttpConnectionManager)
  102. *
  103. * @since 3.0
  104. */
  105. HttpConnection getConnectionWithTimeout(HostConfiguration hostConfiguration, long timeout)
  106. throws ConnectionPoolTimeoutException;
  107. /**
  108. * Releases the given HttpConnection for use by other requests.
  109. *
  110. * @param conn - The HttpConnection to make available.
  111. */
  112. void releaseConnection(HttpConnection conn);
  113. /**
  114. * Closes connections that have been idle for at least the given amount of time. Only
  115. * connections that are currently owned, not checked out, are subject to idle timeouts.
  116. *
  117. * @param idleTimeout the minimum idle time, in milliseconds, for connections to be closed
  118. *
  119. * @since 3.0
  120. */
  121. void closeIdleConnections(long idleTimeout);
  122. /**
  123. * Returns {@link HttpConnectionManagerParams parameters} associated
  124. * with this connection manager.
  125. *
  126. * @since 3.0
  127. *
  128. * @see HttpConnectionManagerParams
  129. */
  130. HttpConnectionManagerParams getParams();
  131. /**
  132. * Assigns {@link HttpConnectionManagerParams parameters} for this
  133. * connection manager.
  134. *
  135. * @since 3.0
  136. *
  137. * @see HttpConnectionManagerParams
  138. */
  139. void setParams(final HttpConnectionManagerParams params);
  140. }