org.sapia.ubik.net
Class Pool

java.lang.Object
  org.sapia.ubik.net.Pool

Direct Known Subclasses:

ByteArrayPool, ThreadPool

public abstract class Pool
extends java.lang.Object

Implements a basic object pool. Pooled objects must be returned to the pool once done with.

Author:

Yanick Duchesne

Copyright:

Copyright © 2002-2003 Sapia Open Source Software. All Rights Reserved.

License:

Read the license.txt file of the jar or visit the license page at the Sapia OSS web site

Field Summary

protected int	_currentCount
protected long	_lastUsageTime
protected int	_maxSize
protected java.util.List	_objects
static int	NO_MAX
static long	NO_TIME_OUT

Constructor Summary

Pool()

Pool(int maxSize)

Method Summary

java.lang.Object	acquire() Acquires an object from the pool; waits indefinitely that an object becomes available if the pool is empty and its maximum created object count has been reach.
java.lang.Object	acquire(long timeout) Acquires an object from this pool; if the pool is empty and its maximum created object count has been reach, this method waits for the specified timeout that an object becomes ready.
java.lang.Object	acquireCreate() This method attempts to acquire an object from this pool.
protected void	cleanup(java.lang.Object pooled) Inheriting classes should override this method to implement proper cleanup behavior for pooled objects.
protected abstract java.lang.Object	doNewObject() This template method should be overridden by inheriting classes to provide object instances that will be pooled.
void	fill(int toSize) Fills the pool up to the given size, or up to this pool's specified maximum size (if the latter was specified).
int	getCreatedCount() Returns the number of objects that have been created by this pool so far.
long	getLastUsageTime() Returns the time an object was last acquired from this pool.
protected java.lang.Object	onAcquire(java.lang.Object o)
protected void	onRelease(java.lang.Object o)
void	release(java.lang.Object obj) Releases the given object to the given pool.
void	shrinkTo(int size) Shrinks the pool to the specified size, or until the pool is empty.
int	size() Returns the number of objects currently in the pool.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_TIME_OUT

public static final long NO_TIME_OUT

See Also:

Constant Field Values

NO_MAX

public static final int NO_MAX

See Also:

Constant Field Values

_objects

protected java.util.List _objects

_maxSize

protected int _maxSize

_currentCount

protected int _currentCount

_lastUsageTime

protected long _lastUsageTime

Constructor Detail

Pool

public Pool()

Pool

public Pool(int maxSize)

Method Detail

acquire

public java.lang.Object acquire()
                         throws java.lang.InterruptedException,
                                java.lang.Exception

Acquires an object from the pool; waits indefinitely that an object becomes available if the pool is empty and its maximum created object count has been reach. If the maximum number of objects has not been reached, or if the pool has no such maximum defined, an object is internally created and immediately returned.

Returns:

an Object

Throws:

an - Exception if a problem occurs acquiring the object.

java.lang.InterruptedException

java.lang.Exception

acquire

public java.lang.Object acquire(long timeout)
                         throws java.lang.InterruptedException,
                                NoObjectAvailableException,
                                java.lang.Exception

Acquires an object from this pool; if the pool is empty and its maximum created object count has been reach, this method waits for the specified timeout that an object becomes ready. If the maximum number of objects has not been reached, or if the pool has no such maximum defined, an object is internally created and immediately returned.

Parameters:

timeout - a timeout to wait for until an object becomes available (in millis).

Returns:

an Object

Throws:

NoObjectAvailableException - if an object could not be acquired within the specified amount of time.

java.lang.Exception - if a problem occurs creating the object.

java.lang.InterruptedException

onAcquire

protected java.lang.Object onAcquire(java.lang.Object o)
                              throws java.lang.Exception

Throws:

java.lang.Exception

onRelease

protected void onRelease(java.lang.Object o)

release

public void release(java.lang.Object obj)

Releases the given object to the given pool.

Parameters:

obj - an Object to put back into the pool.

getLastUsageTime

public long getLastUsageTime()

Returns the time an object was last acquired from this pool.

getCreatedCount

public int getCreatedCount()

Returns the number of objects that have been created by this pool so far.

Returns:

the number of created object.

size

public int size()

Returns the number of objects currently in the pool.

Returns:

the number of objects currently in the pool.

shrinkTo

public void shrinkTo(int size)

Shrinks the pool to the specified size, or until the pool is empty. This method internally calls the cleanup() method for each object in the pool, so that the cleaned objects are properly disposed of.

Parameters:

size - the size to which to clean the pool.

See Also:

cleanup(Object)

fill

public void fill(int toSize)
          throws java.lang.Exception

Fills the pool up to the given size, or up to this pool's specified maximum size (if the latter was specified).

Parameters:

toSize - the size up to which this pool should be filled.

Throws:

java.lang.Exception

acquireCreate

public java.lang.Object acquireCreate()
                               throws java.lang.Exception

This method attempts to acquire an object from this pool. If this pool is currently empty and its maximum number of created objects has been reached, then null. If this pool is currently empty but no maximum number of created objects has been defined (at construction time), then a new object will be created and returned.

Returns:

an Object, or null if the pool is currently empty and has reached the maximum number of objects it can create.

Throws:

java.lang.Exception - if no object could be acquired/created.

doNewObject

protected abstract java.lang.Object doNewObject()
                                         throws java.lang.Exception

This template method should be overridden by inheriting classes to provide object instances that will be pooled.

Returns:

an Object to pool.

Throws:

java.lang.Exception - if an error occurs while creating the object to be returned.

cleanup

protected void cleanup(java.lang.Object pooled)

Inheriting classes should override this method to implement proper cleanup behavior for pooled objects. This method has an empty implementation by default.

See Also:

shrinkTo(int)