PoolService (Vibur Object Pool 8.0 API)

Type Parameters:

T - the type of objects held in this object pool

All Known Implementing Classes:

ConcurrentLinkedPool
```
public interface PoolService<T>
```
Defines the object pool operations. These operations include the take and restore methods. The restore method do not provide any validation whether the currently restored object has been taken before from the pool or whether the object is currently in taken state. Correct usage of these operations is established by programming convention in the application.
The object pool has support for shrinking (reduction) of the number of allocated on the pool objects.
The object pool may support an optional fairness parameter with regards to the waiting takers threads, as well as an optional Listener interface which methods will be called when a take or restore pool method executes.

Author:

Simeon Malchev

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`int`	`createdTotal()` Returns the total number of created objects which currently exist for this object pool.
`int`	`drainCreated()` Tries to remove (and destroy) as many created objects from this object pool as possible.
`int`	`initialSize()` Returns the `initialSize` of this object pool at construction time.
`boolean`	`isFair()` Returns the fairness setting of this object pool.
`boolean`	`isTerminated()` Returns the current terminated state of this object pool.
`Listener<T>`	`listener()` Returns the `Listener` interface instance associated with this object pool, if any.
`int`	`maxSize()` Returns the `maxSize` of this object pool.
`int`	`reduceCreated(int reduction, boolean ignoreInitialSize)` Tries to remove (and destroy) up to `reduction` objects from the object pool.
`int`	`remainingCapacity()` Returns the remaining capacity of this object pool, i.e.
`int`	`remainingCreated()` Returns the number of remaining created objects which currently exist in this object pool.
`void`	`restore(T object)` Restores (returns) an object to the object pool.
`void`	`restore(T object, boolean valid)` Restores (returns) an object to the object pool.
`T`	`take()` Takes an object from the object pool if there is such available.
`int`	`taken()` Returns the number of objects taken from this object pool.
`T`	`takeUninterruptibly()` Takes an object from the object pool if there is such available.
`void`	`terminate()` Terminates this object pool.
`T`	`tryTake()` Tries to take an object from the object pool if there is one which is immediately available.
`T`	`tryTake(long timeout, TimeUnit unit)` Takes an object from the object pool if there is such available.

- Method Detail
  - take
```
T take()
```
    Takes an object from the object pool if there is such available. This is a blocking call which waits indefinitely until an object becomes available. If the calling thread is interrupted while waiting this call will return null and the thread's interrupted status will be set to true.
    
    Returns:
    
    an object taken from the object pool or null if was interrupted while waiting
  - takeUninterruptibly
```
T takeUninterruptibly()
```
    Takes an object from the object pool if there is such available. This is a blocking call which waits indefinitely until an object becomes available.
    
    Returns:
    
    an object taken from the object pool
  - tryTake
```
T tryTake(long timeout,
          TimeUnit unit)
```
    Takes an object from the object pool if there is such available. This is a blocking call which waits up to the specified timeout for an object to become available. If the calling thread is interrupted while waiting this call will return null and the thread's interrupted status will be set to true.
    
    Parameters:
    
    timeout - the maximum time to wait for an object to become available in the object pool
    
    unit - the time unit of the timeout argument
    
    Returns:
    
    an object taken from the object pool or null if the specified timeout expires or if it was interrupted while waiting
  - tryTake
```
T tryTake()
```
    Tries to take an object from the object pool if there is one which is immediately available. Returns null if no object is available at the moment of the call.
    
    Returns:
    
    an object from the object pool or null if there is no object available in the object pool
  - restore
```
void restore(T object)
```
    Restores (returns) an object to the object pool. The object pool will not validate whether the currently restored object has been taken before that from this object pool or whether it is currently in taken state. Equivalent to calling restore(Object, true).
    
    Parameters:
    
    object - an object to be restored (returned) to this object pool
  - restore
```
void restore(T object,
             boolean valid)
```
    Restores (returns) an object to the object pool. The object pool will not validate whether the currently restored object has been taken before that from this object pool or whether it is currently in taken state.
    
    Parameters:
    
    object - an object to be restored (returned) to this object pool
    
    valid - if true the restored object is presumed to be in valid (healthy) state, otherwise it is treated as invalid
  - listener
```
Listener<T> listener()
```
    Returns the Listener interface instance associated with this object pool, if any.
    
    Returns:
    
    see above. null means no Listener is associated with this object pool.
  - taken
```
int taken()
```
    Returns the number of objects taken from this object pool. This number is less than or equal to the object pool createdTotal(). Typically used for testing and debugging purposes.
    
    Returns:
    
    the number of objects taken from this object pool
  - remainingCreated
```
int remainingCreated()
```
    Returns the number of remaining created objects which currently exist in this object pool. This number is less than or equal to the object pool remainingCapacity(). Typically used for testing and debugging purposes.
    
    Returns:
    
    the number of remaining created objects in this object pool
  - createdTotal
```
int createdTotal()
```
    Returns the total number of created objects which currently exist for this object pool. This number is equal to taken() + remainingCreated(). Typically used for testing and debugging purposes.
    
    Returns:
    
    the total number of created objects for this object pool
  - remainingCapacity
```
int remainingCapacity()
```
    Returns the remaining capacity of this object pool, i.e. the number of objects which could be taken from this object pool without blocking. It is not guaranteed that all these objects exist at the time of the call (i.e. are already created) in the object pool - some of them might be created on demand upon take requests. Also see remainingCreated(). Typically used for testing and debugging purposes.
    
    Returns:
    
    the object pool remaining capacity
  - initialSize
```
int initialSize()
```
    Returns the initialSize of this object pool at construction time. This parameter never changes.
    
    Returns:
    
    the object pool initialSize
  - maxSize
```
int maxSize()
```
    Returns the maxSize of this object pool. This parameter never changes.
    
    Returns:
    
    the object pool maxSize
  - reduceCreated
```
int reduceCreated(int reduction,
                  boolean ignoreInitialSize)
```
    Tries to remove (and destroy) up to reduction objects from the object pool. May bring the object pool createdTotal() to a number less then its initialSize().
    
    Parameters:
    
    reduction - the desired amount of objects to be removed
    
    ignoreInitialSize - specifies whether the createdTotal() may be reduced to less than initialSize()
    
    Returns:
    
    the actual amount of objects removed
  - drainCreated
```
int drainCreated()
```
    Tries to remove (and destroy) as many created objects from this object pool as possible. May bring the object pool createdTotal() to a number less then its initialSize().
    
    Returns:
    
    the actual amount of objects removed (and destroyed)
  - terminate
```
void terminate()
```
    Terminates this object pool. Once terminated the object pool cannot be more revived. All take and restore operations called on a terminated object pool should throw an exception or be ignored. Invocation has no additional effect if already terminated.
  - isTerminated
```
boolean isTerminated()
```
    Returns the current terminated state of this object pool.
    
    Returns:
    
    true if the object pool is terminated
  - isFair
```
boolean isFair()
```
    Returns the fairness setting of this object pool.
    
    Returns:
    
    true if the object pool is fair to waiting taker threads

Interface PoolService<T>

Method Summary

Method Detail

take

takeUninterruptibly

tryTake

tryTake

restore

restore

listener

taken

remainingCreated

createdTotal

remainingCapacity

initialSize

maxSize

reduceCreated

drainCreated

terminate

isTerminated

isFair