1.3 AquaScript (Revision #0)

Concept

Architecturally AquaScript is an embedded Mozilla Rhino JavaScript engine with attached library, which provides an extensive set of APIs, called Aqua Open APIs for:

• database queries
• charts
• reports
• data comparison
• file system access
• email
• web server
• analytics
• network
• random data generation
• input data verification and validation
• version control

The complete documentation on Aqua Open APIs can be found at:  http://docs.aquafold.com/ads/14.0/openapi/

The APIs provide programmatic access to the functionality of Aqua Data Studio. They can be used within a user-built application by means of JavaScript.  A user should write a JavaScript file which is executed in Aqua Data Studio, and in the script be able to access the Java API, the Aqua Open API and any other Java libraries. Please download our Custom Jar solution for an example of how to invoke your own Java library APIs via AquaScript.

A JavaScript engine runs within the AquaScript environment.   This environment features fully functional JavaScript editor with auto completion, JavaScript debugger and a web server intended for running and debugging scripts for web-based applications.  Both Aqua Data Studio and Aqua Data Server implement the AquaScript environment. All AquaScripts developed in either ADStudio or ADServer are fully functional in both applications.

AquaScript execution follows a single threaded model.  Even when the environment allows for running multiple scripts at a time, such as in ADServer, there are no explicit inter-process communication mechanisms provided, and there is no way to create a parallel thread or a process.

Aqua Data Studio is typically used as a development environment and Aqua Data Server as a deployment platform though Aqua Data Server also provides sufficient development and debugging functions.  Aqua Data Server has a scheduler, so the user can automate execution of the scripts on a predefined schedule.

Project

The AquaScript environment includes the concept of a project.  A project is comprised of three folders: AquaScripts, Servers and User Files.  The AquaScripts folder, as the name implies, contains script files.  The Servers folder contains database server connection files similar to a Local Database Servers folder in Aqua Data Studio.  The User Files folder may contain files that an AquaScript can create or modify (files in AquaScripts or Servers folders can not be modified by an AquaScript).

Example

Let's consider a simple example:

 1     var conn = aqua.project.getServerConnection("SQL Server 2000");
 2     conn.connect();
 3
 4     // query
 5     var ds = conn.executeSnapshot("select * from northwind.dbo.Orders");
 6     aqua.console.println(ds.getRowCount() + " line(s) read\n\n");
 7
 8     // test string writer
 9     var out = aqua.io.newStringWriter();
10     out.setLineDelimiter("\n");
11     out.setCellDelimiter(",");
12     out.write(ds);
13
14     aqua.console.println("result:\n" + out.toString().substring(0,800));
15
16     conn.disconnect();

With the very first line

 1     var conn = aqua.project.getServerConnection("SQL Server 2000");

a connection to a database server is obtained.  The name "SQL Server 2000" corresponds to the actual server registration file under "Servers" project folder.

The "aqua" variable is an entry point to the AquaScript API library.  This library is implemented in Java, and is available within the JavaScript environment just like any other Java object.  More specifically, an instance of the AQAqua interface is bound to the top-level name "aqua", from which all other parts of the AquaScript API can be accessed. 

In this example, aqua.project is a JavaScript notation for aqua.getProject() method invocation (both are acceptable).  This method returns an implementation of the AQProject interface (see Javadoc for detail).  The subsequent call to getServerConnection() returns an instance of the AQServerConnection interface which is then placed into the "conn" variable.

Further down,

 5      var ds = conn.executeSnapshot("select * from northwind.dbo.Orders");

The AQServerConnection.executeSnapshot() method is called, which returns an AQDataSet.  In this method, a database query is executed and the resulting data is collected row by row and placed into an in-memory object.  Further operations with this data set do not require an open database connection.   This is one way to get the data from a database.  Another way involves a more traditional  AQResultSet object, similar to the JDBC ResultSet class, which can be obtained by calling executeQuery() instead of executeSnapshot().  The latter is recommended in situations where the volume of data may exceed the amount of available memory.

 6     aqua.console.println(ds.getRowCount() + " line(s) read\n\n");

Since the DataSet object now contains all the data obtained in line 5, we can use the print() function to provide a little feedback to the user.  As we learned before, in JavaScript both ds.getRowCount() and ds.rowCount notations are equivalent.

The next step in this example is to save the data extracted from the database into some form.  For simplicity, we are going to generate a text string instead of a text file (use aqua.io.newFileWriter() to write a text file).  A few calls configure the writer:

 9     var out = aqua.io.newStringWriter();
10     out.setLineDelimiter("\n");
11     out.setCellDelimiter(",");

The bulk of the work is done by

12     out.write(ds);

After which the string writer object contains the resulting text. 

Aqua Open API Naming Conventions

The AquaScript API description is provided by the Javadoc documentation.  Please keep in mind that the Javadoc pages refer to Java interfaces and classes, which use a different naming convention than their AquaScript representation.  For example, an AquaScript construct

aqua.system.currentTime

is actually

aqua.getSystem().getCurrentTime()

where "aqua" is an instance of AQAqua interface and the entry point to the AquaScript library.

The following table provides mapping for top-level AquaScript entities: