Class ncsa.horizon.util.Metarunner
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class ncsa.horizon.util.Metarunner

java.lang.Object
   |
   +----ncsa.horizon.util.Metarunner

public class Metarunner
extends Object
implements Runnable
An Runnable object used to fetch the value of a metadatum.

To make this object do anything useful, one must sub-class it and override the getDatum() method. (One should not override the run() method which, in addition to calling the getDatum() method, updates internal data regarding its execution history.) The user then has several ways to fetch and return a value:

If run() completes without interruption, then an internally stored run counter (accessible via getRunCount()) is incremented and the error state is updated. If getDatum() returns with a state of OK or RUN_PROBLEM, the value is stored internally for access via getLastValue().

This class is provided as part of support for metadata within Metadata objects. For example, some metadata may be costly to load into memory if it needs to be downloaded from the network or it requires an expensive computation. This effort may be wasted if the user never asks for the data. The Metadata class provides a mechanism for one to store procedures, in the form of Metarunner objects, for obtaining metadata. The Metarunner is then tranparently executed by the Metadata object when the user first requests the data.

To make use of this capability, programmers should sub-class the Metarunner class, overridding the getDatum() method to fetch and return the value of the metadatum works for. The Metarunner object should then stored in the Metadata object using the name of metadatum appended with the String Metadata.METARUNNER_TAG. When the user later requests the metadatum, the Metadata object first looks for a static value in its hashtable. If it does not exist, then the Metadata object engages the surrogate Metarunner object to fetch the value. If the getDatum() method returns with a status of OK, the Metadata store the returned value as a static value in its list before passing it on to its client. If getDataum() returns RUN_PROBLEM, the Metadata object does not store the returned value, though it does return the value to the client. Any other status from getDatum() will cause null to be returned to the Metadata object. See the Metadata API for more details.


Variable Index

 o errState
value of the error state resulting from the last execution of this Runnable
 o isrunning
true if this Runnable is currently being executed.
 o lastValue
value of metadatum from the last time this Runnable was executed
 o OK
error state: no error occurred
 o RUN_FAILED
error state: runnable encountered an application-specific error
 o RUN_PROBLEM
error state: runnable encountered an application-specific error; however, a usuable or default value has been returned.
 o runCount
true if this Runnable has been executed at least once since being instantiated.
 o THREAD_FAILED
error state: failed to initiate or complete execution of Thread

Constructor Index

 o Metarunner()
construct a Metarunner object

Method Index

 o fetchDatum(Metarunner)
create a Thread, execute the specified Metarunnable, wait for its completion, then return the result.
 o getDatum()
calculate, read, or make up a value for a piece of data.
 o getErrorState()
return the error state resulting from the last time this runnable was executed.
 o getLastValue()
return the value from the last time this runnable was executed
 o getRunCount()
return the number of times this runnable has been fully executed via the run() method.
 o hasRun()
return true if this runnable has been fully executed via the run() method at least once.
 o isRunning()
return true if this runnable is currently being run by some thread
 o run()
execute this Runnable.

Variables

 o OK
  public final static int OK
error state: no error occurred
 o RUN_PROBLEM
  public final static int RUN_PROBLEM
error state: runnable encountered an application-specific error; however, a usuable or default value has been returned.
 o THREAD_FAILED
  public final static int THREAD_FAILED
error state: failed to initiate or complete execution of Thread
 o RUN_FAILED
  public final static int RUN_FAILED
error state: runnable encountered an application-specific error
 o lastValue
  protected Object lastValue
value of metadatum from the last time this Runnable was executed
 o isrunning
  protected Boolean isrunning
true if this Runnable is currently being executed.
 o runCount
  protected int runCount
true if this Runnable has been executed at least once since being instantiated.
 o errState
  protected int errState
value of the error state resulting from the last execution of this Runnable

Constructors

 o Metarunner
  public Metarunner()
construct a Metarunner object

Methods

 o isRunning
  public boolean isRunning()
return true if this runnable is currently being run by some thread
 o getErrorState
  public int getErrorState()
return the error state resulting from the last time this runnable was executed.
 o getLastValue
  public Object getLastValue()
return the value from the last time this runnable was executed
 o hasRun
  public boolean hasRun()
return true if this runnable has been fully executed via the run() method at least once.
 o getRunCount
  public int getRunCount()
return the number of times this runnable has been fully executed via the run() method.
 o run
  public synchronized void run()
execute this Runnable. This method calls getDatum(); thus, subclasses should not override this method but rather should override getDatum(). If getDatum() returns without interruption, the current error state is updated and the run counter is incremented. In addition, if the error state <= 1 (i.e. OK or RUN_PROBLEM), the last known value is also updated.
 o getDatum
  public ValueAndStatus getDatum() throws Exception
calculate, read, or make up a value for a piece of data. This method returns null as a value and OK as an error; thus, subclasses should override this method.
Returns:
ValueAndStatus a container hold the resulting value and an error state.
 o fetchDatum
  public static Object fetchDatum(Metarunner fetcher)
create a Thread, execute the specified Metarunnable, wait for its completion, then return the result.

All Packages  Class Hierarchy  This Package  Previous  Next  Index