A job must implement the service com.sun.star.task.Job if it needs to block the thread in which it is executed or com.sun.star.task.AsyncJob if the current state of the office is unimportant for the job. The service that a job implementation supports is detected at runtime. If both are available, the synchronous service Job is preferred by the job execution environment.
A synchronous job must not make assumptions about the environment, neither that it is the only job that runs currently nor that another object waits for its results. Only the thread context of a synchronous job is blocked until the job finishes its work.
An asynchronous job is not allowed to use threads internally, because OpenOffice.org needs to control thread creation. How asynchronous jobs are executed is an implementation detail of the global job execution environment.
Jobs that need a user interface must proceed with care, so that they do not interfere with the message loop of OpenOffice.org. The following rules apply:
- You cannot display any user interface from a synchronous job, because repaint errors and other threading issues will occur.
- The easiest way to have a user interface for an asynchronous job is to use a non-modal dialog. If you need a modal dialog to get user input, problems can occur. The best way is to use the frame reference that is part of the job environment initialization data, and to get its container window as a parent window. This parent window can be used to create a dialog with the user interface toolkit com.sun.star.awt.Toolkit. The C++ protocol handler discussed in Implementation shows how a modal message box uses this approach.
- Using a native toolkit or the Java AWT for your GUI can lead to a non-painting OpenOffice.org. To avoid this, the user interface must be non-modal and the implementation must allow the office to abort the job by supporting com.sun.star.lang.XComponent or com.sun.star.util.XCloseable.
The optional interfaces com.sun.star.lang.XComponent or com.sun.star.util.XCloseable should be supported so that jobs can be disposed of in a controlled manner. When these interfaces are present, the execution environment can call
close() rather than waiting for a job to finish. Otherwise OpenOffice.org must wait until the job is done. Invisible jobs can be especially problematic, because they cannot be recognized as the reason why OpenOffice.org refuses to exit.
|Content on this page is licensed under the Public Documentation License (PDL).|