com.tivoli.pd.jutil
Class ContextPool<C extends PDContext>

java.lang.Object
  com.tivoli.pd.jutil.ContextPool<C>

public class ContextPool<C extends PDContext>
extends java.lang.Object

This class provides a generic pooling management behavior to manages a pool of shared contexts.

Applications are encouraged to obtain the PDContext from the pool to avoid the overhead of creating a new PDContext every time when one is needed.

Initializing the ContextPool

The ContextPool must be initialized with an appropriate PooledContextBuilder. A default PooledContextBuilder is provided as DefaultPooledPDContextBuilder. However applications are free to provide their own implementation if they wish to customize the pooled context's behavior.

Refer to PooledContextBuilder and DefaultPooledContextBuilder javadoc for more information on how to implement a custom PooledContextBuilder.

For example, to create a PooledContextBuilder for a PDContext pool.

    URL url = new URL("file:///path/to/configFile");
    PooledContextBuilder<PDContext>builder = new DefaultPooledPDContextBuilder(url);
 

The PooledContextBuilder is responsible for creating the actual context instances within the pool. Setup a PooledContextBuilder by passing it as a parameter in ContextPool constructor. Client must call the initailize() method to setup the pool before it can be used.

    ContextPool<PDContext> pool = new ContextPool<PDContext>(builder);
    pool.initalize();
 

Retrieving a PDContext from the Pool

To obtain a PDContext, the client should call one of the two getContext() methods to remove a shared PDContext from the pool. The client can then proceed to the use the PDContext as normal.

    PDContext context = pool.getContext();
 

Returning a PDContext back into the pool

The context should be release back into the pool by calling the PDContext.close() method when it is not needed. Failure to do so will result in ContextPool exhaustion.

    context.close();
 

Closing the ContextPool

And finally, when the pool is no longer needed, its resources can be released by calling the ContextPool.close(). The pool cannot be called on after that.

    pool.close();
 

See Also:

PooledContextBuilder, DefaultPooledPDContextBuilder

Constructor Summary

ContextPool(PooledContextBuilder<C> builder)
Creates a ContextPool with a default pool size of 10 PDContext.

ContextPool(PooledContextBuilder<C> builder, int size)
Creates a ContextPool with the given pool size.

Method Summary

void	close() Close the context pool.
C	getContext() Gets a PDContext from the pool.
C	getContext(int waitTime) Gets a PDContext from the pool.
void	initialize() Initializes the pool.
void	reclaim(C context) Reclaims a shared context back into the pool.

Methods inherited from class java.lang.Object

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

Constructor Detail

ContextPool

public ContextPool(PooledContextBuilder<C> builder)

Creates a ContextPool with a default pool size of 10 PDContext.

Parameters:

builder - PooledContextBuilder to create the context to be managed by this context pool.

ContextPool

public ContextPool(PooledContextBuilder<C> builder,
                   int size)
            throws java.lang.IllegalArgumentException

Creates a ContextPool with the given pool size.

Parameters:

builder - PooledContextBuilder to create the context

size - the PDContext pool size.

Throws:

java.lang.IllegalArgumentException - If pool size is less then 1.

Method Detail

initialize

public void initialize()
                throws PDException

Initializes the pool.

This method must be called before obtaining any PDContext from the pool.

Throws:

PDException - when an error occurred.

getContext

public C getContext()
                               throws PDException

Gets a PDContext from the pool.

If there is no available context in the pool, this method will wait indefinitely until one is made available.

Throws:

PDException - when an error occurred.

getContext

public C getContext(int waitTime)
                               throws PDException

Gets a PDContext from the pool.

If the pool does not have any available context, this method will wait for the specified time. After which if there is still no context available, it will throw a NoPDContextAvailableException.

Parameters:

waitTime - time (in milliseconds) to wait for a context. A wait time of zero or less will wait indefinately.

Throws:

NoPDContextAvailableException - when wait time exceeded.

PDException - an error has occurred.

reclaim

public void reclaim(C context)

Reclaims a shared context back into the pool.

NOTE: This method is for the consumption of context pool implementation. Client code using a pooled context should call the PDContext.close() method to return the pooled context to the pool instead of this method.

Parameters:

context - the context to be returned into the pool.

close

public void close()

Close the context pool.

All resources held by the contexts within the pool will be released. The pool should not be used after calling this method.