Difference between revisions of "Documentation/DevGuide/WritingUNO/Jobs/Configuration"

Revision as of 08:00, 12 July 2018

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.

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.

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.

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.