facets.util.app
Class AppWatcher

java.lang.Object
  facets.util.Tracer
      facets.util.app.AppWatcher

public abstract class AppWatcher
extends Tracer

High-level monitor of application program operation.

AppWatcher has three closely-related functions.

• Busy checking: Detecting blocking of the event loop.
• Watching: Handling of exceptions thrown by WatchableOperations.
• Cancellation: Honouring WatchableOperation.cancelStyle()s.

Busy checking

By frequent calls to its (GUI toolkit dependent) implementation of checkBusy(), AppWatcher detects blocks in the event loop. This enables it to

• trigger changes in the current BusyCursor
• alert AppWatcher.WatcherCoupler when an WatchableOperation requesting WatchableOperation.CancelStyle.Timeout fails to complete within timeoutBlock ms.
• trigger a system timeout if the event loop blocks for systemTimeout ms

Watching

Exceptions thrown by WatchableOperations are passed to AppWatcher.WatcherCoupler.

Cancellation

While the WatchableOperation completes in a (high-priority) background thread, client code can request cancellation as shown below. Cancellation requests are passed to AppWatcher.WatcherCoupler for confirmation.

Style	Enabled by	Signalled by
WatchableOperation.CancelStyle.Dialog	Blocking the event loop by presenting a modal dialog	Dialog cancelled
WatchableOperation.CancelStyle.Timeout	Blocking the event loop internally while checking for timeouts	Timeout detected during busy checking
WatchableOperation.CancelStyle.Future	Restricting input, setting busy cursor and offering status message via AppWatcher.WatcherCoupler	Input unrestricted

Nested Class Summary

static class

AppWatcher.WatcherCoupler Enables client code to communicate with AppWatcher.

Field Summary

protected java.lang.Thread	blocking
static int	systemTimeout
static int	timeoutBlock
static java.lang.String	traceName

Constructor Summary

AppWatcher(boolean inApplet)

Method Summary

protected void	cancelBlockingDialog()
protected boolean	checkBusy()
protected void	futureRunning(boolean on)
protected void	openBlockingDialog(WatchableOperation op)
void	popCursor()
void	pushCursor(BusyCursor cursor)
protected void	runFuture(WatchableOperation op)
java.lang.Object	runWatched(WatchableOperation op) Runs (and possibly allows cancellation of) an WatchableOperation.
protected void	scheduleFuture(WatchableOperation op)
void	setCoupler(AppWatcher.WatcherCoupler coupler)
protected void	traceOutput(java.lang.String msg) Outputs complete trace messages to console or elsewhere.

Methods inherited from class facets.util.Tracer

trace, trace, trace, trace, trace, traceDebug, traceDebug, traceObjectText, traceOutputWithClass

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

traceName

public static final java.lang.String traceName

timeoutBlock

public static int timeoutBlock

systemTimeout

public static int systemTimeout

blocking

protected java.lang.Thread blocking

Constructor Detail

AppWatcher

public AppWatcher(boolean inApplet)

Method Detail

traceOutput

protected final void traceOutput(java.lang.String msg)

Description copied from class: Tracer

Outputs complete trace messages to console or elsewhere.

Default prepends helpful classname to message.

Overrides:

traceOutput in class Tracer

Parameters:

msg - passed from one of the public methods

runWatched

public final java.lang.Object runWatched(WatchableOperation op)

Runs (and possibly allows cancellation of) an WatchableOperation.

Exceptions thrown are passed to the AppWatcher.WatcherCoupler returned by coupler.

Parameters:

op - may be created within another WatchableOperation providing this specifies WatchableOperation.CancelStyle.None.

Returns:

null or the value returned by WatchableOperation.doOperations(int)

openBlockingDialog

protected void openBlockingDialog(WatchableOperation op)

cancelBlockingDialog

protected void cancelBlockingDialog()

checkBusy

protected boolean checkBusy()

scheduleFuture

protected void scheduleFuture(WatchableOperation op)

runFuture

protected final void runFuture(WatchableOperation op)

futureRunning

protected void futureRunning(boolean on)

setCoupler

public final void setCoupler(AppWatcher.WatcherCoupler coupler)

pushCursor

public final void pushCursor(BusyCursor cursor)

popCursor

public final void popCursor()