4.4. Engine API

The engine API is an interface offered optionally to running job instances allowing them to interact with JQM.

It allows them to do some operations only available to running jobs (such as specifying that a file they have just created should be made available to end users) as well as a subset of operations coming directly from theFull client API. The latter is mostly for convenience - that way, clients do not have to import, set parameters and initialize the full API - everything is readied by the engine (and very quickly because the engine reuses some of its own already-initialized objects).

Using the API is easy: one just has to declare, inside the job main class, a Field ofJobManagertype. It can be static. Then, the JQM engine will inject an instance inside that field at runtime and it can be used without further ado.

class

JobManager

This interface gives access to JQM engine variables and methods. It allows to retrieve the characteristics of the currently running job instances, as well as creating new instances and other useful methods. It should never be instantiated but injected by the JQM engine. For the injection to take place, the payload main class should have a field of type JobManager (directly or through inheritance, as well as public or private).

Use is very straightforward:

public class App implements Runnable
{
    private JobManager jm;

    @Override
    public void run()
    {
        // JM can be used immediately.
        jm.enqueue("otherjob", "me");
    }
}

4.4.1. Current job metadata

For the description of these items, please see the job instance description. Please note that these are methods, not fields - this is only because Java does not allow to specify fields inside an interface.

JobManager.parentId() → int

JobManager.jobApplicationId() → int

JobManager.jobInstanceID() → int

JobManager.canBeRestarted() → boolean

JobManager.applicationName() → String

JobManager.sessionID() → String

JobManager.application() → String

JobManager.module() → String

JobManager.keyword1() → String

JobManager.keyword2() → String

JobManager.keyword3() → String

JobManager.userName() → String

JobManager.parameters() → Map<String, String>

4.4.2. Enqueue & retrieve jobs

JobManager.enqueue(String applicationName,String user,String mail,String sessionId,String application,String module,String keyword1,String keyword2, String keyword3,Map<String,String> parameters)→ int

Enqueues a new execution request. This is asynchronous - it returns as soon as the request was posted.

Equivalent toJqmClient.enqueue(), but where the parameters are given directly instead of using aJobRequestinstance. This is a little ugly but necessary due to the underlying class loader proxying magic.

JobManager.enqueueSync(String applicationName,String user,String mail,String sessionId,String application,String module, String keyword1, String keyword2,String keyword3,Map<String,String> parameters)→ int

Callsenqueue()and waits for the end of the execution.

JobManager.waitChild(int jobInstanceId)→ void

JobManager.waitChildren()→ void

JobManager.hasEnded(int jobInstanceId)→ Boolean

JobManager.hasSucceeded(int jobInstanceId)→ Boolean

JobManager.hasFailed(int jobInstanceId)→ Boolean

4.4.3. Communications

JobManager.sendMsg(String message) → void

Messages are strings that can be retrieved during run by other applications, so that interactive human users may have a measure of a job instance progress. (typical messages highlight the job’s internal steps)

JobManager.sendProgress(Integer progress) → void

Progress is an integer that can be retrieved during run by other applications, so that interactive human users may have a measure of a job instance progress. (typically used for percent of completion)

JobManager.addDeliverable(String path,String fileLabel)→ int

When a file is created and should be retrievable from the client API, the file must be referenced with this method.

The file is moved by this method! Only call when you don’t need the file any more.

It is strongly advised to usegetWorkDir()to get a directory where to first create your files.

4.4.4. Misc.

JobManager.defaultConnect()→ String

The default connection JNDI alias. To retrieve a default connection, simply use:

((DataSource)InitialContext.doLookup(jm.defaultConnect)).getConnection();

SeeJDBCfor more details.

Preferably use directlyJobManager.getDefaultConnection()to directly retrieve a connection.

JobManager.getDefaultConnection()→ Connection

A connection as described by the default JNDI alias. SeeJDBCfor more details.

JobManager.getWorkDir() → File

If temp files are necessary, use this directory. The directory already exists. It is used by a single instance. It is purged at the end of the run.

JobManager.yield() → void

This simply notifies the engine that it can briefly take over the thread, mostly to check if the thread should commit suicide. SeeGoing to the cullingfor more details.