The ResourcePool package consists of three major parts:

• ResourcePool
• LoadBalancer
• Command framework

The ResourcePool is used to manage a pool of persistent connections (or more generally "resources"). Every resource in a pool is exactly equivalent to the others since all of them are created through the same factory.

If you want to make a pool of different resources (e.g. connections to different databases) you have to use the ResourcePool::LoadBalancer.

The ResourcePool uses two other classes to operate:

ResourcePool::Factory

used to create resources

ResourcePool::Resource

used as wrapper to implement a unique interface to all resources

To create a ResourcePool you need a ResourcePool::Factory which is able to create the ResourcePool::Resource's you want to use. The ResourcePool will then use this factory to create ResourcePool::Resource objects as required.

The ResourcePool::Resource itself creates the finally interesting objects like DBI or Net::LDAP and provides a standard way to perform the common operations required by ResourcePool to work with this resource.

The ResourcePool::Factory and ResourcePool::Resource classes are base classes to inherit the specialized classes for your resource from. The classes to handle DBI and Net::LDAP resources are available as separate distributions on CPAN.

After creating a ResourcePool you can use the get() method to obtain a resource. The get() method will return the DBI or Net::LDAP object which can be used as usually. Afterwards you have to hand the resource back into the pool by calling the free() method.

Please have a look to the ResourcePool documentation for further details.

A ResourcePool::LoadBalancer can be used to configure a failover and/or loadbalancing behavior for ResourcePool users.

To construct a ResourcePool::LoadBalancer you need one or more ResourcePools. After construction a ResourcePool::LoadBalancer behaves like a ResourcePool, so you can call the get() method to obtain a resource and can use the Command strategy.

The ResourcePool::LoadBalancer can be configured to use a different ResourcePool every time you call the get() method. The ResourcePool::LoadBalancer can also detect a problem with a ResourcePool (e.g. because the related server is down) and will hide such problems from you.

There are currently three "Policies" which change the way the ResourcePool::LoadBalancer uses the configured resources:

• RoundRobin
• LeastUsage
• FailBack
• FailOver

The ResourcePool package includes a framework which can be used to execute commands like described in the GOF book "Design Patterns". You can use this pattern to avoid manual use of the get(), free() and fail() methods. The common code used to work with ResourcePool or ResourcePool::LoadBalancer (get resource, use it, return it to the pool) has been encapsulated into the execute() method.

The Command framework will it make easier to handle errors, and is capable of re-trying the complete work if an error occured. Using this pattern can help you to forget (nearly) about error handling since everything is handled in ResourcePool and ResourcePool::LoadBalancer. More details how to use this pattern can be found in the ResourcePool::Command::Execute documentation.

This pattern does also allow to use ResourcePool and ResourcePool::LoadBalancer for a complete new type of resources like SOAP::Lite. In that case you can use ResourcePool::LoadBalancer to spread load and handle failover for SOAP RPC calls. Have a look at ResourcePool::Command::SOAP::Lite::Call for details about this approach.

You should have the big picture of ResourcePool and ResourcePool::LoadBalancer now, time to go into the details at the ResourcePool and ResourcePool::LoadBalancer documentation. If you loose track of all these modules consult the ResourcePool::UML diagram.

The best entry point for the Command pattern is the ResourcePool::Command::Execute documentation. Have a look at the ResourcePool::Command::DBI::Execute documentation for a database related example or ResourcePool::Command::SOAP::Lite::Call documentation for a SOAP RPC example.

To learn more about how to implement your own resource extensions have a look to the ResourcePool::ExtensionGuide.