Contents Index Implementing the UlSynchObserver interface UltraLite Java development notes pdf/preface.pdf

UltraLite User's Guide
  Developing UltraLite Java Applications
    Monitoring and canceling synchronization

Using the progress viewer


The UltraLite runtime library includes two progress viewer classes, which provide an implementation of synchronization monitoring, together with the ability for end users to cancel synchronization. The progress viewer classes are as follows:

The two classes are used identically. The viewer displays a modal or modeless dialog, which shows a series of messages and a progress bar. Both the messages and the bar are updated during synchronization. The viewer also provides a Cancel button. If the user clicks the Cancel button, synchronization stops and the SQL exception SQLE_INTERRUPTED is thrown.

Threading issues 

In a Java application, all events occur on a single thread called the event thread. Also, all user interface objects are created on the event thread, even if the application is on a different thread at the time. There is only one event thread in an application.

The event thread must never block. Consequently, you should not perform long operations on the event thread, as this leads to painting aberrations. Even calling the show() method on a modal dialog suspends execution of the event thread. You must therefore avoid calling the synchronize() method on the event thread.

Displaying a modal viewer 

The following code snippet illustrates how to invoke a modal instance of the viewer. The import statement uses the AWT version:

import ianywhere.ultralite.ui.SynchProgressViewer;
// create a frame to display a dialog
java.awt.Frame frame = ...;
// get UltraLite connection
Connection conn = ...;
// set synchronization options
UlSynchOptions options = new UlSynchOptions();
options.setUserName( "my_user" );
...
// create the viewer
SynchProgressViewer viewer = new SynchProgressViewer( frame );
viewer.synchronize( frame, options );
// execution stops here until synchronization is complete

When invoked in this manner, the viewer carries out the following operations:

  1. registers itself as a synchronization observer,

  2. spawns a thread to do the synchronization,

  3. displays itself, blocking the current thread.

  4. When synchronization finishes, the observer callback disposes of the dialog, which lets the thread continue.

Displaying a modeless viewer 

The following code snippet illustrates how to invoke a modeless instance of the viewer:

SynchProgressViewer viewer = new SynchProgressViewer( frame, false );
options.setObserver( viewer );
conn.synchronize( options );

In this case, you must ensure that the synchronization occurs on a thread other than the event thread, so that the viewer is not blocked.

Notes 

Contents Index Implementing the UlSynchObserver interface UltraLite Java development notes pdf/preface.pdf