com.aquafold.openapi
Interface AQSystem

public interface AQSystem

This interface provides access to low-level system functionality.

An instance of this interface is available to aquascripts via aqua.system alias.

Method Summary

void	forceGC() Force garbage collection.
long	getCurrentTime() Returns current time in milliseconds as reported by System.currentTimeMillis().
String	getenv(String name) Gets the value of the specified environment variable.
long	getMaxMemory() Returns the maximum amount of memory (in bytes) which may be requested by the virtual machine from the OS.
String	getProperty(String key) Gets the system property indicated by the specified key.
String	getProperty(String key, String def) Gets the system property indicated by the specified key.
long	getTotalMemory() Returns the amount of memory (in bytes) currently allocated by the virtual machine.
long	getUsedMemory() Returns the amount of memory (in bytes) currently in use by the virtual machine.
boolean	isLowMemory() Returns true if the memory is almost full.
byte[]	newByteArray(int length) Creates an empty byte array.
Process	runCommand(String commandLine) Executes an external process.
Process	runCommand(String commandLine, String folder) Executes an external process in the specified folder.
Object	runScript(String path) Execute another script.
Object	runScript(String path, Object args) Execute another script with additional parameter.
Object	runScript(String path, Object argument, boolean shareContext) Executes another script with an additional parameter and enables a shared global context.

Method Detail

runCommand

Process runCommand(String commandLine)
                   throws Exception

Executes an external process.

This method is analogous to Runtime.exec(String) call. A script may call Process.waitFor() method on the returned value to wait for the process to finish.

Parameters:

commandLine - Command line.

Throws:

Exception

runCommand

Process runCommand(String commandLine,
                   String folder)
                   throws Exception

Executes an external process in the specified folder.

This method is analogous to Runtime.exec(String, String[], java.io.File) call. A script may call Process.waitFor() method on the returned value to wait for the process to finish.

Parameters:

commandLine - Command line.

folder - Directory to start the process in.

Throws:

Exception

runScript

Object runScript(String path)
                 throws Exception

Execute another script. Returns the result of eval function called with the text of the specified script.

The new script inherits the instance of aqua object but runs in a separate global scope.

Parameters:

path - Local path to the script in the project's AquaScripts folder.

Throws:

Exception

runScript

Object runScript(String path,
                 Object args)
                 throws Exception

Execute another script with additional parameter. This object can be null, a java object, or a javascript object. Multiple arguments can be passed in a javascript array object. The script being called retrieves the value from argument variable in the global context.

Note: In case of child script uses the argument variable, the child script can only be executed from the parent script unless you handle the undefined errors.

Example:

 // Parent Script:
 //creates an AquaScript object with an attribute title and a function greet
 var greeting = {
      title : "Hello",
      greet : function (name) {
          return  this.title + " " + name;
      }
 };
 // executes script with argument greeting object
 aqua.system.runScript("script.xjs", greeting);
 

 

 // Script Being Called (script.xjs):
 // A variable with the name 'argument' contains an object passed from the parent script
  var name = "aqua data user";
 // invoking greet method defined in greeting object of the parent script.
 print(argument.greet(name));
 

The new script shares the instance of aqua object but gets its own global context. This means, among other things, that variables and functions will not be shared.

Parameters:

path - Local path to the script in the project's AquaScripts folder.

args - Script arguments.

Throws:

Exception

runScript

Object runScript(String path,
                 Object argument,
                 boolean shareContext)
                 throws Exception

Executes another script with an additional parameter and enables a shared global context. Unlike runScript(String, Object), this method allows for global context sharing among parent and child scripts. Once the global shared context is set to true, the parent and child scripts can use each others variables and functions.

Note: In case of child script using parent script's function or variables, the child script can be only be executed from the parent script unless you handle the undefined errors.

Example:

 // Parent Script:
 //defines a simple function toUpperCase to convert any string to upper case.
 function toUpperCase(str) {
      return (str) ? str.toUpperCase() : "";
 }
 // executes script with sharedContext set to true
 aqua.system.runScript("script.xjs", null, true);
 // invoking greet method defined in script.xjs.
 print(greet("Hello", "aqua data user"));
 

 

 // Script Being Called (script.xjs):
 function greet(greeting, name) {
     // invoking toUpperCase method defined in parent script.
     return greeting + " " + toUpperCase(name);
  }
 

Parameters:

path - Local path to the script in the project's AquaScripts folder.

argument - Script arguments.

shareContext - Determines whether to share the parent global context or create a separate one.

Throws:

Exception

isLowMemory

boolean isLowMemory()

Returns true if the memory is almost full. The criteria and algorithm of determining whether memory is full is a trade secret.

forceGC

void forceGC()

Force garbage collection. Unlike System.gc(), this method actually tries to collect in the calling thread.

getCurrentTime

long getCurrentTime()

Returns current time in milliseconds as reported by System.currentTimeMillis().

getUsedMemory

long getUsedMemory()

Returns the amount of memory (in bytes) currently in use by the virtual machine.

getTotalMemory

long getTotalMemory()

Returns the amount of memory (in bytes) currently allocated by the virtual machine.

getMaxMemory

long getMaxMemory()

Returns the maximum amount of memory (in bytes) which may be requested by the virtual machine from the OS.

getProperty

String getProperty(String key)

Gets the system property indicated by the specified key. This call is equivalent to System.getProperty(String).

Parameters:

key - the name of the system property.

Returns:

the string value of the system property, or null if there is no property with that key.

getProperty

String getProperty(String key,
                   String def)

Gets the system property indicated by the specified key. This call is equivalent to System.getProperty(String, String).

Parameters:

key - the name of the system property.

def - a default value.

Returns:

the string value of the system property, or the default value if there is no property with that key.

getenv

String getenv(String name)

Gets the value of the specified environment variable. An environment variable is a system-dependent external named value. This call is equivalent to System.getenv(String).

Parameters:

name - the name of the environment variable

Returns:

the string value of the variable, or null if the variable is not defined in the system environment

newByteArray

byte[] newByteArray(int length)

Creates an empty byte array.

Parameters:

length - Array length.