Job Functions

This module provides functions for registering new query jobs and orchestrating existing jobs. Jobs can be queries, commands, operations performed by a database client, and HTTP requests.

Conventions

All functions in this module are assigned to the http://basex.org/modules/job namespace, which is statically bound to the job prefix. Errors will be bound to the same prefix.

Services

A job can be registered as service by supplying the service option to job:eval:

(: register job as service; will be run every day at 1 am :)
job:eval(
  'db:drop("tmp")',
  options := { 'id':'cleanup', 'start':'01:00:00', 'interval':'P1D', 'service': true() }
),

(: list registered services :)
job:services(),
(: result: <job base-uri="..." id="cleanup" interval="P1D" start="01:00:00">db:drop("tmp")</job> :)

(: unregister job :)
job:remove('cleanup', { 'service': true() })

• All job services will be scheduled for evaluation when the BaseX server or BaseX HTTP server is started.
• If a job service is outdated (e.g. because a supplied end time has been exceeded), it will be removed from the jobs file at startup time.
• The job definitions are stored in a jobs.xml file in the database directory. It can also be edited manually.

Executing Jobs

There are cases in which a client does not, or cannot, wait until a request is fully processed. The client may be a browser, which sends an HTTP request to the server to start another time-consuming query job. The functions in this section allow you to register new query jobs and access existing ones. Jobs can be executed immediately (i.e., as soon as a free slot is available) or scheduled for repeated execution. Each registered job gets a job ID, and the ID can be used to retrieve a query result, stop a job, or wait for its termination.

job:eval

job:eval(
  $query     as xs:anyAtomicType,
  $bindings  as map(*)?           := {},
  $options   as map(*)?           := {}
) as xs:string

job:eval("1 + 3", (), { 'cache': true() })

job:eval(
  "import module namespace mail='mail'; mail:send('Happy birthday!')",
  (),
  { 'start': '2018-09-01T06:00:00' }
)

declare
  %rest:POST("{$query}")
  %rest:path('/start-scheduling')
function local:start($query) {
  job:eval($query, (), { 'start': '02:00:00', 'interval': 'P1D' })
};

declare
  %rest:path('/stop-scheduling/{$id}')
function local:stop($id) {
  job:remove($id)
};

job:eval("prof:sleep(1500)", (), { 'interval': 'PT1S', 'end': 'PT10S' })

job:eval(xs:anyURI('cleanup.xq'))

job:eval(static-base-uri(), {}, { 'start': 'PT5S' })

job:result

job:result(
  $id       as xs:string,
  $options  as map(*)?    := {}
) as item()*

declare
  %rest:path('/result/{$id}')
function local:result($id) {
  job:result($id)
};

let $query := job:eval('(1 to 10000000)[. = 1]', options := { 'cache': true() })
return (
  job:wait($query),
  job:result($query)
)

job:remove

job:remove(
  $id       as xs:string,
  $options  as map(*)?    := {}
) as empty-sequence()

job:list()[. != job:current()] ! job:remove(.)

job:remove(job:current())

job:wait

job:wait(
  $id  as xs:string
) as empty-sequence()

Listing Jobs

job:current

job:current() as xs:string

job:list

job:list() as xs:string*

job:list()

job:list-details

job:list-details(
  $id  as xs:string  := ()
) as element(job)*

job:bindings

job:bindings(
  $id  as xs:string
) as map(*)

job:finished

job:finished(
  $id  as xs:string
) as xs:boolean

job:services

job:services() as element(job)*

Errors

Changelog

• Added: job:bindings
• Updated: Renamed from Jobs Module to Job Module. The namespace URI has been updated as well.
• Updated: job:remove renamed from jobs:stop.
• Updated: job:result: options argument added.

• Updated: job:result: return empty sequence if no result is cached.

• Updated: job:eval: integers added as valid start and end times.

• Updated: job:eval: option added for writing log entries.
• Updated: job:list-details: interval added.

• Deleted: job:invoke (merged with job:eval)

• Updated: job:list-details: registration time added.

• Added: job:invoke, Services

• Updated: job:eval: id option added.

• Added: New module added.