xmlBlaster 2.1.0 API

org.xmlBlaster.util.pool
Class PoolManager

java.lang.Object
  extended by org.xmlBlaster.util.pool.PoolManager

public final class PoolManager
extends java.lang.Object

A little framework to handle a pool of limited resources.

You can use this pool as a base class handling of your limited resources like a 'JDBC connection pool' or a 'thread pool'.

The important attributes of a resource are gathered in the ResourceWrapper class.

You can easily handle bigger number of resources with good performance.

To find out how to use it see the TestPool example in the main() method of this class.

    State chart of resource handling:

      +<------- reserve() if(numIdle==0) ---------------------+
      |                                                       |
      |     +<- reserve() --+        +<-preReserve() *-+      |
      |     | if(numIdle>0) |        |                 |      |
      |     |               |        |                 |      |
    #########               ##########                 ##########
   #         #             #          #               #          #
   #  busy   #             #  idle    #               #  undef   #
   #         #             #          #               #          #
    #########               ##########                 ##########
      |  |  |               | |  | | |                 | |  |  |
      |  |  |   Explicit    | |  | | |   Explicit      | |  |  |
      |  |  +-- release() ->+ |  | | +-- erase() ----->+ |  |  |
      |  |                    |  | |                     |  |  |
      |  +busyToIdleTimeout()>+  | +idleToEraseTimeout()>+  |  |
      |                          |                          |  |
      |                          +-- erase on max cycles *->+  |
      |                                                        |
      +--------- busyToEraseTimeout() since creation *-------->+

 
There are three states:

Note that state transitions marked with '*' are not yet implemented. If you need one of them, code it and contribute it please.

You can choose which states you wish for your resource and how timeouts are used to handle state transitions.

For example if you want to pool user login sessions and want to do an auto logout after 60 minutes, you would use the busyToIdleTimeout and set it to 60*60*1000.
If a user is active you can refresh the session with busyRefresh().
Often you want to use your own generated sessionId as the primary key for this resource, you can pass it as the instanceId argument to reserve(sessionId).
(See example [2] in this main() method)

If you want to pool JDBC connections, reserve() a connection before you do your query and release() it immediately again. If you want to close connections after peak usage, you could set a idleToEraseTimeout, to erase your JDBC connection after some time not used (reducing the current pool size).
Note that in this example the connections are anonymous (all are logged in to the database with the same user name), it is not important which you receive.
(See example [1] in this main() method)

For an implementation example see TestPoolManager.java

This code is derived from the org.jutils.pool package.

Author:
"Marcel Ruff"
See Also:
ResourceWrapper, TestPoolManager

Field Summary
private  java.util.Hashtable busy
          Holds busy resources
private  long busyToIdleTimeout
          Default maximum busy time of a resource, on timeout it changes state from 'busy' to 'idle'
private  I_PoolManager callback
          The callback into the using application, which needs to implement the interface I_PoolManager
private  long counter
          Unique counter to generate IDs
static java.lang.String GENERATE_RANDOM
          Use this constant with the reserve() method, the PoolManager generates a random, unique in universe session ID
private  java.util.Vector idle
          Holds free resources
private  long idleToEraseTimeout
          Default maximum idle span of a resource, on timeout it changes state from 'idle' to 'undef' (it is deleted)
private  int maxInstances
          Default maximum pool size (number of resources)
private  java.lang.String ME
          Nice, unique name for logging output
private  java.lang.Object meetingPoint
           
private  java.lang.String poolName
          A nice name for the generated id
private  Timeout transitionTimer
          Triggers transitions
static java.lang.String USE_HASH_CODE
          Use this constant with the reserve() method, the PoolManager uses the hashCode() of your object
static java.lang.String USE_OBJECT_REF
          Use this constant with the reserve() method, the PoolManager uses the toString() of your object, if no toString() exists the object reference is used, e.g.
 
Constructor Summary
PoolManager(java.lang.String poolName, I_PoolManager callback, int maxInstances, long busyToIdleTimeout, long idleToEraseTimeout)
          Create a new pool instance with the desired behavior.
 
Method Summary
 void busyRefresh(java.lang.String instanceId)
          Restart countdown for resource life cycle.
private  java.lang.String createId(java.lang.String instanceId)
          Generate a unique resource ID
 void destroy()
          Cleanup everything.
private  void erase(ResourceWrapper rw)
          Remove a resource.
 void erase(java.lang.String instanceId)
          Explicitly remove a resource.
protected  void finalize()
          Cleanup.
private  ResourceWrapper findBusySilent(java.lang.String instanceId)
          Find a resource in busy list.
private  ResourceWrapper findIdleSilent(java.lang.String instanceId)
          Find a resource in idle list.
private  ResourceWrapper findLow(java.lang.String instanceId)
          Find a resource in busy list.
 int getNumBusy()
          Number of resources in the 'busy' list.
 int getNumIdle()
          Number of resources in the 'idle' list.
 java.lang.String getState()
          Dump the current state of this pool.
 Timeout getTransistionTimer()
           
 boolean isBusy(java.lang.String instanceId)
          Test if the resource is busy.
 void release(java.lang.String instanceId)
          Release a resource explicitly from 'busy' into the 'idle' pool.
 ResourceWrapper reserve()
          Get a new resource.
 ResourceWrapper reserve(long localBusyToIdleTimeout, long localIdleToEraseTimeout, java.lang.String instanceId)
          Get a new resource.
 ResourceWrapper reserve(java.lang.String instanceId)
          Get a new resource.
private  void setBusyToIdleTimeout(long busyToIdleTimeout)
          On timeout, the resource changes state from 'busy' to 'idle'.
private  void setIdleToEraseTimeout(long idleToEraseTimeout)
          Set the max.
private  void setMaxInstances(int maxInstances)
          Set the maximum pool size.
private  void swap(ResourceWrapper rw, boolean toBusy)
          Idle - busy swapper.
(package private)  void timeoutBusyToIdle(ResourceWrapper rw)
          Recycle busy resource after timeout.
(package private)  void timeoutIdleToErase(ResourceWrapper rw)
          Erase an idle resource after timeout.
 java.lang.String toXml()
          Dump state of this object into a XML ASCII string.
 java.lang.String toXml(java.lang.String extraOffset)
          Dump state of this object into a XML ASCII string.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ME

private java.lang.String ME
Nice, unique name for logging output


poolName

private java.lang.String poolName
A nice name for the generated id


callback

private I_PoolManager callback
The callback into the using application, which needs to implement the interface I_PoolManager


busy

private java.util.Hashtable busy
Holds busy resources


idle

private java.util.Vector idle
Holds free resources


maxInstances

private int maxInstances
Default maximum pool size (number of resources)


busyToIdleTimeout

private long busyToIdleTimeout
Default maximum busy time of a resource, on timeout it changes state from 'busy' to 'idle'


idleToEraseTimeout

private long idleToEraseTimeout
Default maximum idle span of a resource, on timeout it changes state from 'idle' to 'undef' (it is deleted)


counter

private long counter
Unique counter to generate IDs


USE_HASH_CODE

public static final java.lang.String USE_HASH_CODE
Use this constant with the reserve() method, the PoolManager uses the hashCode() of your object

See Also:
Constant Field Values

USE_OBJECT_REF

public static final java.lang.String USE_OBJECT_REF
Use this constant with the reserve() method, the PoolManager uses the toString() of your object, if no toString() exists the object reference is used, e.g. "oracle.jdbc.driver.OracleConnection@443226"

See Also:
Constant Field Values

GENERATE_RANDOM

public static final java.lang.String GENERATE_RANDOM
Use this constant with the reserve() method, the PoolManager generates a random, unique in universe session ID

See Also:
Constant Field Values

transitionTimer

private Timeout transitionTimer
Triggers transitions


meetingPoint

private final java.lang.Object meetingPoint
Constructor Detail

PoolManager

public PoolManager(java.lang.String poolName,
                   I_PoolManager callback,
                   int maxInstances,
                   long busyToIdleTimeout,
                   long idleToEraseTimeout)
Create a new pool instance with the desired behavior.

Implementation:
There are two list in this class

If you ask for a new resource, this will move into the busy list
Is a resource released or a specified timeout occurred, it is moved into the idle list.

Parameters:
poolName - A nice name for this pool manager instance.
callback - The interface 'I_PoolManager' callback
maxInstances - Max. number of resources in this pool.
busyToIdleTimeout - Max. busy time of this resource in milli seconds
On timeout it changes state from 'busy' to 'idle'.
You can overwrite this value for each resource instance
0 switches it off
You get called back through I_PoolManager.busyToIdle() on timeout allowing you to code some specific handling.
idleToEraseTimeout - Max. idle time span of this resource in milli seconds
On timeout it changes state from 'idle' to 'undef' (it is deleted).
You can overwrite this value for each resource instance
0 switches it off
You get called back through I_PoolManager.toErased() on timeout allowing you to code some specific handling.
Method Detail

getTransistionTimer

public Timeout getTransistionTimer()

setMaxInstances

private void setMaxInstances(int maxInstances)
Set the maximum pool size.

Parameters:
maxInstances - How many resources are allowed

setBusyToIdleTimeout

private void setBusyToIdleTimeout(long busyToIdleTimeout)
On timeout, the resource changes state from 'busy' to 'idle'.

Parameters:
busyToIdleTimeout - Max. busy time of this resource in milli seconds
On timeout it changes state from 'busy' to 'idle'.
You can overwrite this value for each resource instance
0 switches it off

setIdleToEraseTimeout

private void setIdleToEraseTimeout(long idleToEraseTimeout)
Set the max. life span of the resources.

Parameters:
idleToEraseTimeout - Max. idle time of this resource in milli seconds
You can overwrite this value for each resource instance
0 switches it off

reserve

public ResourceWrapper reserve()
                        throws XmlBlasterException
Get a new resource.

The life span is set to the default value of the pool.

The instance Id is random and unique generated.

Throws:
XmlBlasterException - Error with random generator

reserve

public ResourceWrapper reserve(java.lang.String instanceId)
                        throws XmlBlasterException
Get a new resource.

The life span is set to the default value of the pool.

Parameters:
instanceId - See description in other reserve() method.
Throws:
XmlBlasterException - Error with random generator

reserve

public ResourceWrapper reserve(long localBusyToIdleTimeout,
                               long localIdleToEraseTimeout,
                               java.lang.String instanceId)
                        throws XmlBlasterException
Get a new resource.

Parameters:
localBusyToIdleTimeout - Max. busy time of this resource in milli seconds, only for this current resource
Overwrite locally the default
0 switches busy timeout off
localIdleToEraseTimeout - Max. idle time of this resource in milli seconds, only for this current resource
Overwrite locally the default
0 switches idle timeout off
instanceId - If given and string length > 1, the delivered ID is used: If in busy list found, this is returned, else a new is created.
USE_HASH_CODE - The PoolManager generates a simple one (hashCode())
USE_OBJECT_REF - The object reference is used
GENERATE_RANDOM - The PoolManager generates a random, unique in universe session ID
Returns:
rw The resource handle (always != null)
Throws:
XmlBlasterException - Error with random generator

release

public void release(java.lang.String instanceId)
             throws XmlBlasterException
Release a resource explicitly from 'busy' into the 'idle' pool.

Parameters:
instanceId - The unique resource ID
Throws:
XmlBlasterException

createId

private java.lang.String createId(java.lang.String instanceId)
                           throws XmlBlasterException
Generate a unique resource ID

Returns:
unique ID or null
Throws:
XmlBlasterException - random generator

swap

private void swap(ResourceWrapper rw,
                  boolean toBusy)
Idle - busy swapper.


findBusySilent

private ResourceWrapper findBusySilent(java.lang.String instanceId)
Find a resource in busy list.

Parameters:
instanceId - The unique resource ID
Returns:
The handle containing the resource.

findIdleSilent

private ResourceWrapper findIdleSilent(java.lang.String instanceId)
Find a resource in idle list.

Note that this is currently a linear search (not high performing).

Parameters:
instanceId - The unique resource ID
Returns:
The handle containing the resource.

findLow

private ResourceWrapper findLow(java.lang.String instanceId)
                         throws XmlBlasterException
Find a resource in busy list.

Parameters:
instanceId - The unique resource ID
Returns:
Handle containing resource
Throws:
XmlBlasterException - "ResourceNotFound"

isBusy

public boolean isBusy(java.lang.String instanceId)
Test if the resource is busy.

Parameters:
instanceId - The unique resource ID
Returns:
true - is in 'busy' state
false - is in 'idle' state or unknown

busyRefresh

public void busyRefresh(java.lang.String instanceId)
                 throws XmlBlasterException
Restart countdown for resource life cycle.

Rewind the timeout for 'busy' to 'idle' transition.

Parameters:
instanceId - The unique resource ID
Throws:
XmlBlasterException - ResourceNotFound

getNumBusy

public int getNumBusy()
Number of resources in the 'busy' list.

Returns:
Number of 'busy' resources

getNumIdle

public int getNumIdle()
Number of resources in the 'idle' list.

Returns:
Number of 'idle' resources

finalize

protected void finalize()
                 throws java.lang.Throwable
Cleanup.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable

getState

public java.lang.String getState()
Dump the current state of this pool.


toXml

public final java.lang.String toXml()
Dump state of this object into a XML ASCII string.

Returns:
internal state of this PoolManager as a XML ASCII string

toXml

public final java.lang.String toXml(java.lang.String extraOffset)
Dump state of this object into a XML ASCII string.

Parameters:
extraOffset - indenting of tags for nice output
Returns:
internal state of this PoolManager as a XML ASCII string

timeoutBusyToIdle

void timeoutBusyToIdle(ResourceWrapper rw)
Recycle busy resource after timeout.

This method is a callback from ResourceWrapper


timeoutIdleToErase

void timeoutIdleToErase(ResourceWrapper rw)
Erase an idle resource after timeout.

This method is a callback from ResourceWrapper


erase

public void erase(java.lang.String instanceId)
Explicitly remove a resource.

It is erased if it is found in the idle list or even when it is busy.

Parameters:
instanceId - The unique resource ID

erase

private void erase(ResourceWrapper rw)
Remove a resource.

Remove it from the 'idle' or the 'busy' list.

Parameters:
rw - The resource wrapper object

destroy

public void destroy()
Cleanup everything.


xmlBlaster 2.1.0 API

Copyright © 1999-2011 The xmlBlaster.org contributers.