Custom Web Applications

The rtvquery Servlet allows custom client applications to retrieve data tables from the RTView Data Server via a REST interface. The client sends an HTTP GET to the servlet specifying the query parameters, and the servlet returns the query result in XML, JSON, JSONP, or plain text format.

The rtvquery Servlet is intended for use by custom browser-based applications to display tables from the RTView Data Server at relatively low data volumes. For high data volume displays, the RTView Viewer application or Thin Client should be used.

Note: For examples of client applications, see the README.txt file in the \custom\rtvquery-samples directory.

Query Format

The rtvquery Servlet supports queries for tables from either the RTView cache data source or the SQL data source. The query parameters are specified in the URL and the headers of an HTTP GET request.

Note: Rather than formulating HTTP GETs and processing the responses, Ajax clients can make queries more simply by using the JavaScript library included with the servlet.

Cache Table Queries

If the rtvquery Servlet is deployed at http://host/rtvquery, the URL for a cache query is:

http://host/rtvquery/cache/<cacheName>/<tableName>

For example, the URL to request the history table from a cache named Production is:

http://host/rtvquery/cache/Production/history

The cache and table names should be URL encoded if they contain special characters. For example, the URL to request the current table from a cache named CPU Usage is:

http://host/rtvquery/cache/CPU+Usage/current 

In addition to the cache and table names, several optional parameters can be specified in the URL to refine the query. For example:

http://host/rtvquery/cache/<cacheName>/<tableName>?<param1>=<value1>&<param2>=<value2>...

Parameter values must be URL encoded if they contain special characters.

Cache Query Optional Parameters

The following are optional parameters for cache queries. Each parameter corresponds to a filter option in a cache data source attachment in RTView. If a parameter is not specified, its default value is used in the query.

Note: The optional parameters can also be specified as custom headers in the HTTP GET request. For example, the name of the custom header for a query parameter named "P" is x-sl-P. The name of the custom header for specifying the time range is x-sl-tr. Unlike URL parameter values, if a query parameter is specified by a custom header, the value should not be URL encoded. Specifying query parameters in custom headers rather than URL parameters avoids the browser URL length limits (about 2000 characters in some IE versions). If the fmt parameter is not specified in the URL or in the x-sl-fmt header, the response format is determined by the value of the standard http "Accept" header.

Cache Query URL Examples

The following are Cache Query URL examples.

Note: For brevity, the base URL (for example, http://host/rtvquery/) is omitted from the following examples.

Get the Customer, Symbol and Purchase Price columns from the current table of a cache named trades, in xml format:

cache/trades/current?cols=Customer;Symbol;Purchase+Price&fmt=xml   

Get all columns of the most recent 5 minutes of data from the trades.history table, for a customer named John Doe, in JavaScript array format:

cache/trades/history?tr=300&fcol=Customer&fval=John+Doe&fmt=js   

Get all columns from the trades.current table, for customers named John Doe or Alice Chen and for symbol = IBM or GE, in json format:

cache/trades/current?fcol=Customer;Symbol&fval=John+Doe,Alice+Chen;IBM,GE&fmt=json   

Get all columns from trades.history table, with indicated begin and end times, but no more than 1500 rows, in text format:

cache/trades/history?tb=June+17,2010+10:00:00&te=June+17,2010+10:15:00&rp=1500&fmt=text   

SQL Table Queries

If the rtvquery Servlet is deployed at http://host/rtvquery, the URL for an SQL query is:

http://host/rtvquery/sql/<dbName>?sql=<sqlQueryString>

where dbName is the name of the RTView database connection.   

The SQL query string must be URL encoded. For example, the URL to perform the SQL query select * from production_table on an RTView database connection named SampleDB is:

http://host/rtvquery/sql/sampleDB?sql=select+*+from+production_table   

Alternatively, the SQL query string can be omitted from the URL and specified in a custom http header named x-sl-sql.

SQL Query Optional Parameters

The following are optional parameters for SQL queries.

Responses

This section describes supported response formats and response status for the rtvquery Servlet.

Response Formats

The supported response formats are named xml, json, jsonp, js, xmlrtv, and text.

XML Response Format

The following is an XML response format, where <DataType> is one of the following strings: string, int, long, double, or date.

<dataset>

<metadata>

<column name="column 1 name" type=DataType/>

... metadata for other columns ...

</metadata>

<data>

<row>

<column_1_name>row 1, column 1 value</column_1_name>

... data for other columns in row 1 ...

</row>

... data for other rows ...

</data>

</dataset>

JSON Response Format

The following is a json response format, where <DataType> is one of the following strings: string, int, long, double, or date.

{

  "metadata":[

     {"name":"column 1 name","type":DataType},

       ... metadata for other columns ...

    ],

    "data":[

      {"column 1 name":"row1, column1 value", ... data for other columns in row 1},

        ... data for other rows ...

    ]

}

JSONP Response Format

The following is a response in jsonp format:

jsonpCallback (json object using format described above>);

The jsonp format can be used to make cross-domain requests to the rtvquery servlet. The name of the JavaScript callback function can be specified via the callback parameter in the query URL. If not specified, then jsonpCallback is used. The callback function must be defined before the query is made. For example, the following uses jsonp to make a cache query and write the result to the JavaScript console:

<!doctype html>

<html>

<body>

<script>

var url = "http://somehost/rtvquery/cache/myCache/current?fmt=jsonp&callback=myCallback";

// callback function for jsonp response

var myCallback = function (queryResultAsJson) {

    console.log("query result:" +

       JSON.stringify(queryResultAsJson));

}

// create script element to make jsonp query

var scr = document.createElement("script");

scr.setAttribute("type", "text/javascript");

scr.src = url;

document.body.appendChild(scr);

</script>

<body>

<html>

The arr=1 parameter can be specified along with fmt=jsonp to make a cross-domain query, but have the data rows in the response formatted as a JavaScript array rather than an array of json objects, for conciseness.

JavaScript Array Response Format

The following is a JavaScript Array response format, where <DataType> is one of the following strings: string, int, long, double, or date. The first row in the array contains the column names, the second row contains the column data types, and the remaining rows are the data rows from the data table. This format is the most compact format.

[

  ["column 1 name", "column 2 name", ...],

  [DataType, DataType, ...],

  [value for column 1 in row 1, value for column 2 in row 1, ...],

  [row 2 values, ...]

  ...

]

XMLRTV Response Format

The following is an XMLRTV response format, where <DataType> is one of the following strings: string, int, long, double, or date. The XMLRTV format is the traditional XML dataset format used in RTView.

<table key="test">

  <tc name="column 1 name" type=DataType index="false"/>

  <tc name="column 2 name" type=DataType index="false"/>

  ...more column definitions ...

  <tr name="">

     <td>value for column 1 in row 1</td>

     <td>value for column 2 in row 1</td>

     ...

  </tr>

  ... other rows ...

</table>

Text Response Format

The following is a text response format, where <DataType> is one of the following strings: string, int, long, double, or date. The text format uses tabs to separate columns.

column 1 name <tab> column 2 name <tab> ...

row 1, col 1 value <tab> row 2, col 2 value <tab> ...

...

Response Status

The following describes the response status indicated by the integer value of the custom header x-sl-status, and the corresponding string value of the header x-sl-status-text.

Servlet Configuration Files

The rtvquery.war file contains two files that determine servlet behavior: web.xml and rtvquery.properties. Within rtvquery.war, the paths for these files are WEB-INF/web.xml and WEB-INF/classes/com/sl/rtvquery/rtvquery.properties, respectively.

rtvquery.properties defines the port number of the RTView Data Server to which the servlet connects. The default value is 3278. The servlet supports a backup Data Server connection. To specify a backup Data Server connection, open the rtvquery.properties file, located in the servlets\rtvquery directory, and add a line as follows:

DataServerBackup=host:port

where host:port are the hostname and port number of the backup Data Server. After editing the file, run the make_war script and redeploy the rtvquery.war file. Several other servlet properties are also defined in rtvquery.properties. See the comments in that file for a description of each.

web.xml should be edited only if it is necessary to change the servlet authentication. By default, authentication is disabled, so any client can submit queries to the servlet. To enable authentication, edit the web.xml file, uncommenting the authentication section at the end of the file, and remake and redeploy the rtvquery.war file. When authentication is enabled, the browser prompts the user for login information when the first request for a session is sent to the servlet. The user must enter a username and password that are valid for the application server (for example, Tomcat). For details, see the comments in the web.xml file.

The source for these two files are in \servlets\rtvquery. Use the make_war.bat and make_war.sh scripts to rebuild rtvquery.war after changing either file.

JavaScript Library

This section is intended for readers familiar with JavaScript, HTML and Ajax.

The rtvquery Servlet includes a JavaScript library to simplify development of Ajax client applications. Examples of client applications that use the library are available in the \custom\rtvquery-samples directory.

Note: Use of the JavaScript library is optional. Alternatively, an application could compose its own HTTP GET requests using the URL and header formats previously described, send them to the rtvquery Servlet using XMLHttpRequest, and process the response itself.

The library is contained in a file named rtvquery.js. Assuming that the client application is deployed in a web directory that is a sibling of the directory in which the rtvquery Servlet is deployed, the following line would typically be used to load the library into an HTML page:

<script src='../rtvquery/rtvquery.js'></script>

The library defines a single JavaScript class named rtvQuery. An instance of that class can be created as follows:

var rtvquery = new rtvQuery();

The rtvQuery constructor takes no arguments.

rtvQuery Class Fields

The following fields are defined by the rtvQuery class.

rtvQuery Class Functions

The following functions are defined by the rtvQuery class.

startQuery(args) Function

Call this function to send a query to the Data Server. The function is returned immediately after the request is sent. The query result is returned asynchronously via the user-defined function specified by the doneCB field using arguments. The startQuery function expects a single argument containing the following fields.

startQuery For Cache Queries

The following fields in the startQuery argument pertain to cache queries. The values should not be URL encoded.

startQuery For SQL Queries

The following fields in the startQuery argument pertain to SQL queries. The values should not be URL encoded.

startQuery Example

The following HTML page calls startQuery to request the current table from a cache named prod_cache, in text format, and displays it in a text area component.

<html>

<head>

<title>Simple cache query using rtvquery servlet</title>

<script src='../rtvquery/rtvquery.js'></script>

<script>

    // callback from 'Run Query' button

function doQuery ()

{

         document.body.style.cursor = 'wait';

        var ta = document.getElementById('ResultArea');

         ta.value = 'Submitted query, waiting for response ...';

        var rtvquery = new rtvQuery();

        rtvquery.startQuery({

                 baseURL : '../rtvquery',

                 cache : 'prod_cache',

                 table : 'current',

                 format : 'text',

                doneCB : function(rtvquery) {

                        document.body.style.cursor = 'auto';

                        if (rtvquery.responseStatus == 0) {

                                // query successful, show result

                                ta.value = rtvquery.response;

                        } else {

                                // query failed, show error msg

                                ta.value = rtvquery.responseStatusText;

                        }

                }

        });

}

</script>

</head>

<body>

<button onclick='doQuery()' id='queryButton'>Run Query</button>

<br><br>

<textarea id='ResultArea' wrap='off' cols='80' rows='20' readonly></textarea>

</body>

</html>

getCacheNames(args) Function

Call this function to get the names of all RTView caches available from the Data Server. The function returns immediately after the request is sent. The cache names are returned asynchronously via the user-defined function specified by the doneCB argument.

The getCacheNames function expects a single argument containing the following fields.

getCacheNames Example

The following script calls to getCacheNames populates a drop-down list with the available cache names.

var namesQuery = new rtvQuery();

namesQuery.getCacheNames ({

         baseURL : '../rtvquery',

        doneCB: function(cacheNames, rtvquery) {

                var list = document.getElementById('cacheNameList');

                list.options.length = 0;

                if (!cacheNames || !cacheNames.length) {

                        alert(rtvquery.responseStatus == 0 ?

                                 'no caches found' :

                                rtvquery.responseStatusText);

                } else {

                        for (var i=0; i < cacheNames.length; ++i) {

                                list.options[i] = new Option(cacheNames[i],

                                        cacheNames[i]);

                        }

                }

        }

});

getCacheColumns(args) Function

Call this function to get the name and type of the columns in a cache table. The function returns immediately after the request is sent. The column information is returned asynchronously via the user-defined function specified by the doneCB argument.

The getCacheNames function expects a single argument containing the following fields:

getCacheColumns Example

The following script calls to getCacheColumns populates a drop-down list with the column names for the current table of a cache named prod_cache:

var colNamesQuery = new rtvQuery();

colNamesQuery.getCacheColumns ({

         baseURL : '../rtvquery',

         cache : 'prod_cache',

         table : 'current',

        doneCB: function(colInfo, rtvquery) {

                // colInfo[0] has column names, colInfo[1] has column types

                var colNames = colInfo ? colInfo[0] : null;

                var list = document.getElementById('cacheNameList');

                list.options.length = 0;

                if (!colNames || !colNames.length) {

                        alert(rtvquery.responseStatus == 0 ?

                                 'no columns found' :

                                rtvquery.responseStatusText);

                } else {

                        for (var i=0; i < colNames.length; ++i) {

                                list.options[i] = new Option(cacheNames[i],

                                        cacheNames[i]);

                        }

                }

        }

});