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

Modifier and Type	Method and Description
void	forceGC() Force garbage collection.
long	getCurrentTime() Returns current time in milliseconds as reported by System.currentTimeMillis().
java.lang.String	getenv(java.lang.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.
java.lang.String	getProperty(java.lang.String key) Gets the system property indicated by the specified key.
java.lang.String	getProperty(java.lang.String key, java.lang.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.
java.lang.Process	runCommand(java.lang.String commandLine) Executes an external process.
java.lang.Process	runCommand(java.lang.String[] cmdArray) Executes an external process.
java.lang.Process	runCommand(java.lang.String[] cmdArray, java.lang.String folder) Executes an external process in the specified folder.
java.lang.Process	runCommand(java.lang.String commandLine, java.lang.String folder) Executes an external process in the specified folder.
java.lang.Object	runScript(java.lang.String path) Execute another script.
java.lang.Object	runScript(java.lang.String path, java.lang.Object args) Execute another script with additional parameter.
java.lang.Object	runScript(java.lang.String path, java.lang.Object argument, boolean shareContext) Executes another script with an additional parameter and enables a shared global context.

Method Detail

runCommand

java.lang.Process runCommand(java.lang.String commandLine)
                      throws java.lang.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.

Returns:

the process

Throws:

java.lang.Exception - on error

runCommand

java.lang.Process runCommand(java.lang.String commandLine,
                             java.lang.String folder)
                      throws java.lang.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.

Returns:

the process

Throws:

java.lang.Exception - on error

runCommand

java.lang.Process runCommand(java.lang.String[] cmdArray)
                      throws java.lang.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:

cmdArray - array containing the command to call and its arguments.

Returns:

the process

Throws:

java.lang.Exception - on error

runCommand

java.lang.Process runCommand(java.lang.String[] cmdArray,
                             java.lang.String folder)
                      throws java.lang.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:

cmdArray - array containing the command to call and its arguments.

folder - Directory to start the process in.

Returns:

the process

Throws:

java.lang.Exception - on error

runScript

java.lang.Object runScript(java.lang.String path)
                    throws java.lang.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.

Returns:

the return value

Throws:

java.lang.Exception - on error

runScript

java.lang.Object runScript(java.lang.String path,
                           java.lang.Object args)
                    throws java.lang.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.

Returns:

the return value

Throws:

java.lang.Exception - on error

runScript

java.lang.Object runScript(java.lang.String path,
                           java.lang.Object argument,
                           boolean shareContext)
                    throws java.lang.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.

Returns:

the return value

Throws:

java.lang.Exception - on error

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.

Returns:

TRUE if memory is low

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().

Returns:

the current time

getUsedMemory

long getUsedMemory()

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

Returns:

the used memory (in bytes)

getTotalMemory

long getTotalMemory()

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

Returns:

the total memory (in bytes)

getMaxMemory

long getMaxMemory()

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

Returns:

the maximum memory (in bytes)

getProperty

java.lang.String getProperty(java.lang.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

java.lang.String getProperty(java.lang.String key,
                             java.lang.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

java.lang.String getenv(java.lang.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.

Returns:

the byte array