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

Revision as of 07:46, 4 June 2008

A job in OpenOffice.org is a UNO component that can be executed by the job execution environment upon an event. It can read and write its own set of configuration data in the configuration branch org.openoffice.Office.Jobs, and it can be activated and deactivated from a certain point in time using special time stamps. It may be started with or without an environment, and it is protected against termination and lifetime issues.

The event that starts a job can be triggered by:

• any code in OpenOffice.org that detects a defined state at runtime and passes an event string to the service com.sun.star.task.JobExecutor through its interface method com.sun.star.task.XJobExecutor:trigger(). The job executor looks in the configuration of OpenOffice.org if there are any jobs registered for this event and executes them.

• the global document event broadcaster

• the dispatch framework, which provides for a vnd.star.sun.job: URL schema to start jobs using a command URL. This URL schema can execute jobs in three different ways: it can issue an event for job components that are configured to wait for it, it can call a component by an alias that has been given to the component in the configuration or it can execute a job component directly by its implementation name.

If you call trigger() at the job executor or employ the global event broadcaster, the office needs a valid set of configuration data for every job you want to run. The third approach, to use a vnd.star.sun.job: command URL, works with or without prior configuration.

The illustration below shows an example job that counts how many times it has been triggered by an event and deactivates itself when it has been executed twice. It uses its own job-specific configuration layer to store the number of times it has been invoked. This value is passed to each newly created job instance as an initialization argument, and can be checked and written back to the configuration. When the counter exceeds two, the job uses the special deactivation feature of the job execution environment. Each job can have a user time stamp and and administrator time stamp to control activation and deactivation. When a job is deactivated, the execution environment updates the user time stamp value, so that subsequent events do not start this job again. It can be enabled by a newer time stamp value in the administration layer.

Flow diagram of an example job