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:

• ianywhere.ultralite.ui.SynchProgressViewer    A heavyweight AWT version.

• ianywhere.ultralite.ui.SynchProgressViewer    A Swing version of the viewer that respects the Swing threading model.

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 

• All messages come from the SynchProgressViewerResources resource bundle.

• The viewer implements the UlSynchObserver interface so it can hook into the synchronization process.

• The CustDB sample application includes a progress viewer. The CustDB sample code is in the UltraLite\samples\CustDB\java subdirectory of your SQL Anywhere directory.