org.ascape.runtime
Class Runner

java.lang.Object
  extended by org.ascape.runtime.Runner
All Implemented Interfaces:
java.io.Serializable, java.lang.Runnable
Direct Known Subclasses:
NonGraphicRunner, SwingRunner

public abstract class Runner
extends java.lang.Object
implements java.io.Serializable, java.lang.Runnable

Manages model runs.

Since:
June 14, 2002
Version:
3.0
Author:
Miles Parker
See Also:
Serialized Form

Field Summary
protected  RuntimeEnvironment environment
          Manages user space UI, settings etc.
 
Constructor Summary
Runner()
           
Runner(RuntimeEnvironment environment)
           
 
Method Summary
static boolean assignEnvironmentParameters(java.lang.String[] args)
          Sets values for the models paramters based on supplied array of key value pairs.
 void close()
           
 void closeAndOpenNew()
          Requests the scape to open another model, closing the existing one.
 void closeAndOpenNewFinally(Scape oldScape)
          Requests the scape to open another model, closing the existing one.
 void closeAndOpenSaved()
          Requests the scape to open a saved run, closing the existing one.
abstract  void closeAndOpenSavedFinally(Scape oldScape)
           
 void closeFinally()
          Closes the application; allowing views to close themseleves gracefully.
 void createEnvironment()
           
static void exit()
          Final kill.
 DataGroup getData()
           
 java.lang.String getDescription()
          Gets the description for the ModelRoot object.
 int getEarliestPeriod()
          Gets the earliestPeriod for the ModelRoot object.
 RuntimeEnvironment getEnvironment()
           
 java.lang.String getHome()
          Returns the path in which all files should by default be stored to and retrieved from.
 java.lang.String getHTMLDescription()
          Returns a brief descripiton (including credits) of the scape or of the model, if this is root scape.
 int getIteration()
           
 int getLatestPeriod()
          Gets the latestPeriod for the ModelRoot object.
 java.lang.Thread getModelThread()
           
 int getPausePeriod()
          Gets the pausePeriod for the ModelRoot object.
 int getPeriod()
           
 java.lang.String getPeriodName()
          Sets the period name for the delegate
 java.util.List getRestartingViews()
          Gets the restartingViews for the ModelRoot object.
 Scape getRootScape()
           
 int getStartPeriod()
          Returns the period that this model started.
 int getStopPeriod()
          Returns the period this scape stops running at.
protected  void initialize()
           
 java.lang.Object instanceFromName(java.lang.String modelName)
           
 boolean isAutoRestart()
          Gets the AutoRestart for the ModelRoot object.
 boolean isBeginningDeserializedRun()
           
 boolean isCloseAndOpenNewRequested()
           
 boolean isCloseAndOpenSavedRequested()
           
 boolean isCloseRequested()
           
static boolean isDisplayGraphics()
           
 boolean isInMainLoop()
           
static boolean isMultiWinEnvironment()
           
 boolean isOpenRequested()
           
 boolean isPaused()
           
 boolean isQuitRequested()
           
 boolean isRestartRequested()
           
 boolean isRunning()
           
 boolean isSaveRequested()
           
static boolean isServeGraphics()
           
static boolean isStartOnOpen()
          Gets the startOnOpen for the Runner object.
 boolean isStep()
           
 boolean isValidPeriod(int period)
          Is the supplied period a valid period for this scape?
 void launch(java.lang.String[] args)
           
 void notify(ScapeEvent event, ScapeListener listener)
           
 void open()
          Creates and runs (if start on open is true) this model scape.
 void open(boolean block)
          Creates and runs (if start on open is true) this model scape.
 void open(java.lang.Object applet, java.lang.String[] args)
          Creates and runs (if start on open is true) this model scape.
 void open(java.lang.Object applet, java.lang.String[] args, boolean block)
          Creates and runs (if start on open is true) this model scape.
 void open(java.lang.String[] args)
          Creates and runs (if start on open is true) this model scape.
 void open(java.lang.String[] args, boolean block)
          Creates and runs (if start on open is true) this model scape.
 Scape open(java.lang.String modelName, boolean block)
          Constructs, creates and runs the supplied model.
 Scape open(java.lang.String modelName, java.lang.Object applet)
          Constructs, creates and runs the supplied model.
 Scape open(java.lang.String modelName, java.lang.Object applet, java.lang.String[] args, boolean block)
          Constructs, creates and runs (if start on open is true) the supplied model.
 Scape open(java.lang.String modelName, java.lang.String[] args)
          Constructs, creates and runs the supplied model.
 Scape open(java.lang.String modelName, java.lang.String[] args, boolean block)
          Constructs, creates and runs the supplied model.
 Scape openChoose()
          Requests the scape to open a model, providing UI for this purpose.
 Scape openChoose(java.lang.String[] args)
          Requests the scape to open a model, providing UI for this purpose.
 void openImplementation(java.lang.Object applet, java.lang.String[] args, boolean block)
          Method neccessary because of amibiguous null values in simpler signature methods.
 Scape openInstance(java.lang.String modelName)
          Constructs, creates and runs the supplied model.
 void openSavedChoose()
          Requests the scape to open a saved run.
 Scape openSavedRun(java.io.File savedRunFile)
           
static Scape openSavedRun(java.io.InputStream is)
           
 Scape openSavedRun(java.lang.String fileName, java.lang.String[] args)
           
 void pause()
          Requests the scape to pause.
 void quit()
          Exits the application; calling stop if running and allowing views to close themseleves gracefully.
 void quitFinally()
          Exits the application; allowing views to close themseleves gracefully.
 void requestRestart()
          Requests the scape to restart.
 void respondControl(ControlEvent control)
          Responds to any control events fired at this scape.
 void restart()
          Stops the scape and requests the scape to restart.
 void resume()
          Requests the scape to resume.
 void run()
          The basic execution cycle of a running scape.
 void run(boolean singlethread)
          The basic execution cycle of a running scape.
protected  void runMainLoop()
          The main run loop of a running simulation.
 void save()
          Requests the scape to save itself, providing UI for this purpose.
abstract  void saveChoose()
          Save the state of the scape to a file.
 void setAutoRestart(boolean autoRestart)
          Sets Restart for the ModelRoot object.
 void setBeginningDeserializedRun(boolean beginningDeserializedRun)
           
 void setCloseAndOpenNewRequested(boolean closeAndOpenNewRequested)
           
 void setCloseAndOpenSavedRequested(boolean closeAndOpenSavedRequested)
           
 void setCloseRequested(boolean closeRequested)
           
 void setDescription(java.lang.String description)
          Sets description for the ModelRoot object.
static void setDisplayGraphics(boolean displayGraphics)
           
 void setEarliestPeriod(int earliestPeriod)
          Sets the earliest period this scape is expected to be run at.
 void setEnvironment(RuntimeEnvironment environment)
           
 void setHome(java.lang.String home)
          Sets the path in which to store all scape related files.
 void setHTMLDescription(java.lang.String HTMLdescription)
          Sets an html-formatted description to be used for the model as a whole.
 void setInMainLoop(boolean inMainLoop)
           
 void setInternalRunning(boolean running)
           
 void setIteration(int iteration)
           
 void setLatestPeriod(int latestPeriod)
          Sets the latest period this scape is expected to be run at.
static void setMultiWinEnvironment(boolean muiltWinEnvironment)
           
 void setOpenRequested(boolean openRequested)
           
 void setPaused(boolean paused)
           
 void setPausePeriod(int pausePeriod)
          Sets pausePeriod for the ModelRoot object.
 void setPeriod(int period)
           
 void setPeriodName(java.lang.String periodName)
          Sets periodName for the ModelRoot object.
 void setQuitRequested(boolean quitRequested)
           
 void setRestartingViews(java.util.List restartingViews)
          Sets restartingViews for the ModelRoot object.
 void setRestartRequested(boolean restartRequested)
           
 void setRootScape(Scape scape)
           
 void setRunning(boolean running)
           
 void setSaveRequested(boolean saveRequested)
           
static void setServeGraphics(boolean serveGraphics)
           
static void setStartOnOpen(boolean _startOnOpen)
          Sets startOnOpen for the ModelRoot object.
 void setStartPeriod(int startPeriod)
          Sets the start period for this scape.
 void setStep(boolean step)
           
 void setStopPeriod(int stopPeriod)
          Sets the stop period for this scape.
 void start()
          Requests the scape to start.
 void stop()
          Requests the scape to stop.
 void testRun()
          Open (create) and run the model, just as in the normal open, but block execution.
 void waitForViewsUpdate()
          Blocks until all views of this scape and this scape's members have been updated.
 void write(java.io.ObjectOutputStream out)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

environment

protected transient RuntimeEnvironment environment
Manages user space UI, settings etc.

Constructor Detail

Runner

public Runner()

Runner

public Runner(RuntimeEnvironment environment)
Method Detail

initialize

protected void initialize()

runMainLoop

protected void runMainLoop()
The main run loop of a running simulation. Seperated from run so that it can be executed in different runtime modes.


respondControl

public void respondControl(ControlEvent control)
Responds to any control events fired at this scape. Currently reacts to start, stop, pause, resume, step, quit, and restart events, as well as listener update report events. All control events except listener updates are passed up to the root. Any other events trigger an untrapped exception.


waitForViewsUpdate

public void waitForViewsUpdate()
Blocks until all views of this scape and this scape's members have been updated.


closeAndOpenNew

public void closeAndOpenNew()
Requests the scape to open another model, closing the existing one. Will not occur until the current iteration is complete; use static forms to open concurrently. Always called on root.


closeAndOpenSaved

public void closeAndOpenSaved()
Requests the scape to open a saved run, closing the existing one. Will not occur until the current iteration is complete; use static forms to open concurrently. Always called on root.


closeAndOpenNewFinally

public void closeAndOpenNewFinally(Scape oldScape)
Requests the scape to open another model, closing the existing one. Always called on root.


openSavedRun

public static Scape openSavedRun(java.io.InputStream is)
                          throws java.io.IOException
Throws:
java.io.IOException

openSavedRun

public Scape openSavedRun(java.lang.String fileName,
                          java.lang.String[] args)
                   throws java.io.IOException
Throws:
java.io.IOException

openSavedRun

public Scape openSavedRun(java.io.File savedRunFile)
                   throws java.io.IOException
Throws:
java.io.IOException

testRun

public void testRun()
Open (create) and run the model, just as in the normal open, but block execution. Should be used for testing model run behavior only.


save

public void save()
Requests the scape to save itself, providing UI for this purpose. Will not occur until the current iteration is complete. Always called on root.


run

public void run()
The basic execution cycle of a running scape. In normal usage this method is not called directly; use start() instead. You might choose to call this method directly if you want the calling code to block, for instance, in order to test that some behavior occurs. In the current implementation, only the root scape is a running thread; all child scapes are iterated through the root thread. Synchronous, determined, reproducible behavior is expected, let us know if you encounter anything different! The cycle always begins by notifying any observers, giving them a chance to observe initial state. Then, the scape waits for the observers to update. When updated, the simulation iterates the root scape and all child scapes with their rules. Again, the scape waits for the observers to update, and the cycle of iteration and update continues until it is paused or stopped. While paused, tick events will be sent to observers, which typically chose to ignore them.

Specified by:
run in interface java.lang.Runnable

assignEnvironmentParameters

public static boolean assignEnvironmentParameters(java.lang.String[] args)
Sets values for the models paramters based on supplied array of key value pairs. Paramters and values are expected to be seperated with an "=", for example: "MyParameter=12".

Parameters:
args - an array of strings with paramter-value paris in the form "{paramter-name}={paramter-value}"
reportNotFound - if paramters not found should result in a console notification and if errors in invocation should be reported, false otherwise

launch

public void launch(java.lang.String[] args)
            throws java.io.IOException
Throws:
java.io.IOException

run

public void run(boolean singlethread)
The basic execution cycle of a running scape. In normal usage this methos is not called directly; use start() instead. You might choose to call this method directly if you want the calling code to block, for instance, in order to test that some behavior occurs. Also use this version with argument "true" if you want to continue using the same thread for restarts.

Parameters:
singlethread - CURRENTLY IGNORED! should the run if restarted continue to use the same thread?

start

public void start()
Requests the scape to start. Note that the scape may not start immeadiatly.

See Also:
setRunning(boolean)

notify

public void notify(ScapeEvent event,
                   ScapeListener listener)

write

public void write(java.io.ObjectOutputStream out)
           throws java.io.IOException
Throws:
java.io.IOException

stop

public void stop()
Requests the scape to stop. Note that the scape will not actually stop until the current iteration is complete.

See Also:
setRunning(boolean)

pause

public void pause()
Requests the scape to pause. (Convenience method).

See Also:
setPaused(boolean)

resume

public void resume()
Requests the scape to resume. (Convenience method).

See Also:
setPaused(boolean)

requestRestart

public void requestRestart()
Requests the scape to restart.


restart

public void restart()
Stops the scape and requests the scape to restart. (Convenience method).

See Also:
setRunning(boolean)

openImplementation

public void openImplementation(java.lang.Object applet,
                               java.lang.String[] args,
                               boolean block)
Method neccessary because of amibiguous null values in simpler signature methods.


open

public void open(java.lang.Object applet,
                 java.lang.String[] args,
                 boolean block)
Creates and runs (if start on open is true) this model scape.

Parameters:
applet - the applet if are we in an applet vm context
args - paramter arguments for the scape
block - should this call block or run in a new thread?

open

public void open(java.lang.Object applet,
                 java.lang.String[] args)
Creates and runs (if start on open is true) this model scape.

Parameters:
applet - the applet if are we in an applet vm context
args - paramter arguments for the scape

open

public void open(java.lang.String[] args,
                 boolean block)
Creates and runs (if start on open is true) this model scape.

Parameters:
args - paramter arguments for the scape
block - should this call block or run in a new thread?

open

public void open(java.lang.String[] args)
Creates and runs (if start on open is true) this model scape.

Parameters:
args - paramter arguments for the scape

open

public void open()
Creates and runs (if start on open is true) this model scape.


open

public void open(boolean block)
Creates and runs (if start on open is true) this model scape.

Parameters:
block - should this call block or run in a new thread?

openSavedChoose

public void openSavedChoose()
Requests the scape to open a saved run.


closeAndOpenSavedFinally

public abstract void closeAndOpenSavedFinally(Scape oldScape)

open

public Scape open(java.lang.String modelName,
                  java.lang.Object applet,
                  java.lang.String[] args,
                  boolean block)
Constructs, creates and runs (if start on open is true) the supplied model.

Parameters:
modelName - the fully qualified name of the Java class for the model's root scape
applet - the applet if are we in an applet vm context
args - paramter arguments for the scape
block - should this call block or run in a new thread?

instanceFromName

public java.lang.Object instanceFromName(java.lang.String modelName)

open

public Scape open(java.lang.String modelName,
                  java.lang.String[] args)
Constructs, creates and runs the supplied model.

Parameters:
modelName - the fully qualified name of the Java class for the model's root scape
args - paramter arguments for the scape

open

public Scape open(java.lang.String modelName,
                  java.lang.String[] args,
                  boolean block)
Constructs, creates and runs the supplied model.

Parameters:
modelName - the fully qualified name of the Java class for the model's root scape
args - paramter arguments for the scape
block - should this call block or run in a new thread?

open

public Scape open(java.lang.String modelName,
                  java.lang.Object applet)
Constructs, creates and runs the supplied model.

Parameters:
modelName - the fully qualified name of the Java class for the model's root scape
applet - the applet if are we in an applet vm context

open

public Scape open(java.lang.String modelName,
                  boolean block)
Constructs, creates and runs the supplied model.

Parameters:
modelName - the fully qualified name of the Java class for the model's root scape

openInstance

public Scape openInstance(java.lang.String modelName)
Constructs, creates and runs the supplied model.

Parameters:
modelName - the fully qualified name of the Java class for the model's root scape

openChoose

public Scape openChoose()
Requests the scape to open a model, providing UI for this purpose.


openChoose

public Scape openChoose(java.lang.String[] args)
Requests the scape to open a model, providing UI for this purpose.


saveChoose

public abstract void saveChoose()
Save the state of the scape to a file.


close

public void close()

closeFinally

public void closeFinally()
Closes the application; allowing views to close themseleves gracefully. Do not call this method directly unless you want to force close; call close() instead, allowing a running scape to stop gracefully. Override this method if you want to provide any scape related pre-quit finalization or clean-up.

See Also:
quit()

quit

public void quit()
Exits the application; calling stop if running and allowing views to close themseleves gracefully. Override quitFinally if you want to provide any pre-quit finalization or clean-up.

See Also:
quitFinally()

quitFinally

public void quitFinally()
Exits the application; allowing views to close themseleves gracefully. Do not call this method directly unless you want to force quit; call quit() instead, allowing a running scape to stop gracefully. Override this method if you want to provide any scape related pre-quit finalization or clean-up.

See Also:
quit()

exit

public static void exit()
Final kill. Calls System exit, which appears neccessary for vm even when code has finished.


createEnvironment

public void createEnvironment()

isDisplayGraphics

public static boolean isDisplayGraphics()

setDisplayGraphics

public static void setDisplayGraphics(boolean displayGraphics)

isServeGraphics

public static boolean isServeGraphics()

setServeGraphics

public static void setServeGraphics(boolean serveGraphics)

isMultiWinEnvironment

public static boolean isMultiWinEnvironment()

setMultiWinEnvironment

public static void setMultiWinEnvironment(boolean muiltWinEnvironment)

getPeriodName

public java.lang.String getPeriodName()
Sets the period name for the delegate

Returns:
the periodName

setPeriodName

public void setPeriodName(java.lang.String periodName)
Sets periodName for the ModelRoot object.

Parameters:
periodName - the periodName

getDescription

public java.lang.String getDescription()
Gets the description for the ModelRoot object.

Returns:
the description

setDescription

public void setDescription(java.lang.String description)
Sets description for the ModelRoot object.

Parameters:
description - the description

getHTMLDescription

public java.lang.String getHTMLDescription()
Returns a brief descripiton (including credits) of the scape or of the model, if this is root scape. Plaintext.

Returns:
the description

setHTMLDescription

public void setHTMLDescription(java.lang.String HTMLdescription)
Sets an html-formatted description to be used for the model as a whole.

Parameters:
HTMLdescription - the description

getStartPeriod

public int getStartPeriod()
Returns the period that this model started.

Returns:
the startPeriod

isStartOnOpen

public static boolean isStartOnOpen()
Gets the startOnOpen for the Runner object. Start on Open is static because we may not have a scape context.

Returns:
the startOnOpen

setStartOnOpen

public static void setStartOnOpen(boolean _startOnOpen)
Sets startOnOpen for the ModelRoot object.

Parameters:
startOnOpen - the startOnOpen

setStartPeriod

public void setStartPeriod(int startPeriod)
                    throws SpatialTemporalException
Sets the start period for this scape. The start period is the period this scape is given when a model run is started.

Parameters:
startPeriod - the period to begin runs at
Throws:
SpatialTemporalException - exception

getStopPeriod

public int getStopPeriod()
Returns the period this scape stops running at. By default, the lesser of latest period and integer maximum value (effectively unlimited.)

Returns:
the stopPeriod

setStopPeriod

public void setStopPeriod(int stopPeriod)
                   throws SpatialTemporalException
Sets the stop period for this scape. The stop period is the period that the scape is automatically stopped at. The scape may be automatically set to start agina at start value is the scape is set to restart.

Parameters:
stopPeriod - the period the scape will stop at upon reaching
Throws:
SpatialTemporalException - exception
See Also:
setAutoRestart(boolean)

getPausePeriod

public int getPausePeriod()
Gets the pausePeriod for the ModelRoot object.

Returns:
the pausePeriod

setPausePeriod

public void setPausePeriod(int pausePeriod)
Sets pausePeriod for the ModelRoot object.

Parameters:
pausePeriod - the pausePeriod

getEarliestPeriod

public int getEarliestPeriod()
Gets the earliestPeriod for the ModelRoot object.

Returns:
the earliestPeriod

setEarliestPeriod

public void setEarliestPeriod(int earliestPeriod)
Sets the earliest period this scape is expected to be run at. 0 by default.

Parameters:
earliestPeriod - the lowest period value this scape can have

getLatestPeriod

public int getLatestPeriod()
Gets the latestPeriod for the ModelRoot object.

Returns:
the latestPeriod

setLatestPeriod

public void setLatestPeriod(int latestPeriod)
Sets the latest period this scape is expected to be run at. Max of integer (effectively unlimited) by default.

Parameters:
latestPeriod - the highest period value this scape can have

getRestartingViews

public java.util.List getRestartingViews()
Gets the restartingViews for the ModelRoot object.

Returns:
the restartingViews

setRestartingViews

public void setRestartingViews(java.util.List restartingViews)
Sets restartingViews for the ModelRoot object.

Parameters:
restartingViews - the restartingViews

isAutoRestart

public boolean isAutoRestart()
Gets the AutoRestart for the ModelRoot object.

Returns:
the Restart state

setAutoRestart

public void setAutoRestart(boolean autoRestart)
Sets Restart for the ModelRoot object.

Parameters:
autoRestart - should the model restart when it ends?

isValidPeriod

public boolean isValidPeriod(int period)
Is the supplied period a valid period for this scape?

Parameters:
period - the period to test
Returns:
true if within earliest and latest periods, false otherwise

getHome

public java.lang.String getHome()
Returns the path in which all files should by default be stored to and retrieved from. Nonstatic, so that parameter can automatically be set from command line, but backing variable is static. Default is "./", can be modified by calling setHome or providing an ascape.home java property. (This may change now since it is no longer neccesary.)

Returns:
the home

setHome

public void setHome(java.lang.String home)
Sets the path in which to store all scape related files. Nonstatic, so that parameter can automatically be set from command line, but backing variable is static.

Parameters:
home - the home

getEnvironment

public RuntimeEnvironment getEnvironment()

isBeginningDeserializedRun

public boolean isBeginningDeserializedRun()

setBeginningDeserializedRun

public void setBeginningDeserializedRun(boolean beginningDeserializedRun)

isCloseAndOpenNewRequested

public boolean isCloseAndOpenNewRequested()

setCloseAndOpenNewRequested

public void setCloseAndOpenNewRequested(boolean closeAndOpenNewRequested)

isCloseAndOpenSavedRequested

public boolean isCloseAndOpenSavedRequested()

setCloseAndOpenSavedRequested

public void setCloseAndOpenSavedRequested(boolean closeAndOpenSavedRequested)

isCloseRequested

public boolean isCloseRequested()

setCloseRequested

public void setCloseRequested(boolean closeRequested)

isInMainLoop

public boolean isInMainLoop()

setInMainLoop

public void setInMainLoop(boolean inMainLoop)

getIteration

public int getIteration()

setIteration

public void setIteration(int iteration)

isOpenRequested

public boolean isOpenRequested()

setOpenRequested

public void setOpenRequested(boolean openRequested)

isPaused

public boolean isPaused()

setPaused

public void setPaused(boolean paused)

getPeriod

public int getPeriod()

setPeriod

public void setPeriod(int period)

isQuitRequested

public boolean isQuitRequested()

setQuitRequested

public void setQuitRequested(boolean quitRequested)

isRestartRequested

public boolean isRestartRequested()

setRestartRequested

public void setRestartRequested(boolean restartRequested)

isRunning

public boolean isRunning()

setRunning

public void setRunning(boolean running)

setInternalRunning

public void setInternalRunning(boolean running)

isSaveRequested

public boolean isSaveRequested()

setSaveRequested

public void setSaveRequested(boolean saveRequested)

isStep

public boolean isStep()

setStep

public void setStep(boolean step)

getData

public DataGroup getData()

setRootScape

public void setRootScape(Scape scape)

getRootScape

public Scape getRootScape()

setEnvironment

public void setEnvironment(RuntimeEnvironment environment)

getModelThread

public java.lang.Thread getModelThread()


Copyright © 1998-2008 The Brookings Institution, NuTech Solutions, Metascape, LLC All Rights Reserved.