xmlBlaster 2.2.0 client 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, org.xmlBlaster.test.classtest.TestPoolManager

Field Summary
static java.lang.String GENERATE_RANDOM
          Use this constant with the reserve() method, the PoolManager generates a random, unique in universe session ID
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.
 void destroy()
          Cleanup everything.
 void erase(java.lang.String instanceId)
          Explicitly remove a resource.
protected  void finalize()
          Cleanup.
 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.
 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

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
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()

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

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

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

destroy

public void destroy()
Cleanup everything.


xmlBlaster 2.2.0 client API

Copyright © 1999-2014 The xmlBlaster.org contributers.