Job

Job is a class of single-use objects created for each execution of a business method (from Application's ModuleMap).

(Its name means "jobs" as in Queueing theory, not Oracle Database's periodic tasks)

This class implements the basic workflow used in all doix based server applications. It's presumed to never be inherited from, only extended by setting event handlers.

Job instances are mostly passive objects: other pieces of code get and set their properties, subscribe to events and so on. Only two methods are exposed to be called from elsewhere.

Properties

Name	Description
app	the Application instance this job belongs to
rq	request parameters, an an Object. Think PHP's $_REQUEST generalization. Setting rq is the way of passing parameters to the business method to be called in the context of this job.
module	business method containing module: the value fetched from Application's ModuleMap by MethodSelector's getModuleName () result.
result	the result returned by the business method and to be returned by toComplete ()
error	the error thrown by the business method and to be thrown by toComplete ()

Methods

toComplete ()

This asynchronous method implements the job's lifecycle:

• setting module to the value fetched from Application's ModuleMap by MethodSelector's getModuleName () result;
• calling its method named getMethodName () (the business method) with the job itself visible as this and then:
  • if it throws something, set it to error and rethrow;
  • set the value returned to result and return it otherwise.

At each step, toComplete () emits the corresponding event. In node.js, listeners must be synchronous and cannot throw anything, but here, the can call waitFor () to register any Promises — in that case, toComplete () will wait for all of them to be settled before proceeding to the next stage.

Each event handler receives the Job instance as the 1st parameter and can modify its content. The execution order is fixed, so for each event subsequent handlers see the job state modified by previous ones. In particular, if the business method throws something, the error property may be rewritten by error handlers and if finally it gets undefined, toComplete () returns undefined instead of throwing anything.

waitFor (promise)

This synchronous method registers the given promise to be awaited for before toComplete () to proceeding to the next stage. It is to be called from event handlers.

fail (error)

This is a wrapper around waitFor that postpones a Promise immediately rejecting with the given error.

Events

Name	When emitted	Purpose
start	Beginning of the lifecycle	Logging, adjusting rq content (e. g. fetching it from a stream)
module	The module is set, but the method is not yet chosen	Security checks, resource injection
method	The method name is known (passed as a parameter to the handler)	Security checks, resource injection
end	The result is obtained and set as a property	Rewriting result, reporting it
error	The error is caught and set as a property	Rewriting error, reporting it
finish	Guaranteed to be emitted the last	Cleaning up, logging