Home | History | Annotate | Download | only in conn 
      1 /*
      2  * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/conn/ClientConnectionManager.java $
      3  * $Revision: 671717 $
      4  * $Date: 2008-06-25 21:03:24 -0700 (Wed, 25 Jun 2008) $
      5  *
      6  * ====================================================================
      7  * Licensed to the Apache Software Foundation (ASF) under one
      8  * or more contributor license agreements.  See the NOTICE file
      9  * distributed with this work for additional information
     10  * regarding copyright ownership.  The ASF licenses this file
     11  * to you under the Apache License, Version 2.0 (the
     12  * "License"); you may not use this file except in compliance
     13  * with 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,
     18  * software distributed under the License is distributed on an
     19  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     20  * KIND, either express or implied.  See the License for the
     21  * specific language governing permissions and limitations
     22  * under the License.
     23  * ====================================================================
     24  *
     25  * This software consists of voluntary contributions made by many
     26  * individuals on behalf of the Apache Software Foundation.  For more
     27  * information on the Apache Software Foundation, please see
     28  * <http://www.apache.org/>.
     29  *
     30  */
     31 
     32 package org.apache.http.conn;
     33 
     34 
     35 import java.util.concurrent.TimeUnit;
     36 
     37 import org.apache.http.conn.routing.HttpRoute;
     38 import org.apache.http.conn.scheme.SchemeRegistry;
     39 
     40 /**
     41  * Management interface for {@link ManagedClientConnection client connections}.
     42  *
     43  * @author Michael Becke
     44  * @author <a href="mailto:mbowler (at) GargoyleSoftware.com">Mike Bowler</a>
     45  * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
     46  * @author <a href="mailto:rolandw at apache.org">Roland Weber</a>
     47  *
     48  *
     49  * <!-- empty lines to avoid svn diff problems -->
     50  * @version   $Revision: 671717 $
     51  *
     52  * @since 4.0
     53  */
     54 public interface ClientConnectionManager {
     55 
     56     /**
     57      * Obtains the scheme registry used by this manager.
     58      *
     59      * @return  the scheme registry, never <code>null</code>
     60      */
     61     SchemeRegistry getSchemeRegistry()
     62         ;
     63 
     64 
     65     /**
     66      * Returns a new {@link ClientConnectionRequest}, from which a
     67      * {@link ManagedClientConnection} can be obtained or the request can be
     68      * aborted.
     69      */
     70     ClientConnectionRequest requestConnection(HttpRoute route, Object state)
     71         ;
     72 
     73 
     74     /**
     75      * Releases a connection for use by others.
     76      * You may optionally specify how long the connection is valid
     77      * to be reused.  Values <= 0 are considered to be valid forever.
     78      * If the connection is not marked as reusable, the connection will
     79      * not be reused regardless of the valid duration.
     80      *
     81      * If the connection has been released before,
     82      * the call will be ignored.
     83      *
     84      * @param conn      the connection to release
     85      * @param validDuration the duration of time this connection is valid for reuse
     86      * @param timeUnit the unit of time validDuration is measured in
     87      *
     88      * @see #closeExpiredConnections()
     89      */
     90     void releaseConnection(ManagedClientConnection conn, long validDuration, TimeUnit timeUnit)
     91         ;
     92 
     93 
     94     /**
     95      * Closes idle connections in the pool.
     96      * Open connections in the pool that have not been used for the
     97      * timespan given by the argument will be closed.
     98      * Currently allocated connections are not subject to this method.
     99      * Times will be checked with milliseconds precision
    100      *
    101      * All expired connections will also be closed.
    102      *
    103      * @param idletime  the idle time of connections to be closed
    104      * @param tunit     the unit for the <code>idletime</code>
    105      *
    106      * @see #closeExpiredConnections()
    107      */
    108     void closeIdleConnections(long idletime, TimeUnit tunit)
    109         ;
    110 
    111     /**
    112      * Closes all expired connections in the pool.
    113      * Open connections in the pool that have not been used for
    114      * the timespan defined when the connection was released will be closed.
    115      * Currently allocated connections are not subject to this method.
    116      * Times will be checked with milliseconds precision.
    117      */
    118     void closeExpiredConnections();
    119 
    120     /**
    121      * Shuts down this connection manager and releases allocated resources.
    122      * This includes closing all connections, whether they are currently
    123      * used or not.
    124      */
    125     void shutdown()
    126         ;
    127 
    128 
    129 } // interface ClientConnectionManager
    130