Configuration

Although jobs that are called through a vnd.sun.star.jobs: URL by their implementation name do not require it, a job usually has configuration data. The configuration package org.openoffice.Office.Jobs contains all necessary information:

<?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE oor:component-schema SYSTEM "../../../../component-schema.dtd">
  <oor:component-schema xmlns:oor="http://openoffice.org/2001/registry" 
                        xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                        oor:name="Jobs" 
                        oor:package="org.openoffice.Office" 
                        xml:lang="en-US">
      <templates>
          <group oor:name="Job">
              <prop oor:name="Service" oor:type="xs:string"/>
              <group oor:name="Arguments" oor:extensible="true"/>
          </group>
          <group oor:name="TimeStamp">
              <prop oor:name="AdminTime" oor:type="xs:string"/>
              <prop oor:name="UserTime" oor:type="xs:string"/>
          </group>
          <group oor:name="Event">
              <set oor:name="JobList" oor:node-type="TimeStamp"/>
          </group>
      </templates>
      <component>
          <set oor:name="Jobs" oor:node-type="Job"/>
          <set oor:name="Events" oor:node-type="Event"/>
      </component>
  </oor:component-schema>

The Job template contains all properties that describe a job component. Instances of this template are located inside the configuration set Jobs.

Properties of the Job template
`Alias`	string. This property is declared as the name of the corresponding set node inside the configuration set `Jobs`. It must be a unique name, which represents the structured information of a job. In the example .xcu file below its value is "`SyncJob`". In the job execution arguments this property is passed as `Config - Alias`
`Service`	string. Represents the UNO implementation name of the job component. In the job execution arguments this property is passed as `Config - Service`
`Arguments`	set of any entries. This list can be filled with any values and represents the private set of configuration data for this job. In the job execution arguments this property is passed as `JobConfig`

The job property Alias was created to provide you with more flexibility for a developing components. You can use the same UNO implementation, but register it with different Aliases. At runtime the job instance will be initialized with its own configuration data and can detect which representation is used.

You cannot use the generic UNO service names com.sun.star.task.Job or com.sun.star.task.AsyncJob for the Service job property, because the job executor cannot identify the correct job implementation. To avoid ambiguities, it is necessary to use the UNO implementation name of the component.

Every job instance can be bound to multiple events. An event indicates a special office state, which can be detected at runtime (for example, OnFirstVisibleTask ), and which can be triggered by a call to the job executor when the first document window is displayed.

Properties of the Event template

EventName

string. This property is declared as the name of the corresponding set node inside the configuration set Events. It must be a unique name, which describes a functional state. In the example .xcu file below its value is "onFirstVisibleTask".

Section List of Supported Events summarizes the events currently triggered by the office. In addition, developers can use arbitrary event strings with the vnd.sun.star.jobs: URL or in calls to trigger() at the com.sun.star.task.JobExecutor service.

JobList set of TimeStamp entries. This set contains a list of all Alias names of jobs that are bound to this event. Every job registration can be combined with time stamp values. Please refer to the description of the template TimeStamp below for details

As an optional feature, every job registration that is bound to an event can be enabled or disabled by two time stamp values. In a shared installation of OpenOffice.org, an administrator can use the AdminTime value to reactivate jobs for every newly started user office instance; regardless of earlier executions of these jobs. That can be useful, for example, for updating user installations if new functions have been added to the shared installation.

Properties of the TimeStamp template
`AdminTime`	string. This value must be formatted according to the ISO 8601. It contains the time stamp, which can only be adjusted by an administrator, to reactivate this job.
`UserTime`	string. This value must be formatted according to the ISO 8601. It contains the time, when this job was finished successfully last time upon the configured event.

Using this time stamp feature can sometimes be complicated. For example, assume that there is a job that was installed using the Extension Manager. The job is enabled for a registered event by default, but after the first execution it is disabled. By default, both values (AdminTime and UserTime) do not exist for a configured event. A Jobs.xcu fragment, as part of the extension, must also not contain the AdminTime and UserTime entries. Because both values are not there, no check can be made and the job is enabled. A job can be deactivated by the global job executor once it has finished its work successfully (depending on the Deactivate return value). In that case, the UserTime entry is generated and set to the current time. An administrator can set a newer and valid AdminTime value in order to reactivate the job again, or the user can remove his UserTime entry manually from the configuration file of the user installation.

The following Jobs.xcu file shows an example job configuration:

<?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="SyncJob" oor:op="replace">
              <prop oor:name="Service">
                  <value>com.sun.star.comp.framework.java.services.SyncJob</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>
      <node oor:name="Events">
          <node oor:name="onFirstVisibleTask" oor:op="fuse">
              <node oor:name="JobList">
                  <node oor:name="SyncJob" oor:op="replace"/>
              </node>
          </node>
      </node>
  </oor:component-data>

This example job has the following characteristics:

Its alias name is "SyncJob"
The UNO implementation name of the component is com.sun.star.comp.framework.java.services.SyncJob.
The job has its own set of configuration data with one item. It is a string, its name is arg_1 and its value is "val_1".
The job is bound to the global event onFirstVisibleTask, which is triggered when the first document window of a new OpenOffice.org instance is displayed. The next execution of this job is guaranteed, because there are no time stamp values present.

When specifying the event to which the job is bound (onFirstVisibleTask in the above example), it is important to use oor:op="fuse", so that multiple Jobs.xcu particles merge losslessly. but note that oor:op="fuse" is only available since OpenOffice.org 2.0.3, and that a Jobs.xcu file that uses it cannot be used with older versions of OpenOffice.org. With older versions of OpenOffice.org, it was common to use oor:op="replace" instead of oor:op="fuse", which potentially caused event bindings to get lost when multiple Jobs.xcu particles were merged.

A job is not executed when it has deactivated itself and is called afterwards by a vnd.sun.star.jobs:event=... command URL. This can be confusing to users, especially with add-ons, since it would seem that the customized UI items do not function.

Content on this page is licensed under the Public Documentation License (PDL).

Configuration

Views

Personal tools

Navigation

Search

Tools

In other languages