    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