The Computation Monitor Project

Reference Manual

The ComputationMonitor class and its subclasses

To create a monitored computation, the client object should create an object of class computation.ComputationMonitor or of a class derived from it. The only constructor of this class is:

public ComputationMonitor(Frame base, CompInterface computation);

The base parameter is an optional reference to the AWT frame that will be the parent of the monitor window. It can be null.

The computation parameter is a reference to an object implementing the computation.CompInterface abstract class, described later.

When a computation monitor has been constructed, its run() method executes the computation.

The ComputationMonitor class has some other public methods, to be used to customize a single computation monitor. They are the following:

• void setTitle(String title): Sets the title caption of the monitor frame.
• void setDialogMargins(int pixels): Sets the width in pixels of the margins surrounding every object in the monitor frame.
• void setStatusMinLength(int width): Sets the minimum length of the status messages. Use it as if its name were setStatusLength. Actually, depending on the captions of the buttons, the actual length can be bigger than the amount specified.
• void setUpdateInterval(int millis): Sets the interval between successive updates of the monitor frame content, while the computation is running.
• void setCheckInterval(int millis): Sets the interval between successive checks for deciding to open the monitor window, as for short computation, the monitor frame is not opened. Such checks are performed while the computation is running but the monitor frame is still not open.
• void setMaxNonDialogTime(int millis): Sets the time limit from the start of the computation that should never be surpassed without opening the monitor frame. Actually, for long computations, the decision to open the monitor frame is taken earlier, and for a very slow system, the actual opening of the monitor frame could take more than this limit.
• void setSuspendedCaption(String caption): Sets the caption for the check box to suspend temporarily the computation.
• void setCancelCaption(String caption): Sets the caption for the pushbutton to cancel definitively to computation.

To customize the animation icons of the ComputationMonitor, or to standardize on some customizations, it is possible to derive a class form ComputationMonitor, ovverriding some methods, and then to instantiate monitors from this class.

The methods of the ComputationMonitor class that can be overridden are the following:

• String getDefaultDialogTitle(): Returns the title caption of the monitor frame. The default is "Running".
• int getIconCount(): Returns the number of the icons that compose the animation of the running state. The default is 4.
• int getIconWidth(): Returns the width in pixels of the icons that compose the animation. The default is 16 pixels.
• int getIconHeight(): Returns the height in pixels of the icons that compose the animation. The default is 16 pixels.
• int getDefaultDialogMargins(): Returns the width in pixels of the margins surrounding every object in the monitor frame. The default is 5 pixels.
• int getDefaultStatusMinLength(): Returns the minimum length of the status messages. The default is zero, i.e. no status message is guaranteed to be displayed.
• int getDefaultUpdateInterval(): Returns the interval between successive updates of the monitor frame content, while the computation is running. The default is 400 milliseconds.
• int getDefaultCheckInterval(): Returns the interval between successive checks for deciding to open the monitor window. The default is 400 milliseconds.
• int getDefaultMaxNonDialogTime(): Sets the time limit from the start of the computation that should never be surpassed without opening the monitor frame. The default is 5000 milliseconds (i.e. 5 seconds).
• String getDefaultSuspendedCaption(): Sets the caption for the check box to suspend temporarily the computation. The default is "Suspended".
• String getDefaultCancelCaption(): Sets the caption for the pushbutton to cancel definitively to computation. The default is "Cancel".

He, who would like to change the icons of the animation, should follow the following rules:

• Every icon should be a GIF-format file.
• Every icon file should be in the computation package.
• The suspended-state icon file should be named "run0.gif".
• The running-state icon files should be named "runN.gif" or "runNN.gif", where N or NN is a progressive number, starting from 1. For instance, for having 12 icons for the running-state, the files should be named "run1.gif", "run2.gif", ..., up to "run12.gif".
• Every icon should have the width and the height returned, respectively, by the methods getIconWidth" and getIconHeight.

The Computation class and its subclasses

Every computation monitor needs an object implementing the computation.CompInterface abstract class. In the computation package, there are two classes derived from this class: Computation and RemoteCompProxy. The first is for local computations, the second is for remote computations.

Actually, also the Computation class is abstract, so it must be subclassed by a class implementing its abstract methods.

However, even for remote computations, it is necessary to define a class derived from Computation, that is a concrete computation.

A concrete computation must implement the following methods:

• int getLevelCount()
  • Purpose: To inform the computation monitor of the maximum number of nested levels in the computation.
  • Preconditions: None.
  • Postconditions: The return value is between 1 and 9.
• double getProgress(int level):
  • Purpose: To inform the computation monitor of the fraction of work already accomplished at the specified level.
  • Preconditions: level is between 0 and getLevelCount() - 1.
  • Postconditions: The return value is betwen 0 and 1. If the computation is not yet actually started, the return value is 0. If the computation is completed, the return value is 1. If the computation is still running, the return value is less than 1.
• String getStatus(int level):
• Purpose: To inform the computation monitor of the state of the computation at the specified level.
• Preconditions: level is between 0 and getLevelCount() - 1.
• Postconditions: None.
• void run():
• Purpose: To perform the computation, while checking for interruptions from the computation monitor.
• Preconditions: None.
• Postconditions: None.
• Internal conditions: If possible, the body of the routine updates regularly some members of the object, shared with the getProgress and getStatus methods, which use them to track the computation. If possible, the body of the routine calls often the method isCanceled(), and, if it returns true, terminates quickly the computation.

The concrete computation should define the necessary private variable to store the computation state, and the necessary methods to set the parameters for the computation and to retrieve the results afterwords. These methods will not be called during the computation. The methods getProgress and getStatus are called asynchronously by the computation monitor, so they should not change the state of the computation, and should access only volatile variables.

Running a Local Computation

To run a local computation, the client object should do the following operations, in this order:

1. Create a concrete computation object.
2. Set the parameters of the concrete computation object.
3. Create a computation monitor object, passing to the constructor the concrete computation object.
4. Optionally, customize the computation monitor object.
5. Run the computation monitor object.
6. Get the results from the concrete computation object.

Actually, steps 2 and 3 could be swapped.

Running a Remote Computation

A remote computation, of course, is more complicated. In addition to defining a concrete computation class and an optional computation monitor customized class, it is necessary to define an interface derived from RemoteCompInterface, that is an RMI interface, and a class implementing this interface and derived from the RemoteComputation class, that is an RMI server.

The RMI interface should define the same public methods already defined by the concrete computation class, with the only difference that their declaration should add the clause throws RemoteException.

The RMI server should implement the methods declared by the RMI interface, and should add a private instance variable and a public constructor. Naming AComputation the concrete computation class, and ARemoteComputation the RMI server, the variable and the constructor should be defined by the following code:

private AComputation localComp = new AComputation();
public ARemoteComputation() throws RemoteException {
  setComputation(localComp);
}

The implementation of the RMI methods should simply call the corresponding methods of the private instance variable.

Of course, the RMI server should be bound to an RMI name at the startup of the server, using the Naming class and the rmiregistry process.

To run a remote computation, the client object should do the following operations, in this order:

1. Instantiate a remote computation object, using the lookup method of the Naming class.
2. Set the parameters of the remote computation object.
3. Create a new object of class RemoteCompProxy, passing to the constructor the remote computation object.
4. Create a computation monitor object with the new RemoteCompProxy object.
5. Optionally, customize the computation monitor object.
6. Run the computation monitor object.
7. Get the results from the remote computation object.