isnode-mod-jobs v0.1.0

ISNode Jobs Module

Introduction

This is just a module for the ISNode Framework. To learn how to use the framework, we strongly suggest obtaining a copy of the Hello World example.

The Jobs Module provides a mechanism for your application to add jobs to a processor which will later execute those jobs according to defined instructions. Each job comprises of a definition (identifier, name, type and any type-specific parameters), a function/method and an input object.

There are currently two supported mechanisms for processing jobs - (i) Queued; and (ii) Recurring.

1. Queued Jobs - These jobs are added to a single queue. The processor then picks up a pre-defined number of jobs from the queue every pre-defined period of time (these are parameters that are configurable within the application server configuration file - config.json). The jobs are processed in a FIFO manner. Ie; First In, First Out. Once the job has executed, then the processor has completed the task it was assigned for that job and the job is considered closed. Unless of course, within the job function there is a definite or conditional line that re-queues the job.

2. Recurring Jobs - These jobs are added to a processor with a defined "delay". They will be executed on a recurring basis with the length of time in between defined by the delay (or interval). These jobs will be executed indefinitely, unless they are removed from the processor or the application server terminates.

Below is an example of the Jobs module configuration object within the application server configuration file (config.json):

  "jobs": {
    "enabled": true,
    "queue": {
      "interval": 1000,
      "jobsPerInterval": 5
    }
  }

The "enabled" property defines whether the Jobs module is active. If it is disabled, then any attempts to add a new job or remove a job will fail, and no jobs will be executed.

The child object "queue" governs how the processor executes Queued Jobs. The "interval" defines the number of milliseconds between each attempt that the processor has to collect jobs from the queue to execute, and "jobsPerInterval" defines the number of jobs that are picked up from the queue with each iteration that passes.

Methods

jobs.add(definition, fn, input)

Synchronous Function. Adds a new job to the Processor.

Input Parameters:

1. definition - (Object) Definition Object
   1. id - (String) A (generally random) identifier for the job. Can be used to remove the job from the processor later.
   2. name - (String) A free text descriptive name for the job. For instance, if this is a job that clears expired user session tokens, the name might be "Clear Expired Session Tokens".
   3. type - (String) Either "queue" (for a Queued Job) or "recurring" (for a Recurring Job).
   4. delay - (Integer) Should only be defined for Recurring Jobs, and defines the length of the interval in milliseconds betweene each execution of the recurring job. If defined for a Queued Job, this parameter will generally be ignored.
2. fn - (Function) The function (or method) that is executed by the Processor for the job.
3. input - (Object) A single argument that is passed in to the function (fn) by the Processor. Is usually an object that may contain multiple attributes and sub-attributes.

Returns: This method returns "true" if the job was added successfully, otherwise it returns "false".

Example

	var jobOneId = isnode.module("utilities").randomString(20);
	var addJob = isnode.module("jobs").jobs.add;
	var clearSessionTokens = function(input){
		// Logic goes here to clear user session tokens, perhaps based on some data within the input object.
	}
	addJob({"name": "Clear Session Tokens", "id": jobOneId, "type": "recurring", "delay": 600000}, clearSessionTokens, input);

jobs.remove(id)

Synchronous Function. Removes a Job from the Processor

Input Parameters:

1. id - (String) Unique Job Identifier (from when it was added)

Returns: This method returns "true" if the job was found (based on id) and removed from the Processor. Returns "false" if the job could not be found.

Example

	// Following on from the add job example...
	var removeJob = isnode.module("jobs").jobs.remove;
	var result = removeJob(jobOneId);
	if(result) {
		console.log("Job Removed Successfully");
	} else {
		console.log("Could Not Find Job to Remove It");
	}