## org.apache.http.impl.conn.tsccm
Class ConnPoolByRoute

    java.lang.Object
      org.apache.http.impl.conn.tsccm.AbstractConnPool
          org.apache.http.impl.conn.tsccm.ConnPoolByRoute

All Implemented Interfaces:
  RefQueueHandler

    @ThreadSafe
    public class ConnPoolByRoute

extends AbstractConnPool

A connection pool that maintains connections by route. This class is derived from `MultiThreadedHttpConnectionManager` in HttpClient 3.x, see there for original authors. It implements the same algorithm for connection re-use and connection-per-host enforcement:

- connections are re-used only for the exact same route
- connection limits are enforced per route rather than per host

Note that access to the pool data structures is synchronized via the `poolLock` in the base class, not via `synchronized` methods.

Since:
  4.0

Field Summary
`protected ConnPerRoute` `connPerRoute` Connections per route lookup
`protected Queue<BasicPoolEntry>` `freeConnections` The list of free connections
`protected Set<BasicPoolEntry>` `leasedConnections` References to issued connections
`protected int` `maxTotalConnections`
`protected int` `numConnections`
`protected ClientConnectionOperator` `operator` Connection operator for this pool
`protected Map<HttpRoute,RouteSpecificPool>` `routeToPool` Map of route-specific pools
`protected boolean` `shutdown`
`protected Queue<WaitingThread>` `waitingThreads` The list of WaitingThreads waiting for a connection

Fields inherited from class org.apache.http.impl.conn.tsccm.AbstractConnPool
`idleConnHandler, isShutDown, issuedConnections, refQueue`

Constructor Summary
`ConnPoolByRoute(ClientConnectionOperator operator, ConnPerRoute connPerRoute, int maxTotalConnections)` Creates a new connection pool, managed by route.
`ConnPoolByRoute(ClientConnectionOperator operator, ConnPerRoute connPerRoute, int maxTotalConnections, long connTTL, TimeUnit connTTLTimeUnit)`
`ConnPoolByRoute(ClientConnectionOperator operator, HttpParams params)` Deprecated. use `ConnPoolByRoute(ClientConnectionOperator, ConnPerRoute, int)`

Method Summary
`void` `closeExpiredConnections()`
`void` `closeIdleConnections(long idletime, TimeUnit tunit)` Closes idle connections.
`protected BasicPoolEntry` `createEntry(RouteSpecificPool rospl, ClientConnectionOperator op)` Creates a new pool entry.
`protected Queue<BasicPoolEntry>` `createFreeConnQueue()` Creates the queue for `freeConnections`.
`protected Map<HttpRoute,RouteSpecificPool>` `createRouteToPoolMap()` Creates the map for `routeToPool`.
`protected Queue<WaitingThread>` `createWaitingThreadQueue()` Creates the queue for `waitingThreads`.
`void` `deleteClosedConnections()` Deletes all entries for closed connections.
`protected void` `deleteEntry(BasicPoolEntry entry)` Deletes a given pool entry.
`protected void` `deleteLeastUsedEntry()` Delete an old, free pool entry to make room for a new one.
`void` `freeEntry(BasicPoolEntry entry, boolean reusable, long validDuration, TimeUnit timeUnit)` Returns an entry into the pool.
`int` `getConnectionsInPool()`
`int` `getConnectionsInPool(HttpRoute route)`
`protected BasicPoolEntry` `getEntryBlocking(HttpRoute route, Object state, long timeout, TimeUnit tunit, WaitingThreadAborter aborter)` Obtains a pool entry with a connection within the given timeout.
`protected BasicPoolEntry` `getFreeEntry(RouteSpecificPool rospl, Object state)` If available, get a free pool entry for a route.
`protected Lock` `getLock()`
`int` `getMaxTotalConnections()` since 4.1
`protected RouteSpecificPool` `getRoutePool(HttpRoute route, boolean create)` Get a route-specific pool of available connections.
`protected void` `handleLostEntry(HttpRoute route)`
`protected RouteSpecificPool` `newRouteSpecificPool(HttpRoute route)` Creates a new route-specific pool.
`protected WaitingThread` `newWaitingThread(Condition cond, RouteSpecificPool rospl)` Creates a new waiting thread.
`protected void` `notifyWaitingThread(RouteSpecificPool rospl)` Notifies a waiting thread that a connection is available.
`PoolEntryRequest` `requestPoolEntry(HttpRoute route, Object state)` Returns a new `PoolEntryRequest`, from which a `BasicPoolEntry` can be obtained, or the request can be aborted.
`void` `setMaxTotalConnections(int max)` since 4.1
`void` `shutdown()` Shuts down this pool and all associated resources.

Methods inherited from class org.apache.http.impl.conn.tsccm.AbstractConnPool
`closeConnection, enableConnectionGC, getEntry, handleReference`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### operator

    protected final ClientConnectionOperator operator

  Connection operator for this pool

### connPerRoute

    protected final ConnPerRoute connPerRoute

  Connections per route lookup

### leasedConnections

    protected final Set<BasicPoolEntry> leasedConnections

  References to issued connections

### freeConnections

    protected final Queue<BasicPoolEntry> freeConnections

  The list of free connections

### waitingThreads

    protected final Queue<WaitingThread> waitingThreads

  The list of WaitingThreads waiting for a connection

### routeToPool

    protected final Map<HttpRoute,RouteSpecificPool> routeToPool

  Map of route-specific pools

### shutdown

    protected volatile boolean shutdown

### maxTotalConnections

    protected volatile int maxTotalConnections

### numConnections

    protected volatile int numConnections

Constructor Detail

### ConnPoolByRoute

    public ConnPoolByRoute(ClientConnectionOperator operator,
                           ConnPerRoute connPerRoute,
                           int maxTotalConnections)

  Creates a new connection pool, managed by route.

  Since:
    4.1

### ConnPoolByRoute

    public ConnPoolByRoute(ClientConnectionOperator operator,
                           ConnPerRoute connPerRoute,
                           int maxTotalConnections,
                           long connTTL,
                           TimeUnit connTTLTimeUnit)

Since:
  4.1

### ConnPoolByRoute

    @Deprecated
    public ConnPoolByRoute(ClientConnectionOperator operator,
                                      HttpParams params)

  Deprecated. use `ConnPoolByRoute(ClientConnectionOperator, ConnPerRoute, int)`

  Creates a new connection pool, managed by route.

Method Detail

### getLock

    protected Lock getLock()

### createFreeConnQueue

    protected Queue<BasicPoolEntry> createFreeConnQueue()

  Creates the queue for `freeConnections`. Called once by the constructor.

  Returns:
    a queue

### createWaitingThreadQueue

    protected Queue<WaitingThread> createWaitingThreadQueue()

  Creates the queue for `waitingThreads`. Called once by the constructor.

  Returns:
    a queue

### createRouteToPoolMap

    protected Map<HttpRoute,RouteSpecificPool> createRouteToPoolMap()

  Creates the map for `routeToPool`. Called once by the constructor.

  Returns:
    a map

### newRouteSpecificPool

    protected RouteSpecificPool newRouteSpecificPool(HttpRoute route)

  Creates a new route-specific pool. Called by `getRoutePool(org.apache.http.conn.routing.HttpRoute, boolean)` when necessary.

  Parameters:
    `route` - the route
  Returns:
    the new pool

### newWaitingThread

    protected WaitingThread newWaitingThread(Condition cond,
                                             RouteSpecificPool rospl)

  Creates a new waiting thread. Called by `getRoutePool(org.apache.http.conn.routing.HttpRoute, boolean)` when necessary.

  Parameters:
    `cond` - the condition to wait for
    `rospl` - the route specific pool, or `null`
  Returns:
    a waiting thread representation

### getRoutePool

    protected RouteSpecificPool getRoutePool(HttpRoute route,
                                             boolean create)

  Get a route-specific pool of available connections.

  Parameters:
    `route` - the route
    `create` - whether to create the pool if it doesn't exist
  Returns:
    the pool for the argument route, never `null` if `create` is `true`

### getConnectionsInPool

    public int getConnectionsInPool(HttpRoute route)

### getConnectionsInPool

    public int getConnectionsInPool()

### requestPoolEntry

    public PoolEntryRequest requestPoolEntry(HttpRoute route,
                                             Object state)

  Description copied from class: `AbstractConnPool`
  Returns a new `PoolEntryRequest`, from which a `BasicPoolEntry` can be obtained, or the request can be aborted.

  Specified by:
    `requestPoolEntry` in class `AbstractConnPool`

### getEntryBlocking

    protected BasicPoolEntry getEntryBlocking(HttpRoute route,
                                              Object state,
                                              long timeout,
                                              TimeUnit tunit,
                                              WaitingThreadAborter aborter)
                                       throws ConnectionPoolTimeoutException,
                                              InterruptedException

  Obtains a pool entry with a connection within the given timeout. If a `WaitingThread` is used to block, `WaitingThreadAborter.setWaitingThread(WaitingThread)` must be called before blocking, to allow the thread to be interrupted.

  Parameters:
    `route` - the route for which to get the connection
    `timeout` - the timeout, 0 or negative for no timeout
    `tunit` - the unit for the `timeout`, may be `null` only if there is no timeout
    `aborter` - an object which can abort a `WaitingThread`.
  Returns:
    pool entry holding a connection for the route
  Throws:
    `ConnectionPoolTimeoutException` - if the timeout expired
    `InterruptedException` - if the calling thread was interrupted

### freeEntry

    public void freeEntry(BasicPoolEntry entry,
                          boolean reusable,
                          long validDuration,
                          TimeUnit timeUnit)

  Description copied from class: `AbstractConnPool`
  Returns an entry into the pool. The connection of the entry is expected to be in a suitable state, either open and re-usable, or closed. The pool will not make any attempt to determine whether it can be re-used or not.

  Specified by:
    `freeEntry` in class `AbstractConnPool`
  Parameters:
    `entry` - the entry for the connection to release
    `reusable` - `true` if the entry is deemed reusable, `false` otherwise.
    `validDuration` - The duration that the entry should remain free and reusable.
    `timeUnit` - The unit of time the duration is measured in.

### getFreeEntry

    protected BasicPoolEntry getFreeEntry(RouteSpecificPool rospl,
                                          Object state)

  If available, get a free pool entry for a route.

  Parameters:
    `rospl` - the route-specific pool from which to get an entry
  Returns:
    an available pool entry for the given route, or `null` if none is available

### createEntry

    protected BasicPoolEntry createEntry(RouteSpecificPool rospl,
                                         ClientConnectionOperator op)

  Creates a new pool entry. This method assumes that the new connection will be handed out immediately.

  Parameters:
    `rospl` - the route-specific pool for which to create the entry
    `op` - the operator for creating a connection
  Returns:
    the new pool entry for a new connection

### deleteEntry

    protected void deleteEntry(BasicPoolEntry entry)

  Deletes a given pool entry. This closes the pooled connection and removes all references, so that it can be GCed.

  Note: Does not remove the entry from the freeConnections list. It is assumed that the caller has already handled this step.

  Parameters:
    `entry` - the pool entry for the connection to delete

### deleteLeastUsedEntry

    protected void deleteLeastUsedEntry()

  Delete an old, free pool entry to make room for a new one. Used to replace pool entries with ones for a different route.

### handleLostEntry

    protected void handleLostEntry(HttpRoute route)

  Specified by:
    `handleLostEntry` in class `AbstractConnPool`

### notifyWaitingThread

    protected void notifyWaitingThread(RouteSpecificPool rospl)

  Notifies a waiting thread that a connection is available. This will wake a thread waiting in the specific route pool, if there is one. Otherwise, a thread in the connection pool will be notified.

  Parameters:
    `rospl` - the pool in which to notify, or `null`

### deleteClosedConnections

    public void deleteClosedConnections()

  Description copied from class: `AbstractConnPool`
  Deletes all entries for closed connections.

  Specified by:
    `deleteClosedConnections` in class `AbstractConnPool`

### closeIdleConnections

    public void closeIdleConnections(long idletime,
                                     TimeUnit tunit)

  Closes idle connections.

  Overrides:
    `closeIdleConnections` in class `AbstractConnPool`
  Parameters:
    `idletime` - the time the connections should have been idle in order to be closed now
    `tunit` - the unit for the `idletime`

### closeExpiredConnections

    public void closeExpiredConnections()

  Overrides:
    `closeExpiredConnections` in class `AbstractConnPool`

### shutdown

    public void shutdown()

  Description copied from class: `AbstractConnPool`
  Shuts down this pool and all associated resources. Overriding methods MUST call the implementation here!

  Overrides:
    `shutdown` in class `AbstractConnPool`

### setMaxTotalConnections

    public void setMaxTotalConnections(int max)

  since 4.1

### getMaxTotalConnections

    public int getMaxTotalConnections()

  since 4.1

Copyright © 1999-2011 The Apache Software Foundation. All Rights Reserved.