The new method is called to create a new factory.
Usually this method just stores the parameters somewhere and will use it later create_resource is called.
This method is used to actually create a resource according to the parameters given to the new method.
You must override this method in order to do something useful.
<B>Returns:B> a reference to a ResourcePool::Resource object
This method is used for reporting purposes. It doesnt take any arguments and just returns some human readable string to identify the factory (and the related resource).
You are not required to override this method, but its highly recommended for reporting purposes.
<B>Returns:B> A human readable string describing the factory
This method is used to create the key which separates instances of a class which should not considered being the same when using ResourcePool::Singleton.
Remember, the key difference between the ResourcePool::Singleton and other singleton implementations is that ResourcePool::Singleton can take parameters into account. This means that, for example, two instances of the same class (e.g. DBI) with different parameters (e.g. database names) are NOT considered to be the same!
This function must return a string which holds all information which separates such instances from each other. The default implementation does just return a stringified representation of the $self reference (using Data::Dumper). This is usually what you want. But if you configure some parameters to your factory which should not separate the factories (e.g. a transaction/request id which is used by the info() method for reporting purposes), you must override this method to take only the required information into account.
Performance might be another aspect why to override this method. This method is called every time you construct a ResourcePool even if the new method of ResourcePool does return a previously constructed reference. Keep in mind: the default implementation is generic but slow.
This function is used by ResourcePool on construction. Even if you develop you own factory, you do usually not get in touch with this method. But anyway, documentation is provided for better understanding:
Used to implement the singleton behavior of the factory. The new method of this class does NOT return a singleton reference! Instead, you have to call this method to obtain a singleton reference of this factory. This is required to allow factories to not require all parameters which have to be taken into account for the singleton separation on construction.
The ResourcePool::Factory::Net::LDAP makes use of this feature. So you have the possibility to configure your factory using some more function calls (like the bind() method of ResourcePool::Factory::Net::LDAP and afterwards call the singleton() method to get a singleton reference which takes also the bind() parameters into consideration.
Normally you do not get in touch with this method, if you derive your home-build factories from this class, everything will work as expected. This way of handling the singleton behaviour of factories was introduces with version 0.9909 of ResourcePool. The change is transparent to your previously developed factories if you derive your factory from this class.