org.colos.ejs.library
Class Simulation

java.lang.Object
  extended by org.colos.ejs.library.Animation
      extended by org.colos.ejs.library.Simulation
All Implemented Interfaces:
java.lang.Runnable, LocaleListener
Direct Known Subclasses:
SimulationCollaborative

public abstract class Simulation
extends Animation
implements LocaleListener

A base interface for a simulation


Field Summary
static java.util.ResourceBundle ejsRes
           
 
Fields inherited from class org.colos.ejs.library.Animation
MAXIMUM_FPS, MINIMUM_DELAY, MINIMUM_FPS
 
Constructor Summary
Simulation()
           
 
Method Summary
 void addAvailableLocale(java.lang.String _language)
           
 void addDescriptionPage(java.lang.String _htmlPage, int _width, int _height)
          Called by subclasses to add a description page at start-up
 void addDescriptionPage(java.lang.String _title, java.lang.String _htmlPage, int width, int height)
          Old form for backwards compatibility
 void addElementMenuEntries(java.lang.String elementName, java.util.List<java.lang.Object> _entries)
           
 void addMenuEntries(java.util.List<java.lang.Object> _entries)
           
 Experiment createExperiment(java.lang.String _experimentName)
           
 void createHTMLpage()
          Creates an HTML page
static java.io.File extractToDirectory(java.lang.String _resourceString, java.io.File _targetDirectory, boolean _verbose)
           
 java.util.Set<LocaleItem> getAvailableLocales()
           
 java.net.URL getCodebase()
          Returns the codebase
 java.net.URL getDescriptionPageURL(java.lang.String _htmlPage)
          Returns the URL of a given Description page
static java.lang.String getEjsString(java.lang.String key)
           
 java.util.List<Experiment> getExperiments()
           
static java.lang.String getHomeDir()
           
 java.lang.String getJarName()
          Utility that returns the name of the JAR file which contains the simulation
 java.util.Locale getLocale()
           
 LocaleItem getLocaleItem()
           
 java.lang.String getMainWindow()
          Returns the main frame of the simulation's view.
 java.awt.Component getParentComponent()
          Gets the parent component for subsequent message windows such as a JOptionPane.
static java.lang.String getPathToLibrary()
           
 void getPopupMenu(java.awt.Component _component, int _x, int _y, java.lang.String _element)
           
 void getPopupMenu(java.awt.Component _component, java.lang.String _element)
           
static java.io.File getResourceFile(java.lang.String _filename)
           
 java.util.List<java.lang.String> getStateVariablesList()
          Gets the default list used when saving or reading the state.
static java.lang.String getTemporaryDir()
           
 java.awt.Component getTopLevelComponent(java.awt.Component _component)
           
static java.lang.String getUserDir()
           
 java.lang.String getVariable(java.lang.String _name)
          This method returns a String with the value of a public variable of the model.
 java.lang.String getVariable(java.lang.String _name, java.lang.String _sep)
          This method returns a String with the value of a public variable of the model.
 java.lang.String getVariablesXML(java.util.List<java.lang.String> _varList)
          Returns the state of the variables of the model specified in the given list a a text with XML format.
 java.lang.String getVariablesXML(java.lang.String _varList)
          Returns the state of the variables of the model specified in the given list a a text with XML format.
 java.util.List<java.lang.String> getWindowsList()
          Returns the list of top level containers of the simulation's view.
 LauncherApplet initEmersion()
          Initializes the applet
 boolean isEmersionConnected()
           
static boolean isImageFormatSupported(java.lang.String _format)
           
 void killExperiment()
           
 boolean openDescriptionPageInBrowser(java.lang.String _name)
          Extracts the description pages and opens the required page in the system browser
 boolean openDescriptionPagesInBrowser()
          Extracts the description pages (if not yet done) and opens them in the system browser
 void openURL(java.lang.Object _source, java.net.URL _url, java.awt.Component _parentComponent, boolean _isApplet)
           
 void processArguments(java.lang.String[] _args)
           
 boolean readState(java.lang.String _filename)
          Reads the complete state of the model (as defined by setStateVariablesList()) either from a file on the disk, from memory, or from a url location.
 boolean readState(java.lang.String _filename, java.net.URL _codebase)
          Reads the complete state of the model (as defined by setStateVariablesList()) from a file on the disk, from memory or from a url location.
 java.lang.String readText(java.lang.String _filename)
           Reads a String with user-defined info either from a file on the disk, from memory or from a url location.
 java.lang.String readText(java.lang.String _filename, java.net.URL _codebase)
           Reads a String with user-defined info either from a file on the disk, from memory or from a url location.
 boolean readVariables(java.lang.String _filename, java.util.List<java.lang.String> _varList)
           
 boolean readVariables(java.lang.String _filename, java.net.URL _codebase, java.util.List<java.lang.String> _varList)
          Reads the state of the specified variables of the model either from a file on the disk, from memory or from a url location.
 boolean readVariables(java.lang.String _filename, java.net.URL _codebase, java.lang.String _varList)
          Reads the state of the specified variables of the model either from a file on the disk, from memory or from a url location.
 void runExperiment(Experiment _experiment)
           
 void runExperiment(java.lang.String _experimentClassname)
           
 boolean saveDefaultStateToJar(java.io.File jarFile)
          Saves a default file with default state into the simulation JAR file
 boolean saveImage(java.lang.String _element)
          Saves the image produced by a component.
 boolean saveImage(java.lang.String _filename, java.lang.String _element)
          Saves the image produced by a component to disk.
 boolean saveImageAs(java.lang.String _element)
          Saves the image produced by a component.
 boolean saveState(java.lang.String _filename)
          Saves the complete state of the model (as defined by setStateVariablesList()) either to a file on the disk or to memory.
 boolean saveText(java.lang.String _filename, java.lang.String _text)
          Saves a String with user-defined info either to a file on the disk or to memory.
 boolean saveText(java.lang.String _filename, java.lang.StringBuffer _info)
          Saves user generated info to a file.
 boolean saveVariables(java.lang.String _filename, java.util.List<java.lang.String> _varList)
          Saves the state of the variables of the model specified in the given list, either to a file on the disk or to memory.
 boolean saveVariables(java.lang.String _filename, java.lang.String _varList)
          Saves the state of the variables of the model specified in the given string, either to a file on the disk or to memory.
 void setCodebase(java.net.URL _codebase)
          Sets the codebase
 void setLocale(java.lang.String _language)
           
 void setLocaleItem(LocaleItem _item)
          Sets the locale item for the simulation
 void setParentComponent(java.awt.Component _component)
          Sets the parent component of any subsequent message window such as a JOptionPane.
 void setParentComponent(java.lang.String _componentName)
          Sets the parent component of any subsequent message window such as a JOptionPane using a name
static void setPathToLibrary(java.lang.String _path)
           
 void setStateVariablesList(java.util.List<java.lang.String> _list)
          Sets the default list to use when saving or reading the state.
 void setStateVariablesList(java.lang.String _varList)
          Sets the default list to use when saving or reading the state If not set, the whole state is saved using reflection.
 boolean setVariable(java.lang.String _name, java.lang.String _value)
          This method sets the value of a public variable of the model.
 boolean setVariable(java.lang.String _variable, java.lang.String _value, java.lang.String _sep)
          This method sets the value of a public variable of the model.
 boolean setVariables(java.lang.String _valueList)
          This method is used to set more than one variables of the model at once.
 boolean setVariables(java.lang.String _valueList, java.lang.String _sep, java.lang.String _arraySep)
          This method is used to set more than one variables of the model at once.
 void showDescription()
          Shows the description dialog
 void showDescription(boolean _show)
          Shows/Hides the description dialog
 void showDescriptionAtStartUp(boolean _show)
          Whether the description dialog should show at start-up (true by default)
static java.util.List<java.lang.String> toArrayList(java.lang.String _list)
           
 java.lang.String translateString(java.lang.String _property)
           
 java.lang.String translateString(java.lang.String _property, java.lang.String _default)
           
 
Methods inherited from class org.colos.ejs.library.Animation
apply, apply, applyAll, freeSimulation, getDelay, getModel, getThreadGroup, getTopSimulation, getView, initialize, invokeMethodWhenIdle, isPaused, isPlaying, killAllSimulations, killSimulation, onExit, pause, play, reset, run, runSimulation, runSimulation, setAutoplay, setDelay, setFPS, setModel, setStepsPerDisplay, setUpdateView, setView, step, update, updateAfterModelAction, updateWhenIdle
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ejsRes

public static java.util.ResourceBundle ejsRes
Constructor Detail

Simulation

public Simulation()
Method Detail

getEjsString

public static java.lang.String getEjsString(java.lang.String key)

getPathToLibrary

public static java.lang.String getPathToLibrary()

setPathToLibrary

public static void setPathToLibrary(java.lang.String _path)

getUserDir

public static java.lang.String getUserDir()

getHomeDir

public static java.lang.String getHomeDir()

getTemporaryDir

public static java.lang.String getTemporaryDir()

getResourceFile

public static java.io.File getResourceFile(java.lang.String _filename)

extractToDirectory

public static java.io.File extractToDirectory(java.lang.String _resourceString,
                                              java.io.File _targetDirectory,
                                              boolean _verbose)

setParentComponent

public void setParentComponent(java.awt.Component _component)
Sets the parent component of any subsequent message window such as a JOptionPane.

Parameters:
_component - java.awt.Component

setParentComponent

public void setParentComponent(java.lang.String _componentName)
Sets the parent component of any subsequent message window such as a JOptionPane using a name

Parameters:
_componentName - String

getParentComponent

public java.awt.Component getParentComponent()
Gets the parent component for subsequent message windows such as a JOptionPane.

Returns:
java.awt.Component

setCodebase

public void setCodebase(java.net.URL _codebase)
Sets the codebase


getCodebase

public java.net.URL getCodebase()
Returns the codebase


addAvailableLocale

public void addAvailableLocale(java.lang.String _language)

getAvailableLocales

public java.util.Set<LocaleItem> getAvailableLocales()

translateString

public java.lang.String translateString(java.lang.String _property,
                                        java.lang.String _default)

translateString

public java.lang.String translateString(java.lang.String _property)

setLocaleItem

public void setLocaleItem(LocaleItem _item)
Sets the locale item for the simulation

Specified by:
setLocaleItem in interface LocaleListener

getLocaleItem

public LocaleItem getLocaleItem()

setLocale

public void setLocale(java.lang.String _language)

getLocale

public java.util.Locale getLocale()

addDescriptionPage

public void addDescriptionPage(java.lang.String _htmlPage,
                               int _width,
                               int _height)
Called by subclasses to add a description page at start-up

Parameters:
_htmlPage -
_width -
_height -

addDescriptionPage

public void addDescriptionPage(java.lang.String _title,
                               java.lang.String _htmlPage,
                               int width,
                               int height)
Old form for backwards compatibility

Parameters:
_title -
_htmlPage -
width -
height -

showDescriptionAtStartUp

public void showDescriptionAtStartUp(boolean _show)
Whether the description dialog should show at start-up (true by default)

Parameters:
_show -

showDescription

public void showDescription()
Shows the description dialog


showDescription

public void showDescription(boolean _show)
Shows/Hides the description dialog

Parameters:
_show -

getDescriptionPageURL

public java.net.URL getDescriptionPageURL(java.lang.String _htmlPage)
Returns the URL of a given Description page

Parameters:
_htmlPage -
Returns:

openDescriptionPagesInBrowser

public boolean openDescriptionPagesInBrowser()
Extracts the description pages (if not yet done) and opens them in the system browser


openDescriptionPageInBrowser

public boolean openDescriptionPageInBrowser(java.lang.String _name)
Extracts the description pages and opens the required page in the system browser


openURL

public void openURL(java.lang.Object _source,
                    java.net.URL _url,
                    java.awt.Component _parentComponent,
                    boolean _isApplet)

getVariable

public java.lang.String getVariable(java.lang.String _name)
This method returns a String with the value of a public variable of the model. If the variable is an array, individual element values are separated by a comma. Only public variables of primitive or String type can be accessed.

Parameters:
_name - The name of a public variable of the model
Returns:
The value of the variable as a String.

getVariable

public java.lang.String getVariable(java.lang.String _name,
                                    java.lang.String _sep)
This method returns a String with the value of a public variable of the model. If the variable is an array, individual element values are separated by the specified separator string. Only public variables of primitive or String type can be accessed.

Parameters:
_name - The name of a public variable of the model
_sep - A separator string to use for array variables
Returns:
The value of the variable

setVariable

public boolean setVariable(java.lang.String _name,
                           java.lang.String _value)
This method sets the value of a public variable of the model. If the variable is an array, individual element values must separated by a comma. In this case, if the number of values specifies differs with the length of the array (a warning may be issued and) either the extra values are ignored (if there are more) or the last elements of the array will be left unmodified (if there are less). If the values provided cannot be parsed to the variable type (an error message may be issued and) the method returns false. Only public variables of primitive or String type can be accessed.

Parameters:
_name - the name of a public variable of the model
_value - the value to be given to the variable
Returns:
true if the process was completed sucessfully, false otherwise

setVariable

public boolean setVariable(java.lang.String _variable,
                           java.lang.String _value,
                           java.lang.String _sep)
This method sets the value of a public variable of the model. If the variable is an array, individual element values must separated by the specified separator string. In this case, if the number of values specifies differs with the length of the array (a warning may be issued and) either the extra values are ignored (if there are more) or the last elements of the array will be left unmodified (if there are less). Only public variables of primitive or String type can be accessed. If the values provided cannot be parsed to the variable type (an error message may be issued and) the method returns false.

Parameters:
_variable - the name of a public variable of the model
_value - the value to be given to the variable
_sep - the separator string for arrays
Returns:
true if the process was completed sucessfully, false otherwise

setVariables

public boolean setVariables(java.lang.String _valueList)
This method is used to set more than one variables of the model at once. Pairs of the type 'variable=value' must be separated by semicolons. Then they will be tokenized and sent to setVariable().

Parameters:
_valueList - the string containing the pairs 'variable=value'
Returns:
true if all the variables are correctly set by setVariable()
See Also:
setVariable(String,String);

setVariables

public boolean setVariables(java.lang.String _valueList,
                            java.lang.String _sep,
                            java.lang.String _arraySep)
This method is used to set more than one variables of the model at once. Pairs of the type 'variable=value' must be separated by the separator string _sep. Then they will be tokenized and sent to setVariable(), using _arraySep as separator string for values of array variables.

Parameters:
_valueList - the string containing the pairs 'variable=value'
_sep - the separator string between pairs
_arraySep - the separator string for values of array variables
Returns:
true if all the variables are correctly set by setVariable()
See Also:
setVariable(String,String)

initEmersion

public LauncherApplet initEmersion()
Initializes the applet

Returns:
true if teh applet is non-null

isEmersionConnected

public boolean isEmersionConnected()

isImageFormatSupported

public static boolean isImageFormatSupported(java.lang.String _format)

getExperiments

public java.util.List<Experiment> getExperiments()

createExperiment

public Experiment createExperiment(java.lang.String _experimentName)

runExperiment

public void runExperiment(Experiment _experiment)

runExperiment

public void runExperiment(java.lang.String _experimentClassname)

killExperiment

public void killExperiment()

addMenuEntries

public void addMenuEntries(java.util.List<java.lang.Object> _entries)

addElementMenuEntries

public void addElementMenuEntries(java.lang.String elementName,
                                  java.util.List<java.lang.Object> _entries)

getTopLevelComponent

public java.awt.Component getTopLevelComponent(java.awt.Component _component)

getPopupMenu

public void getPopupMenu(java.awt.Component _component,
                         java.lang.String _element)

getPopupMenu

public void getPopupMenu(java.awt.Component _component,
                         int _x,
                         int _y,
                         java.lang.String _element)

getWindowsList

public java.util.List<java.lang.String> getWindowsList()
Returns the list of top level containers of the simulation's view. Subclasses should overwrite this method.

Returns:
ArrayList

getMainWindow

public java.lang.String getMainWindow()
Returns the main frame of the simulation's view. Subclasses should overwrite this method.

Returns:
ArrayList

getJarName

public java.lang.String getJarName()
Utility that returns the name of the JAR file which contains the simulation

Returns:

createHTMLpage

public void createHTMLpage()
Creates an HTML page


saveImage

public boolean saveImage(java.lang.String _element)
Saves the image produced by a component. The name is created from the name of the simulation class plus a counter

Parameters:
_element - the name of the view element to get the image from
Returns:
true if the file was correctly saved

saveImageAs

public boolean saveImageAs(java.lang.String _element)
Saves the image produced by a component. The user will be given the chance to choose a name.

Parameters:
_element - the name of the view element to get the image from
Returns:
true if the file was correctly saved

saveImage

public boolean saveImage(java.lang.String _filename,
                         java.lang.String _element)
Saves the image produced by a component to disk.

Parameters:
_filename - the name of a file (either in disk or in memory). Null if the user must select a name.
_element - the name of the view element to get the image from
Returns:
true if the file was correctly saved

processArguments

public void processArguments(java.lang.String[] _args)

toArrayList

public static java.util.List<java.lang.String> toArrayList(java.lang.String _list)

getStateVariablesList

public java.util.List<java.lang.String> getStateVariablesList()
Gets the default list used when saving or reading the state. If null, the whole state is saved using reflection.


setStateVariablesList

public void setStateVariablesList(java.util.List<java.lang.String> _list)
Sets the default list to use when saving or reading the state. If not set, the whole state is saved using reflection.

Parameters:
_list - ArrayList the list of variables that define the state to save or read

setStateVariablesList

public void setStateVariablesList(java.lang.String _varList)
Sets the default list to use when saving or reading the state If not set, the whole state is saved using reflection.

Parameters:
_list - String a comma or semicolon list of variables that define the state to save or read

saveState

public boolean saveState(java.lang.String _filename)
Saves the complete state of the model (as defined by setStateVariablesList()) either to a file on the disk or to memory.

Parameters:
_filename - the name of a file, either in disk or in memory (if given the prefix "ejs:")
Returns:
true if the file was correctly saved

readState

public boolean readState(java.lang.String _filename)
Reads the complete state of the model (as defined by setStateVariablesList()) either from a file on the disk, from memory, or from a url location.

Parameters:
_filename - the name of a file, either in disk , in memory (if given the prefix "ejs:") or from a url (if given the prefix "url:") If running as an applet, the codebase of the applet is used for a non-qualified file (one that does not starts explictly with "http:"). If file is null the user will be prompted to select a file from disk.
Returns:
true if the file was correctly read

readState

public boolean readState(java.lang.String _filename,
                         java.net.URL _codebase)
Reads the complete state of the model (as defined by setStateVariablesList()) from a file on the disk, from memory or from a url location.

Parameters:
_filename - the name of a file, either in disk , in memory (if given the prefix "ejs:") or from a url (if given the prefix "url:")
_codebase - the codebase when the simulation runs as an applet
Returns:
true if the file was correctly read

saveVariables

public boolean saveVariables(java.lang.String _filename,
                             java.lang.String _varList)
Saves the state of the variables of the model specified in the given string, either to a file on the disk or to memory.

Parameters:
_filename - the name of a file (either in disk or in memory)
_varList - a String with the list of variables separated by semicolons ';'
Returns:
true if the file was correctly saved
See Also:
#saveVariables(String,ArrayList)

readVariables

public boolean readVariables(java.lang.String _filename,
                             java.net.URL _codebase,
                             java.lang.String _varList)
Reads the state of the specified variables of the model either from a file on the disk, from memory or from a url location.

Parameters:
_filename - the name of a file (either in disk , in memory or a url)
_codebase - the codebase when the simulation runs as an applet
_varList - a String with the list of variables separated by semicolons ';'
Returns:
true if the file was correctly read
See Also:
(String, java.net.URL, ArrayList)

readVariables

public boolean readVariables(java.lang.String _filename,
                             java.net.URL _codebase,
                             java.util.List<java.lang.String> _varList)
Reads the state of the specified variables of the model either from a file on the disk, from memory or from a url location.

If the name of the file starts with the prefix "ejs:", then the state of the model will be read from a memory file that must have been created previously with the corresponding call to saveVariables().

If the name of the file starts with "url:" it will be considered a url location and the method will attempt to read the file from this url (either locally or through the network).

If the codebase is non-null the file is considered to be a network file on that codebase.

In all other cases, the file will be considered to be on a disk. If the filename is null, the user will be prompted to choose a file to read from.

If the name of the file ends in ".xml" the data is expected to be in XML form. Otherwise it is considered to be binary.

Security considerations apply when running the simulation as an applet.

The state of the model is read by reading from disk all its public fields which implement the java.io.Serializable interface. This includes primitives and arrays.

Parameters:
_filename - the name of a file (either in disk, in memory, or a url)
_codebase - the codebase when the simulation runs as an applet
_varList - the list of variables to read
Returns:
true if the file was correctly read

readVariables

public boolean readVariables(java.lang.String _filename,
                             java.util.List<java.lang.String> _varList)

saveVariables

public boolean saveVariables(java.lang.String _filename,
                             java.util.List<java.lang.String> _varList)
Saves the state of the variables of the model specified in the given list, either to a file on the disk or to memory. If the list is null, it saves all the variables of the model.

If the name of the file starts with the prefix "ejs:", then the state of the model will be saved to memory, otherwise it will be saved to disk.

If the name of the file ends with ".xml", then the state of the model will be saved in XML form.

Security considerations apply when running the simulation as an applet.

The state of the model is saved by writing to disk all its public fields which implement the java.io.Serializable interface. This includes primitives and arrays.

Parameters:
_filename - the name of a file (either in disk or in memory). If null, the user will be prompted to choose a file name.
_varList - the list of variables to save. If null, all variables are saved
Returns:
true if the file was correctly saved

saveDefaultStateToJar

public boolean saveDefaultStateToJar(java.io.File jarFile)
Saves a default file with default state into the simulation JAR file

Returns:

getVariablesXML

public java.lang.String getVariablesXML(java.lang.String _varList)
Returns the state of the variables of the model specified in the given list a a text with XML format.

Parameters:
_varList - a String with the list of variables separated by commas ',' or semicolons ';'
Returns:
String the text in XML format
See Also:
#getVariablesXML(ArrayList)

getVariablesXML

public java.lang.String getVariablesXML(java.util.List<java.lang.String> _varList)
Returns the state of the variables of the model specified in the given list a a text with XML format. If the list is null, it saves all the variables of the model.

The state of the model is saved by writing to disk all its public fields which implement the java.io.Serializable interface. This includes primitives and arrays.

Parameters:
_varList - the list of variables to save. If null, all variables are saved
Returns:
String the text in XML format

saveText

public boolean saveText(java.lang.String _filename,
                        java.lang.String _text)
Saves a String with user-defined info either to a file on the disk or to memory.

If the name of the file starts with the prefix "ejs:", then the state of the model will be saved to memory, otherwise it will be dumped to disk.

Security considerations apply when running the simulation as an applet.

Parameters:
_filename - the name of a file (either in disk or in memory)
_text - the user-defined info string
Returns:
true if the file was correctly saved

saveText

public boolean saveText(java.lang.String _filename,
                        java.lang.StringBuffer _info)
Saves user generated info to a file. Equivalent to saveText (_filename,_info.toString());

Parameters:
_filename - String
_info - StringBuffer
Returns:
boolean

readText

public java.lang.String readText(java.lang.String _filename)

Reads a String with user-defined info either from a file on the disk, from memory or from a url location.

Parameters:
_filename - the name of a file (either in disk, in memory or a url)
Returns:
String The string read, or null if failed

readText

public java.lang.String readText(java.lang.String _filename,
                                 java.net.URL _codebase)

Reads a String with user-defined info either from a file on the disk, from memory or from a url location.

If the name of the file starts with the prefix "ejs:", then the info string will be read from a memory file.

If the name of the file starts with "url:" it will be considered a url location and the method will attempt to read the file from this url (either locally or through the network).

If the name of the file does not start with any of those prefixes, then it will be considered to be a file. Security considerations apply when running the simulation as an applet.

Parameters:
_filename - the name of a file (either in disk, in memory or a url)
_codebase - the codebase when the simulation runs as an applet
Returns:
String The string read, or null if failed