ResourcePool

ResourcePool is an abstract parent for classes implementing database connection pools and other similar limited size containers for scarce resources sequentially used by several Jobs.

The key feature here is to assure for each resource to be returned to the pool when it is no longer needed. This is achieved by listening to the finish message emitted in the Job.outcome ()'s finally block.

Another feature is connecting on demand only. Instead of eagerly locking a resource instance for every Job, ResourcePools generate light proxy objects that actually acquire resources only when an asynchronous method is called.

As a result, the business method called by the Job can operate on resources seen as properties of this (e. g. this.db for the main database connection) without any care about proper acquiring and releasing.

Constructor

...is absent here. This is a totally abstract class.

Properties

Name	Description
app	the Application instance this resource belongs to
name	the name with which this resource is registered in app.pools
wrapper	This property must be set by each descendant constructor to the wrapper Class which instances are injected into Jobs by this pool. Such class must implement the asynchronous method release ().
logger	winston Logger
shared	a Set of properties to be copied in each resource from this pool. For function valued properties, this works like using mixins. ['logger'] by default.

Methods

Application level

setResource (job, name)

This asynchronous method:

• calls acquire ();
• wraps it with wrapper class thus producing the resource instance;
• sets job [name] to the wrapped acquired resource;
• sets the resource's fields:
  • .job to the containing job;
  • .name to name;
• sets other properties with addSharedProperties (o);
• schedules job [name].release () to the job's finish;
• awaits for this.onAcquire (resource);

setProxy (job, resourceName)

This synchronous method sets job [resourceName] to a disposable proxy object mocking a wrapper instance and replacing itself with one upon the first use. It has:

• the job back reference;
• all properties set with addSharedProperties (o);
• all asynchronous methods with names found in wrapper's class.

Each of these methods:

• first, checks if job [resourceName] is (still) pointing to this same proxy object;
• if it is, calls await setResource (job, resourceName) thus acquiring a real resource;
• finally, forwards the arguments received to its eponymous method real implementation.

To override in descendants

acquire ()

This asynchronous method (not implemented in the abstract ancestor) must return a new instance of raw object (such as native driver's database connection) to be used as the single parameter for creating a new wrapper (raw) -- that eventually will be injected in a Job instance.

onAcquire (resource)

This asynchronous method is executed before any asynchronous requests to the resource freshly acquired in the context of a Job. Does nothing in the base implementation. Reserved for transaction auto start, setting variables etc.

Internal

addSharedProperties (o)

This synchronous method, used internally by setResource and setProxy, sets its 'o.pool' property to this and copies from this to o all properties which names are listed in this.shared and are yet absent from o.