Using the vnd.sun.star.jobs: URL Schema
This section describes the necessary steps to execute a job by issuing a command URL at the dispatch framework. Based upon the protocol handler mechanism, a specialized URL schema has been implemented in Apache OpenOffice. It is registered for the URL schema "
vnd.sun.star.job:*" which uses the following syntax:
|Elements of a vnd.sun.star.job: URL|
|| string. Contains an event string, which can also be used as parameter of the interface method trigger(). It corresponds to the node name of the set |
Note: Disabled jobs, that is jobs with a user time stamp that is newer than the administrator time stamp, are not triggered by event URLs.
|| string. Contains an alias name of a configured job. This name is not used by the job execution API. It is a node name of the set Jobs in the configuration package org.openoffice.Office.Jobs. Using the alias part of a |
||string. Contains the UNO implementation name of a configured or unconfigured com.sun.star.task.Job or com.sun.star.task.AsyncJob service. It is not necessary that such jobs are registered in the configuration, provided that they work without configuration data or implements necessary configuration on their own.|
It is possible to combine elements so as to start several jobs at once with a single URL. For instance, you could dispatch a URL vnd.sun.star.job:event=e1,alias=a1,event=e2,…. However, URLs that start several jobs at once should be used carefully, since there is no check for double or concurrent requests. If a service is designed asynchronously, it will be run concurrently with another, synchronous job. If both services work at the same area, there might be race conditions and they must synchronize their work. The generic job execution mechanism does not provide this functionality.
The following configuration file for the configuration package org.openoffice.Office.Jobs shows two jobs, which are registered for different events:
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE oor:component-data SYSTEM "../../../../component-update.dtd"> <oor:component-data oor:name="Jobs" oor:package="org.openoffice.Office" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <node oor:name="Jobs"> <node oor:name="Job_1" oor:op="replace"> <prop oor:name="Service"> <value>vnd.sun.star.jobs.Job_1</value> </prop> <node oor:name="Arguments"> <prop oor:name="arg_1" oor:type="xs:string" oor:op="replace"> <value>val_1</value> </prop> </node> </node> <node oor:name="Job_2" oor:op="replace"> <prop oor:name="Service"> <value>vnd.sun.star.jobs.Job_2</value> </prop> <node oor:name="Arguments"/> </node> </node> <node oor:name="Events"> <node oor:name="onFirstVisibleTask" oor:op="fuse"> <node oor:name="JobList"> <node oor:name="Job_1" oor:op="replace"> <prop oor:name="AdminTime"> <value>01.01.2003/00:00:00</value> </prop> <prop oor:name="UserTime"> <value>01.01.2003/00:00:01</value> </prop> </node> <node oor:name="Job_2" oor:op="replace"/> </node> </node> </node> </oor:component-data>
The first job can be described by the following properties:
|Properties of "Job_1"|
||Disabled for job execution (because its AdminTime is older than its UserTime)|
|| contains one |
|| job is registered for the event string "|
The second job can be described by these properties:
|Properties of "Job_2"|
||Enabled for job execution (because it uses default values for AdminTime and UserTime)|
||no own configuration items registered|
|| job is registered for the event string "|
The following demonstrates use cases for all possible vnd.sun.star.job: URLs. Not all possible scenarios are shown here. The job dispatch can be used in different ways and the combination of jobs can produce different results:
This URL starts
Job_1 is marked
DISABLED, since its
AdminTime stamp is older than its
The job is initialized with environment information through the Environment sub list, as shown in section Initialization. Optional dispatch arguments are passed in
DynamicData, and generic configuration data, including the event string, is received in
Config. However, it is not initialized with configuration data of its own in
Job_2 is not configured with such information. On the other hand,
Job_2 may return data after finishing its work, which will be written back to the configuration.
Furthermore, the job instance can expect that the
Frame property from the
Environment sub list points to the frame in which the dispatch request is to be executed.
Job_1 only. It is initialized with an environment, and optionally initialized with dispatch arguments, generic configuration data, and configuration data of its own. However, the event name is not set here because this job was triggered directly, not using an event name.
vnd.sun.star.jobs.Job_3 is not registered in the job configuration package. However, if this implementation was registered with the global service manager, and if it provided the com.sun.star.task.XJob or com.sun.star.task.XAsyncJob interfaces, it would be executed by this URL. If both interfaces are present, the synchronous version is preferred.
The given UNO implementation name
vnd.sun.star.jobs.Job_3 is used directly for creation at the UNO service manager. In addition, this job instance is only initialized with an environment and possibly with optional dispatch arguments - there is no configuration data for the job to use.
|Content on this page is licensed under the Public Documentation License (PDL).|