Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS | NEXT CLASS	FRAMES | NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

Class ncsa.horizon.util.Metarunner

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

public class Metarunner

extends java.lang.Object

implements java.lang.Runnable, java.io.Serializable

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.

See Also:

Serialized Form

Field Summary

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

Constructor Summary

Metarunner()
construct a Metarunner object

Method Summary

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

Methods inherited from class java.lang.Object

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

Field Detail

OK

public static final int OK

error state: no error occurred

RUN_PROBLEM

public static final int RUN_PROBLEM

error state: runnable encountered an application-specific error; however, a usuable or default value has been returned.

THREAD_FAILED

public static final int THREAD_FAILED

error state: failed to initiate or complete execution of Thread

RUN_FAILED

public static final int RUN_FAILED

error state: runnable encountered an application-specific error

lastValue

protected java.lang.Object lastValue

value of metadatum from the last time this Runnable was executed

isrunning

protected java.lang.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

Constructor Detail

Metarunner

public Metarunner()

construct a Metarunner object

Method Detail

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 java.lang.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 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.

Specified by:

run() in interface java.lang.Runnable

getDatum

public ValueAndStatus getDatum()
                                         throws java.lang.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 java.lang.Object fetchDatum(Metarunner fetcher)

create a Thread, execute the specified Metarunnable, wait for its completion, then return the result.