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:
- call the getDatum() method directly.
- call the run() method, then call
getLastValue().
- call the static
fetchDatum
method (equivalent to the previous 2-step procedure).
- pass this object as a Runnable to a Thread, execute the Thread,
wait for it to finish, and then call
getLastValue().
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.
-
errState
- value of the error state resulting from the last execution of this
Runnable
-
isrunning
- true if this Runnable is currently being executed.
-
lastValue
- value of metadatum from the last time this Runnable was executed
-
OK
- error state: no error occurred
-
RUN_FAILED
- error state: runnable encountered an application-specific error
-
RUN_PROBLEM
- error state: runnable encountered an application-specific error;
however, a usuable or default value has been returned.
-
runCount
- true if this Runnable has been executed at least once since being
instantiated.
-
THREAD_FAILED
- error state: failed to initiate or complete execution of Thread
-
Metarunner()
- construct a Metarunner object
-
fetchDatum(Metarunner)
- create a Thread, execute the specified Metarunnable, wait for its
completion, then return the result.
-
getDatum()
- calculate, read, or make up a value for a piece of data.
-
getErrorState()
- return the error state resulting from the last time this runnable
was executed.
-
getLastValue()
- return the value from the last time this runnable was executed
-
getRunCount()
- return the number of times this runnable has been fully executed
via the run() method.
-
hasRun()
- return true if this runnable has been fully executed via the run()
method at least once.
-
isRunning()
- return true if this runnable is currently being run by some thread
-
run()
- execute this Runnable.
OK
public final static int OK
- error state: no error occurred
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.
THREAD_FAILED
public final static int THREAD_FAILED
- error state: failed to initiate or complete execution of Thread
RUN_FAILED
public final static int RUN_FAILED
- error state: runnable encountered an application-specific error
lastValue
protected Object lastValue
- value of metadatum from the last time this Runnable was executed
isrunning
protected Boolean isrunning
- true if this Runnable is currently being executed.
runCount
protected int runCount
- true if this Runnable has been executed at least once since being
instantiated.
errState
protected int errState
- value of the error state resulting from the last execution of this
Runnable
Metarunner
public Metarunner()
- construct a Metarunner object
isRunning
public boolean isRunning()
- return true if this runnable is currently being run by some thread
getErrorState
public int getErrorState()
- return the error state resulting from the last time this runnable
was executed.
getLastValue
public Object getLastValue()
- return the value from the last time this runnable was executed
hasRun
public boolean hasRun()
- return true if this runnable has been fully executed via the run()
method at least once.
getRunCount
public int getRunCount()
- return the number of times this runnable has been fully executed
via the run() method.
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.
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.
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