java.lang.Object
- sleep.runtime.ScriptLoader

```
public class ScriptLoader
extends java.lang.Object
```
The ScriptLoader is a convienence container for instantiating and managing ScriptInstances.

To load a script from a file and run it:
```
 ScriptLoader   loader = new ScriptLoader();
 ScriptInstance script = loader.loadScript("script.sl");

 script.runScript();
 
```
The above will load the file script.sl and then execute it immediately.

Installation of loadable bridges you create can also be managed by the ScriptLoader.

A loadable bridge is installed into the language by adding it to a script loader class. There are two types of bridges. The two types are specific and global bridges.

The load and unload methods for a specific bridge are executed for every script load and unload, no matter what.

A global bridge is installed once for each script environment. If scripts are sharing an environment there is no sense in loading stuff into the environment more than once. This is why global bridges exist.

An example of adding a loadable bridge to a script loader:
```
 ScriptLoader loader = new ScriptLoader()
 loader.addSpecificBridge(new MyLoadableBridge());
 
```
There is a difference between "loading" and "compiling" a script:

This class contains several methods to either load or compile a script. Loading a script instantiates a script environment, registers the script with the script loader, and registers all of the appropriate bridges with the script on top of compiling the script.

To compile a script means to produce a runnable Block of code. On its own a Block is not really runnable as a script environment is needed. For functions eval(), include(), etc.. it makes sense to compile a script as you may want to run the block of code within the environment of the calling script. Using the compile method saves on the overhead of unnecessary script environment creation and bridge registration.

Management of Script Reloading

The ScriptInstance class has a an associateFile method to associate a source File object with a script. The &include function calls this method when a file is included into the current script context. To check if any of the associated files has changed call hasChanged on the appropriate ScriptInstance.

The ScriptLoader will automatically associate a source file with a ScriptInstance when a File object is passed to loadScript. If you choose to do some voodoo compiling scripts and managing your own cache (not necessary btw) then you will have to call associateFile against any ScriptInstance you construct

Script Cache

The ScriptLoader mantains a cache of Blocks. These are indexed by name and a timestamp of when they were created. You may call the touch method with the name and a timestamp to allow the ScriptLoader to invalidate the cache entry. If you just load scripts from files then the script cache will just work. To disable the cache use loader.setGlobalCache(false).

Hopefully this helped to clarify things. :)

Field Summary

Fields
Modifier and Type	Field	Description
`protected static java.util.Map`	`BLOCK_CACHE`	cache for parsed scripts mantained (optionally) by the script loader.
`protected java.util.LinkedList`	`bridgesg`	global bridges
`protected java.util.LinkedList`	`bridgess`	specific bridges
`protected boolean`	`disableConversions`
`protected java.util.LinkedList`	`loadedScripts`	loaded scripts
`protected java.util.LinkedList`	`paths`	path to search for jar files imported using [import * from: *] syntax
`protected java.util.Map`	`scripts`	loaded scripts except referable by key

Constructor Summary

Constructors
Constructor Description

ScriptLoader()
initializes the script loader

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`addGlobalBridge(Loadable l)`	A global bridge is loaded into an environment once and only once.
`void`	`addSpecificBridge(Loadable l)`	A specific bridge is loaded into every script regardless of wether or not the environment is shared.
`Block`	`compileScript(java.io.File file)`	compiles the specified script file
`Block`	`compileScript(java.lang.String fileName)`	compiles the specified script file
`Block`	`compileScript(java.lang.String name, java.io.InputStream stream)`	compiles a script using the specified stream as a source
`Block`	`compileScript(java.lang.String name, java.lang.String code)`	compiles the specified script into a runnable block
`java.lang.String`	`getCharset()`
`ScriptEnvironment`	`getFirstScriptEnvironment()`	Convienence method to return the script environment of the first script tht was loaded, returns null if no scripts are loaded
`java.util.LinkedList`	`getScripts()`	Returns a linked list of all loaded ScriptInstance objects
`java.util.Map`	`getScriptsByKey()`	Returns a HashMap with all loaded scripts, the key is a string which is just the filename, the value is a ScriptInstance object
`java.util.Set`	`getScriptsToLoad(java.util.Set configured)`	A convienence method to determine the set of scripts to "load" based on a passed in set of scripts that are currently configured.
`java.util.Set`	`getScriptsToUnload(java.util.Set configured)`	A convienence method to determine the set of scripts to "unload" based on a passed in set of scripts that are currently configured.
`protected void`	`initDefaultBridges()`	method call to initialize the default bridges, if you want to change the default bridges subclass this class and override this method
`protected void`	`inProcessScript(java.lang.String name, ScriptInstance si)`	Process the newly loaded script.
`boolean`	`isCharsetConversions()`
`boolean`	`isLoaded(java.lang.String name)`	Determines wether or not the script is loaded by checking if the specified key exists in the script db.
`ScriptInstance`	`loadScript(java.io.File file)`	Loads the specified script file
`ScriptInstance`	`loadScript(java.io.File file, java.util.Hashtable env)`	Loads the specified script file, uses the specified hashtable for the environment
`ScriptInstance`	`loadScript(java.lang.String fileName)`	Loads the specified script file
`ScriptInstance`	`loadScript(java.lang.String name, java.io.InputStream stream)`	loads a script from the specified inputstream
`ScriptInstance`	`loadScript(java.lang.String name, java.io.InputStream stream, java.util.Hashtable env)`	loads a script from the specified input stream using the specified hashtable as a shared environment
`ScriptInstance`	`loadScript(java.lang.String name, java.lang.String code, java.util.Hashtable env)`	loads the specified script
`ScriptInstance`	`loadScript(java.lang.String fileName, java.util.Hashtable env)`	Loads the specified script file, uses the specified hashtable for the environment
`ScriptInstance`	`loadScript(java.lang.String name, Block code, java.util.Hashtable env)`	creates a Sleep script instance using the precompiled code, name, and shared environment.
`ScriptInstance`	`loadScriptNoReference(java.lang.String name, Block code, java.util.Hashtable env)`	creates a Sleep script instance using the precompiled code, name, and shared environment.
`ScriptInstance`	`loadSerialized(java.io.File script, java.util.Hashtable env)`	Load a serialized version of the script iff a serialized version exists, and its modification time is greater than the modification time of the script.
`ScriptInstance`	`loadSerialized(java.lang.String name, java.io.InputStream stream, java.util.Hashtable env)`	Loads a serialized script from the specified input stream with the specified name
`static void`	`saveSerialized(ScriptInstance si)`	Saves a serialized version of the compiled script to scriptname.bin.
`static void`	`saveSerialized(ScriptInstance si, java.io.OutputStream stream)`	Saves a serialized version of the ScriptInstance si to the specified output stream
`void`	`setCharset(java.lang.String charset)`	If charset conversion is enabled and charset is set, then the stream will be read using specified charset.
`void`	`setCharsetConversion(boolean b)`	Java by default maps characters from an 8bit ascii file to an internal 32bit unicode representation.
`java.util.Map`	`setGlobalCache(boolean setting)`	The Sleep script loader can optionally cache parsed script files once they are loaded.
`void`	`touch(java.lang.String name, long lastModifiedTime)`	nudge the cache with the last modified time of the specified script.
`void`	`unloadScript(java.lang.String filename)`	unload a script
`void`	`unloadScript(ScriptInstance script)`	unload a script

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - BLOCK_CACHE
```
protected static java.util.Map BLOCK_CACHE
```
    cache for parsed scripts mantained (optionally) by the script loader.
  - loadedScripts
```
protected java.util.LinkedList loadedScripts
```
    loaded scripts
  - scripts
```
protected java.util.Map scripts
```
    loaded scripts except referable by key
  - bridgesg
```
protected java.util.LinkedList bridgesg
```
    global bridges
  - bridgess
```
protected java.util.LinkedList bridgess
```
    specific bridges
  - paths
```
protected java.util.LinkedList paths
```
    path to search for jar files imported using [import * from: *] syntax
  - disableConversions
```
protected boolean disableConversions
```
- Constructor Detail
  - ScriptLoader
```
public ScriptLoader()
```
    initializes the script loader
- Method Detail
  - touch
```
public void touch(java.lang.String name,
                  long lastModifiedTime)
```
    nudge the cache with the last modified time of the specified script. this call will delete the script from the cache if the lastModifiedTime > lastLoadTime
  - setGlobalCache
```
public java.util.Map setGlobalCache(boolean setting)
```
    The Sleep script loader can optionally cache parsed script files once they are loaded. This is useful if you will have several script loader instances loading the same script files in isolated objects.
  - initDefaultBridges
```
protected void initDefaultBridges()
```
    method call to initialize the default bridges, if you want to change the default bridges subclass this class and override this method
  - addGlobalBridge
```
public void addGlobalBridge(Loadable l)
```
    A global bridge is loaded into an environment once and only once. This way if the environment is shared among multiple script instances this will save on both memory and script load time
  - addSpecificBridge
```
public void addSpecificBridge(Loadable l)
```
    A specific bridge is loaded into *every* script regardless of wether or not the environment is shared. Useful for modifying the script instance while it is being in processed. Specific bridges are the first thing that happens after the script code is parsed
  - getScriptsByKey
```
public java.util.Map getScriptsByKey()
```
    Returns a HashMap with all loaded scripts, the key is a string which is just the filename, the value is a ScriptInstance object
  - isLoaded
```
public boolean isLoaded(java.lang.String name)
```
    Determines wether or not the script is loaded by checking if the specified key exists in the script db.
  - getFirstScriptEnvironment
```
public ScriptEnvironment getFirstScriptEnvironment()
```
    Convienence method to return the script environment of the first script tht was loaded, returns null if no scripts are loaded
  - getScripts
```
public java.util.LinkedList getScripts()
```
    Returns a linked list of all loaded ScriptInstance objects
  - inProcessScript
```
protected void inProcessScript(java.lang.String name,
                               ScriptInstance si)
```
    Process the newly loaded script. Setup its name and load the bridges into the environment assuming this hasn't been done before.
  - loadSerialized
```
public ScriptInstance loadSerialized(java.io.File script,
                                     java.util.Hashtable env)
                              throws java.io.IOException,
                                     java.lang.ClassNotFoundException
```
    Load a serialized version of the script iff a serialized version exists, and its modification time is greater than the modification time of the script. Also handles the muss and fuss of reserializing the script if it has to reload the script. Personally I didn't find much of a startup time decrease when loading the scripts serialized versus parsing them each time. Theres a command 'bload' in the console to benchmark loading a script normally versus serialized. Try it.
    
    Parameters:
    
    script - a file object pointing to the script file...
    
    Throws:
    
    java.io.IOException
    
    java.lang.ClassNotFoundException
  - loadSerialized
```
public ScriptInstance loadSerialized(java.lang.String name,
                                     java.io.InputStream stream,
                                     java.util.Hashtable env)
                              throws java.io.IOException,
                                     java.lang.ClassNotFoundException
```
    Loads a serialized script from the specified input stream with the specified name
    
    Throws:
    
    java.io.IOException
    
    java.lang.ClassNotFoundException
  - saveSerialized
```
public static void saveSerialized(ScriptInstance si)
                           throws java.io.IOException
```
    Saves a serialized version of the compiled script to scriptname.bin.
    
    Throws:
    
    java.io.IOException
  - saveSerialized
```
public static void saveSerialized(ScriptInstance si,
                                  java.io.OutputStream stream)
                           throws java.io.IOException
```
    Saves a serialized version of the ScriptInstance si to the specified output stream
    
    Throws:
    
    java.io.IOException
  - loadScriptNoReference
```
public ScriptInstance loadScriptNoReference(java.lang.String name,
                                            Block code,
                                            java.util.Hashtable env)
```
    creates a Sleep script instance using the precompiled code, name, and shared environment. This function also processes the script using the global and specific bridges registered with this script loader. No reference to the newly created script is kept by the script loader
  - loadScript
```
public ScriptInstance loadScript(java.lang.String name,
                                 Block code,
                                 java.util.Hashtable env)
```
    creates a Sleep script instance using the precompiled code, name, and shared environment. This function also processes the script using the global and specific bridges registered with this script loader. The script is also referened by this loader so it can be processed again (during the unload phase) when unloadScript is called.
  - loadScript
```
public ScriptInstance loadScript(java.lang.String name,
                                 java.lang.String code,
                                 java.util.Hashtable env)
                          throws YourCodeSucksException
```
    loads the specified script
    
    Throws:
    
    YourCodeSucksException
  - compileScript
```
public Block compileScript(java.lang.String name,
                           java.io.InputStream stream)
                    throws YourCodeSucksException,
                           java.io.IOException
```
    compiles a script using the specified stream as a source
    
    Throws:
    
    YourCodeSucksException
    
    java.io.IOException
  - compileScript
```
public Block compileScript(java.io.File file)
                    throws java.io.IOException,
                           YourCodeSucksException
```
    compiles the specified script file
    
    Throws:
    
    java.io.IOException
    
    YourCodeSucksException
  - compileScript
```
public Block compileScript(java.lang.String fileName)
                    throws java.io.IOException,
                           YourCodeSucksException
```
    compiles the specified script file
    
    Throws:
    
    java.io.IOException
    
    YourCodeSucksException
  - compileScript
```
public Block compileScript(java.lang.String name,
                           java.lang.String code)
                    throws YourCodeSucksException
```
    compiles the specified script into a runnable block
    
    Throws:
    
    YourCodeSucksException
  - loadScript
```
public ScriptInstance loadScript(java.lang.String name,
                                 java.io.InputStream stream)
                          throws YourCodeSucksException,
                                 java.io.IOException
```
    loads a script from the specified inputstream
    
    Throws:
    
    YourCodeSucksException
    
    java.io.IOException
  - loadScript
```
public ScriptInstance loadScript(java.lang.String name,
                                 java.io.InputStream stream,
                                 java.util.Hashtable env)
                          throws YourCodeSucksException,
                                 java.io.IOException
```
    loads a script from the specified input stream using the specified hashtable as a shared environment
    
    Throws:
    
    YourCodeSucksException
    
    java.io.IOException
  - loadScript
```
public ScriptInstance loadScript(java.lang.String fileName)
                          throws java.io.IOException,
                                 YourCodeSucksException
```
    Loads the specified script file
    
    Throws:
    
    java.io.IOException
    
    YourCodeSucksException
  - loadScript
```
public ScriptInstance loadScript(java.lang.String fileName,
                                 java.util.Hashtable env)
                          throws java.io.IOException,
                                 YourCodeSucksException
```
    Loads the specified script file, uses the specified hashtable for the environment
    
    Throws:
    
    java.io.IOException
    
    YourCodeSucksException
  - loadScript
```
public ScriptInstance loadScript(java.io.File file,
                                 java.util.Hashtable env)
                          throws java.io.IOException,
                                 YourCodeSucksException
```
    Loads the specified script file, uses the specified hashtable for the environment
    
    Throws:
    
    java.io.IOException
    
    YourCodeSucksException
  - loadScript
```
public ScriptInstance loadScript(java.io.File file)
                          throws java.io.IOException,
                                 YourCodeSucksException
```
    Loads the specified script file
    
    Throws:
    
    java.io.IOException
    
    YourCodeSucksException
  - unloadScript
```
public void unloadScript(java.lang.String filename)
```
    unload a script
  - unloadScript
```
public void unloadScript(ScriptInstance script)
```
    unload a script
  - getScriptsToUnload
```
public java.util.Set getScriptsToUnload(java.util.Set configured)
```
    A convienence method to determine the set of scripts to "unload" based on a passed in set of scripts that are currently configured. The configured scripts are compared to the loaded scripts. Scripts that are loaded but not configured are determined to be in need of unloading. The return Set contains String objects of the script names. The passed in Set is expected to be the same thing (a bunch of Strings).
  - getScriptsToLoad
```
public java.util.Set getScriptsToLoad(java.util.Set configured)
```
    A convienence method to determine the set of scripts to "load" based on a passed in set of scripts that are currently configured. The configured scripts are compared to the loaded scripts. Scripts that are configured but not loaded are determined to be in need of loading. The return Set contains String objects of the script names. The passed in Set is expected to be the same thing (a bunch of Strings).
  - setCharsetConversion
```
public void setCharsetConversion(boolean b)
```
    Java by default maps characters from an 8bit ascii file to an internal 32bit unicode representation. How this mapping is done is called a character set encoding. Sometimes this conversion can frustrate scripters making them say "hey, I didn't put that character in my script". You can use this option to ensure sleep disables charset conversions for scripts loaded with this script loader
  - isCharsetConversions
```
public boolean isCharsetConversions()
```
  - getCharset
```
public java.lang.String getCharset()
```
  - setCharset
```
public void setCharset(java.lang.String charset)
```
    If charset conversion is enabled and charset is set, then the stream will be read using specified charset.
    
    Parameters:
    
    charset - The name of a supported charset

Class ScriptLoader

To load a script from a file and run it:

There is a difference between "loading" and "compiling" a script:

Management of Script Reloading

Script Cache

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

BLOCK_CACHE

loadedScripts

scripts

bridgesg

bridgess

paths

disableConversions

Constructor Detail

ScriptLoader

Method Detail

touch

setGlobalCache

initDefaultBridges

addGlobalBridge

addSpecificBridge

getScriptsByKey

isLoaded

getFirstScriptEnvironment

getScripts

inProcessScript

loadSerialized

loadSerialized

saveSerialized

saveSerialized

loadScriptNoReference

loadScript

loadScript

compileScript

compileScript

compileScript

compileScript

loadScript

loadScript

loadScript

loadScript

loadScript

loadScript

unloadScript

unloadScript

getScriptsToUnload

getScriptsToLoad

setCharsetConversion

isCharsetConversions

getCharset

setCharset