Using the vnd.sun.star.jobs: URL Schema

From Apache OpenOffice Wiki
Jump to: navigation, search


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 OpenOffice.org. It is registered for the URL schema "vnd.sun.star.job:*" which uses the following syntax:

 vnd.sun.star.job:{[event=<name>]}{,[alias=<name>]}{,[service=<name>]} 


Elements of a vnd.sun.star.job: URL
event=<name> string. Contains an event string, which can also be used as parameter of the interface method <idlml>com.sun.star.task.XJobExecutor:trigger</idlml>(). It corresponds to the node name of the set Events in the configuration package org.openoffice.Office.Jobs. Using the event parameter of a vnd.sun.star.job: URL will start all jobs that are registered for this event in the configuration.

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.

alias=<name> 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 vnd.sun.star.job: URL only starts the requested job.
service=<name> 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"
alias Job_1
UNO implementation name vnd.sun.star.jobs.Job_1
activation state Disabled for job execution (because its AdminTime is older than its UserTime)
own configuration contains one string item arg1 with the value "val1"
event registration job is registered for the event string "onFirstVisibleTask"

The second job can be described by these properties:

Properties of "Job_2"
alias Job_2
UNO implementation name vnd.sun.star.jobs.Job_2
activation state Enabled for job execution (because it uses default values for AdminTime and UserTime)
own configuration no own configuration items registered
event registration job is registered for the event string "onFirstVisibleTask"

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:

 vnd.sun.star.job:event=onFirstVisibleTask 

This URL starts Job_2 only, Job_1 is marked DISABLED, since its AdminTime stamp is older than its UserTime stamp.

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 JobConfig because 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.

 vnd.sun.star.job:alias=Job_1 

This starts 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.job:service=vnd.sun.star.jobs.Job_3 

A 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).
Personal tools
In other languages