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) → integerA 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¶
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) → InputStreamSame 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.
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¶
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);