JOBs and the JSON-RPC Interface

The JOB and the JSON-RCP interface

A valid job class must inherits from TCustomJob class defined in DMSCustomJob unit. The following code defines a job which beeps at each execution.

unit Jobs.Beeper.Job;

interface

uses 
    DMSCommonsU, DMSCustomJob, DMSLoggingU;

type
    TBeepJob = class(TCustomJob)
    protected
        procedure DoExecute; override;
    end;

implementation

uses
    WinApi.Windows, System.SysUtils;

{ TBeepJob }

procedure TBeepJob.DoExecute;
begin
    Log.Info('Hello! I''m going to play something amazing!!', JobName);
    WinApi.Windows.Beep(440, 80);
end;

initialization

TBeepJob.ClassName;

end.

The package must requires dmsRT and LockBoxDR whose DCPs are provided, among others, in the <DMS_HOME>\SDK folder.

The JOB Class

The job class must be stateless because at each execution is created and destroyed. So no object state is preserved upon different execution. If the job needs persistence should relies on files, databases, web service or other persistence systems. Inside the job class, even the more simple, are available some facilities offered by the DMSContainer execution environment:

JobName: This read-only property return the name of the current job as defined in the jobsmanager.json file;

Log: This function return the singleton instance to access the specific logger for the job. It provides 4 logs level (DEBUG, INFO, WARNING, ERROR) and can create an arbitrary numbers of log files. Usually you want to write to the log file specific for the current job. In this (very common) case you should use JobName as the TAG of the log as shown in the previous code snippet.

Considering the internal mechanisms that DMSContainer uses, to be sure that the Delphi optimizing linker does not remove the class from the binary, you have to create a fictitious reference to the class as shown in the initialization section of the unit. A simple “no-op” like calling .ClassName is enough.

The class of the job (property jobclass) is not required. One of the following conbination is ok.

JobClass without RPCClass: This combination configures just a job without the RPC interface, there are no way to interact with the job remotely.

RPCClass without JobClass: This combination configures just an RPC endpoint, there isn’t a running job scheduled.

JobClass + RPCClass: This combination is the best from the both: a running job + an RPC interface to interact remotely with the job.

The JSON-RPC Class

One of the best features of DMSContainer is the automatic JSON-RPC object publishing. This powerful mechanisms is based on the similar feature available in DMVCFramework, the most popular, Delphi project on GitHub with hundred of active users and a lot of contributors all around the world.

Just defining a simple class like the following, is possible to define an RCP interfaced based on JSON-RPC 2.0 standard. This interface can be used to configure and manage in all the possible ways the JOB execution. The RCP interface is not required for a class job, but it is a really powerful extension. The built-in email job uses the RPC interface to allows the sender users to send emails, the admin users to manage other users and the messages queue, and the monitor users to check all the things are going on.