Job

Job is a class of single-use objects created for each execution of a business method taken from Application's modules according to its namingConventions.

(The name means job as in Queueing theory, not Oracle Database's periodic tasks)

This class implements the basic workflow:

• fetch the request (this.rq, a plain object);
• pick the suitable business method;
• execute it;
• release all resources possibly used.

Job is presumed to never be inherited from, but completely configured by the parent JobSource.

Properties

Private

Name	Description
[Symbol('todo')]	An Array of Promises to be awaited for during outcome ()
[Symbol('timestamps')]	An object of event-to-timestamp pairs plus the 'created' key with the constructor call timestamp
[Symbol('maxLatency')]	The maximum time between the constructor call and the end or error event, Infinity by default
[Symbol('minLatency')]	The minimum time between the constructor call and the finished event, 0 by default

Public

Name	Description
app	the Application instance this job belongs to
src	the JobSource this job comes from (if any)
parent	absent by default, by convention this property should be set to this by a job creating another job. For instance, the clone () method sets it.
id	the unique identifier of this job to use in logs etc. By default, is generated with crypto.randomUUID, but this can be overridden by setting id in generators object
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
user	By convention, this property must represent the system's actor performing the actual Job: for security checks, logging etc. Missing by default.
method	the business method to be executed, with [ModuleMap.MODULE] and [ModuleMap.METHOD_NAME] properties set
module	the module containing the business method to be executed: fetched from method [ModuleMap.MODULE]
result	the result returned by the business method and to be returned by outcome ()
error	the error thrown by the business method and to be thrown by outcome ()
logger	A winston Logger
tracker	the Tracker listening to the job's events and registering it with logger
[Tracker.LOGGING_DETAILS]	computed via src.getJobLoggingDetails
[Tracker.LOGGING_ID]	computed as id
[Tracker.LOGGING_PARENT]	computed as src
[Tracker.LOGGING_EVENT]	set from app.globals entry, adjusted with src.globals. See also Application's default globals

Constructor

Never to be called directly. Job instances must be produced only by calling the factory method createJob ().

Methods

Application level

fail (error)

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

outcome ()

This asynchronous method implements the job's lifecycle:

• calling app.getMethod (rq) to determine the method to execute;
• invoking callMethod with the business method 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 but the last one, outcome () calls broadcast () with the corresponding event name to process asynchronous event handlers before proceeding to the next stage. The finished event is just emitted, so all its handlers must be synchronous and neither of them can throw an error.

Each event handler defined as a (not arrow) function sees the Job instance as this 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, outcome () returns undefined instead of throwing anything.

resources (clazz)

This generator method iterates over all job's resources provided by pools of a given clazz.

waitFor (promise)

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

Internal

callMethod (func)

This asynchronous method invokes func as a method of this job and, normally, returns its result or rethrows the error. If [Symbol('maxLatency')] is finite and the time is out, throws an expirationError () instead.

expirationError ()

This synchronous method returns (not throws) an Error with the message "Timeout expired".

getTimeLeft (period)

This synchronous method returns period minus the number of milliseconds elapsed from the job creation.

setMaxLatency (ms)

This synchronous method sets the Symbol('maxLatency') private property to the non-negative integer ms. If set to a finite number, the end event cannot occur later than ms milliseconds since the job creation. Incase of such a delay, the expirationError result is thrown.

setMinLatency (ms)

This synchronous method sets the Symbol('minLatency') private property to the non-negative integer ms. If set, the finished event will be emitted not earlier than ms milliseconds since the job creation, even if the result is obtained and all resources are freed.

broadcast (event, payload)

This asynchronous method implements a single step of the job's lifecycle:

• writes the current timestamp into this [Symbol ('timestamps')] [event];
• initializes the TODO list;
• emits the event (which handlers should either be synchronous or call waitFor (promise));
• awaits for all promises from the TODO list.

Events

Name	When emitted	Purpose
start	Beginning of the lifecycle	Logging, adjusting rq content (e. g. fetching it from a stream)
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 after all end / error handlers are done working	Cleaning up, logging
finished	After asynchronous finish handlers, but not earlier than Symbol('minLatency') ms from job creation	Scheduling chained jobs. Only synchronous functions allowed