6.3.2. Client API details

6.3.2.1. The JqmClient interface

class JqmClient

This interface contains all the necessary methods to interact with JQM functions.

All methods have detailed Javadoc. The Javadoc is available on Maven Central (as are the binaries and the source code). This paragraph gives the methods prototypes as well as how they should be used. For details on exceptions thrown, etc. please refer to the javadoc.

6.3.2.1.1. New execution requests

JqmClient.enqueue(JobRequest executionRequest) → integer

The core method of the Job Queue Manager: it enqueues a new job execution request, as described in the object parameter. It returns the ID of the request. This ID will be kept throughout the life cycle of the request until it becomes the ID of the history item after the execution ends. This ID is reused in many other methods of the API.

It consumes a JobRequest item, which is a “form” object in which all ncessary parameters can be specified.

JqmClient.enqueue(String applicationName, String user) → integer

A simplified version of the method above.

JqmClient.enqueueFromHistory(Integer jobIdToCopy) → integer

This method copies an ended request. (this creates a new request - it has no impact whatsoever on the copied request)

6.3.2.1.2. Job request deleting

JqmClient.cancelJob(Integer id) → void

When called on a waiting execution request, removes it from the queue and moves it to history with CANCELLED status. This is the standard way of cancelling a request.

Synchronous method

JqmClient.deleteJob(int id) → void

This method should not usually be called. It completely removes a job execution request from the database. Please use cancelJob instead.

Synchronous method

JqmClient.killJob(int id) → void

Attempts to kill a running job instance. As Java thread are quite hard to kill, this may well have no effect.

Asynchronous method

6.3.2.1.3. Pausing and restarting jobs

JqmClient.pauseQueuedJob(int id) → void

When called on a job execution request it is ignored by engines and status forever in queue.

JqmClient.resumeJob(int id) → void

Will re insert a paused execution request into the queue. The place inside the queue may change from what it used to be before the pause.

JqmClient.restartCrachedJob(int id) → int

Will create an execution request from a crashed history element and remove all traces of the failed execution*.

6.3.2.1.4. Queries on Job instances

The API offers many methods to query either ended jobs or waiting/running ones. When there is a choice, please use the method which is the mst specific to your needs, as it may have optimizations not present in the more general ones.

JqmClient.getJob(int id) → JobInstance

Returns either a running or an ended job instance.

JqmClient.getJobs() → List<JobInstance>

Returns all job instances.

JqmClient.getActiveJobs() → List<JobInstance>

Lists all waiting or running job instances.

JqmClient.getUserActiveJobs(String username) → List<JobInstance>

Lists all waiting or running job instances which have the given “username” tag.

JqmClient.getJobs(Query q) → List<JobInstance>

please see Query API.

6.3.2.1.5. Quick access helpers

JqmClient.getJobMessages(int id) → List<String>

Retrieves all the messages created by a job instance (ended or not)

JqmClient.getJobProgress(int id) → int

Get the progress indication that may have been given by a job instance (running or done).

6.3.2.1.6. Files & logs retrieval

JqmClient.getJobDeliverables(int id) → List<Deliverable>

Return all metadata concerning the (potential) files created by the job instance: Excel files, PDFs, … These are the files explicitly referenced by the job instance through the JobManager.addDeliverable() method.

JqmClient.getDeliverableContent(Deliverable d) → InputStream

The actual content of the file described by the Deliverable object.

This method, in all implementations, uses a direct HTTP(S) connection to the engine that has run the job instance.

The responsibility to close the stream lies on the API user

JqmClient.getDeliverableContent(int deliverableId) → InputStream

Same a above.

JqmClient.getJobDeliverablesContent(int jobId) → List<InputStream>

Helper method. A loop on getDeliverableContent() for all files created by a single job instance.

JqmClient.getJobLogStdOut(int jobId) → InputStream

Returns the standard output flow of of an ended job instance.

This method, in all implementations, uses a direct HTTP(S) connection to the engine that has run the job instance.

The responsibility to close the returned stream lies on the API user

JqmClient.getJobLogStdErr(int jobId) → InputStream

Same as getJobLogStdOut() but for standard error flow.

6.3.2.1.7. Referential queries

These methods allow to retrieve all the referential data that may be needed to use the other methods: queue names, application names, etc.

JqmClient.getQueues() → List<Queue>
JqmClient.getJobDefinitions() → List<JobDef>
JqmClient.getJobDefinition(String applicationName) → JobDef

6.3.2.2. API objects

6.3.2.2.1. JobRequest

class JobRequest

Job execution request. It contains all the data needed to enqueue a request (the application name), as well as non-mandatory data. It is consumed by JqmClient.enqueue().

Basically, this is the form one has to fill in order to submit an execution request.

6.3.2.2.2. Queue

class Queue

All the metadata describing a queue. Read only element.

Please note there is another queue class that exists within JQM, inside the com.enioka.jqm.jpa packages. The JPA one is an internal JQM class and should not be confused with the API one, which is a stable interface.

6.3.2.2.3. JobDef

class JobDef

All the metadata describing a job definition. Read-only element.

Please note there is another class with this name that exists within JQM, inside the com.enioka.jqm.jpa packages. The JPA one is an internal JQM class and should not be confused with the API one, which is a stable interface.

6.3.2.3. Example

# Enqueue a job
int i = JqmClientFactory.getClient().enqueue("superbatchjob");

# Get its status
Status s = JqmClientFactory.getClient().getStatus(i);

# If still waiting, cancel it
if (s.equals(State.WAITING))
    JqmClientFactory.getClient().cancel(i);