Package ca.spatial.util

Class IProperties

java.lang.Object
ca.spatial.util.IProperties
public abstract class IProperties extends Object
This class manages access to scripting engines. Scripting engines are used to run scripts within the Patchworks system. Both the Patchworks and MapViewer applications provide interactive script engine consoles which can be used to access and invoke the Patchworks API.

Patchworks is provided with the BeanShell script engine, but others such as ECMAScript, Groovy and Jython (Python in Java) are also available. Script engines are provisioned by adding the JSR223 jar file to the SPSHOME/Patchworks/lib folder. When a script engine is available if can be accessed by using commands to

In addition this class contains static methods to coordinate access to stored properties, contained in a file named 'patchworks.ini' in each users home directory.

As well, the class manages the loading of script libraries, typically from the scripts folder in the Patchworks installation. After loading the system scripts, this class will try to load a custom initialization file in your home directory, if one exists. The custom file is written the language that the system is being initialized in, and has the name .patchworksrc.<language>

This class also contains methods for synchronizing access to volatile data structures (suspend(), resume()).

In most cases these methods are not intended for internal application use only. The exception for this guidance is for the methods:

User friendly methods
MethodPurpose
logEvent(String,String)Add annotations to the event logs
putGlobal(String,Object)Save a value to a global variable shared between script engines. All active script engines can then access the variable typically by name as a regular variable.
showURL(String)Show a web page in the system default web browser

  • Field Details

    • HOME

      public static final String HOME
      The read-only location of the Patchworks install folder. This is typically within the "Program Files/Spatial Planning Systems" folder.

    • userPwDirectory

      public static final String userPwDirectory
      The read-only location of the personal Patchworks folder. This is usually a Patchworks folder within the Documents folder.

  • Constructor Details

    • IProperties

      public IProperties()

  • Method Details

    • loadProps

      public static Properties loadProps()
      Load the saved properties from the 'patchworks.ini' file that is located in the personal Patchworks folder. These properties keep track of previous inputs to wizards, pervious command settings, etc.

    • saveProps

      public static void saveProps​(Properties prop)
      Save the current set of command properties to the 'patchworks.ini' file that is located in the personal Patchworks folder.

    • setEventLogger

      public static void setEventLogger​(EventLogger logger)
      Set an EventLogger object that will record events that happen during program execution. Typically events will be recorded to the ScenarioEvent report.

      This method is called internally from the Patchworks model and should not be called from user code.

    • logEvent

      public static void logEvent​(String type, String detail)
      Write a message to the event log. 
       IProperties.logEvent("Note", "Adjust weight values");
      Parameters:
      type - Specifies the category of the message.
      detail - A detailed message.

    • setSynchronizationObject

      public static void setSynchronizationObject​(Suspendable object)
      Set the synchronization object that mediates the interaction of map displays and report production with the scheduler.

      This method is called internally from the Patchworks model and should not be called from user code.

    • suspend

      public static boolean suspend()
      Suspend the active simulation. This method is called prior to accessing internal simulation data structures.

      This method is called internally from the Patchworks model and generally does not need to be called from user code.

    • isSuspended

      public static boolean isSuspended()
      Test if the active simulation is a suspended state.

    • resume

      public static void resume()
      Resume the active simulation.

      This method is called internally from the Patchworks model and generally does not need to be called from user code.

    • putGlobal

      public static void putGlobal​(String name, Object value)
      Set a global interpreter value. This value will show up as a variable within all interpreters that are active (e.g. BeanShell, Groovy).
      Parameters:
      name - the variable name
      value - the value to assign to the variable

    • exists

      public static boolean exists​(String name)
      Test if a global variable exists
      Parameters:
      name - the variable name

    • getGlobal

      public static Object getGlobal​(String name)
      Get a global variable object. If the variable does not exist return null.
      Parameters:
      name - the variable name

    • getGlobal

      public static Object getGlobal​(String name, Object def)
      Get a global variable object. If the variable does not exist then return the default value.
      Parameters:
      name - the variable name
      def - the default value if the variable does not exist

    • getInt

      public static int getInt​(String name)
      Get the integer value of a global variable. If the variable does not exist then return 0. If the varaible is not a number then return 0. This method does not attempt to convert string variables to an integer value.
      Parameters:
      name - the variable name

    • getBoolean

      public static boolean getBoolean​(String name)
      Get the boolean value of a global variable. If the variable does not exist then return false. If the variable does not have a boolean value then no conversion is attempted and false is returned.
      Parameters:
      name - the variable name

    • getScriptLanguages

      public static List<String> getScriptLanguages()
      Get a list of currently available language by names. Languages are available if the JSR223 provider jar file is found in the classpath when Patchworks is started. The easiest way to provide a languages is to add the JSR223 jar file to the Patchworks\lib folder in the Patchworks home folder.

    • getLanguageForExtension

      public static String getLanguageForExtension​(String ext)
      Get the name of the language that will process files having the given extension.
      Parameters:
      ext - the extension name

    • getEngineByExtension

      public static ScriptEngine getEngineByExtension​(String ext)
      Get the scripting engine that will be used to process files of the given extension.
      Parameters:
      ext - the extension name

    • getEngineByLanguage

      public static ScriptEngine getEngineByLanguage​(String language)
      Get a scripting engine by the name of the language
      Parameters:
      language - the name of the language

    • getEngineByName

      public static ScriptEngine getEngineByName​(String name)
      Get a scripting engine by using an alternate language name. Scripting engines are allowed to provide multiple alternate names (such as BeanShell which hs alternate names of Beanshell, bsh and java).
      Parameters:
      name - an alternate name for the engine

    • eval

      public static Object eval​(String statement, String language) throws ScriptException
      Evaluate a statement in the context of a language
      Parameters:
      statement - the statement to evaluate
      language - the language of the statement
      Throws:
      ScriptException

    • eval

      public static Object eval​(Reader reader, String language) throws ScriptException
      Evaluate a script that is provided by the Reader in the specified language.
      Parameters:
      reader - the Reader object that provides the script
      language - the language used to process the script
      Throws:
      ScriptException

    • eval

      public static void eval​(File file, String language) throws ScriptException
      Evaluate a script that is referenced by the File in the specified language using the system default character encoding.
      Parameters:
      file - the File object that references the script
      language - the language used to process the script
      Throws:
      ScriptException

    • eval

      public static void eval​(File file, String language, String encoding) throws ScriptException
      Evaluate a script that is referenced by the File in the specified language, using the specified file encoding.
      Parameters:
      file - the File object that references the script
      language - the language used to process the script
      encoding - the character encoding of the file
      Throws:
      ScriptException

    • escapeQuotes

      public static String escapeQuotes​(String path)
      Escape quotes in a string. Any double quote characters that are within the string will be replaced with and encoded \" characters. This is often required to pass quoted strings in to scripts.
      Parameters:
      path - the string to be checked for embedded double quote characters.

    • getConsole

      public static PWConsole getConsole​(String language)
      Get a PWConsole for the given language. If the language is available this will return a console window running with an interpreter for the given language. The first time the console is requested the engine will be initialized. On subsequent calls the same console window will be reused with the same engine.
      Parameters:
      language - the name of the language.

    • moveToGlobalProperties

      public static void moveToGlobalProperties​(ScriptEngine engine)
      Promote the engine variables into the global context. This will find all variables defined in the script engine context, and promote them in to the global context. The variables in the engine context will then be removed.

      This method allows all variables in an engine context to be shared with all other engines.

    • showURL

      public static void showURL​(String url)
      Attempt to display a web page by URL in the system default web browser. The URL should include the protocol to be used, for example 
       showURL("http://localhost:8081/current/index.html")
      will display ReportWriter index for the current simulation and 
       showURL("file:///C:/Project_1/Data/Dictionary.html")
      will show a web page stored in a file.
      Parameters:
      url - the URL to show

    • about

      public static String about()
      Return a string containing information about the Patchworks version and the current execution environment.

    • banner

      public static String banner()
      Return a banner string that is displayed in the script engine console windows.

    • main

      public static void main​(String[] args)
      Start up a Beanshell interpreter in interactive mode. If a script argument is not provided then the iterpreter starts immediately in interactive mode.

      This method requires a first parameter that specifies the scripting language that is to be used. The BeanShell language is almost always available, and other languages may also be available depending on how the installation has been customized. (Note that available languages may be determined usin the getScriptLanguages() command.

      If a script filename is provided then use it as the initial source of commands (as though "source(file);" was executed). After the script has completed the method will exit.

      If no script filename is provided then an interactive shell is invoked. To leave interactive mode and end the interpreter use the "exit();" command.

      This command is usually set up as the default action for double-clicking on a ".bsh" file from the file explorer.

      Parameters:
      args - A list of arguments to this commnd. The first argument (required) is the language to be used. The second argument (optional) is the script source file to be evaluated.