Custom Web Applications

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, 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.

Parameter	Description	Default Value
cols	The names of table columns to include in the query response, separated by semicolons (;).	*
fcol	The names of the filter columns, separated by semicolons (;). The fcol and fval parameters are used together to specify one or more filters. Only rows that pass the filter(s) are included in the query result. The values of columns specified by fcol are compared with the values listed in the fval parameter. In the simplest case, fcol specifies the name of a single filter column, fval specifies a single filter value, and the result includes only rows in which the filter column matches the filter value. If multiple values are acceptable for the filter, they must be separated by commas in fval, and rows in which the filter column matches any of the filter values are included in the query result. If multiple filter columns are required, they should be separated by semicolons in fcol. The corresponding filter values for each filter column should be separated by semicolons in fval.	none
fval	The filter value(s) for each filter column. This parameter is used with the fcol parameter. See the fcol parameter for further details.	none
tr	The time range, in seconds. This parameter is valid only if table=history. The tr, tb and te parameters are time parameters and return the following: If only tr is specified, all rows with timestamps >= currentTime - tr are returned. If only tb is specified, all rows with timestamps >= tb are returned. If tb and tr are specified, all rows in the range of tb to tb + tr are returned. If only te is specified, all rows with timestamps <= te are returned. If te and tr are specified, all rows in the range of te - tr to te are returned. If te, tr and tb are specified, tr is ignored and all rows with timestamps >= tb and <= te are returned.	30
tb	Specifies the begin time (in milliseconds since 1970) for the rows to be retrieved. This parameter is valid only if table=history. See the tr parameter for details about behavior with other time parameters (tr and te).	none
te	Specifies the end time (in milliseconds since 1970) for the rows to be retrieved. This parameter is valid only if table=history. See the tr parameter for details about behavior with other time parameters (tr and tb).	none
rp	Specifies the maximum number of rows per page to be returned. The rp and pn parameters must be used together and have the following behavior: If rp and pn are specified, the first row in the query result is row number *pn rp (where row zero is the top row of the table) and the last row in the result is row number pn * rp + rp**. If only rp is specified, pn defaults to zero. If only pn is specified, it is ignored.	none
pn	Specifies the page number to be returned. The rp and pn parameters must be used together and have the following behavior: If rp and pn are specified, the first row in the query result is row number *pn rp (where row zero is the top row of the table) and the last row in the result is row number pn * rp + rp**. If only rp is specified, pn defaults to zero. If only pn is specified, it is ignored.	0
to	Specifies the query timeout, in seconds.	15
fmt	Specifies the desired response format: text, xml, js, or json. (For details, see Response Formats). If this 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.	xml

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.

Parameter	Default Value	Description
maxrows	none	The maximum number of rows to be returned for the query.
to	15	The amount of time, in seconds, for the query to timeout.
fmt	xml	The query response format: text, xml, js, xmlrtv, or json.

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

Response Formats
The supported response formats are named xml, json, 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 ...
    ]
}

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.

x-sl-status	x-sl-status-text	Description
0	OK	The query was successful.
-1	Not connected to data server.	The query failed and the response is empty.
-2	Query is missing one or more required parameters.	The query failed and the response is empty.
-3	No data received before timeout, query may be invalid.	The query failed and the response is empty.
-4	Error, reason unknown.	The query failed and the response is empty.
-5	Item not found.	The query failed and the response is empty. The cache query specified a cache table that does not exist.

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, un-commenting 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.

Field	Type	Value
responseStatus	Number	The status of the last query. If the HTTP request failed, the value is the HTTP status code (for example, 404). If the HTTP request succeeded, the value indicates the query status: either 0 for success or a negative error value as described for x-sl-status in Response Status.
responseStatusText	String	The status of the last query. If the HTTP request failed, the value indicates the HTTP status (for example, 404 Not Found). If the HTTP request succeeded, the value indicates the query status: either OK for success or one of the error messages described for x-sl-status-text in Response Status.
response	String or Object	The response result of the last query. If the HTTP request for the query failed, the value is undefined. If the query succeeded and the requested format is text, xml, or xmlrtv the value is a string. If the format is js or json the response is a JavaScript object. See Response Status for details.

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.

Field	Description
baseURL	A string indicating the prefix to be prepended to the URL used to access the rtvquery Servlet. For example, if the rtvquery Servlet is located on the same application server as the calling application, the value would typically be ../rtvquery. The default is "".
format	A string indicating the desired response format: xml, json, js, xmlrtv, or text as described in Response Formats. The default is xml.
timeout	The query timeout, in seconds. The default is determined by the rtvquery Servlet properties file and is typically set to 15 seconds.
doneCB	The function to be called when the query result is received. There is no default value. The rtvQuery object that invoked the startQuery function is passed as the first (and only) argument to the doneCB function. The function can access the query result via the rtvQuery response* fields.
noJSConvert	A boolean indicating if a js or json response should be parsed and converted to a JavaScript object. If false, the response is a string. The default is true. Typically this would only be set to false for debugging purposes.

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

Field	Description
cache	The name of the RTView cache. There is no default value.
table	The name of the table. Typically, this is either current or history. The default is none.
columns	A string containing the names of the cache table columns. The default is . For details, see the cols* parameter.
filterColumns	A string containing the names of the cache table columns to be used to filter the result. There is no default value. For details, see the fcol parameter.
filterValues	A string containing the values that the filter column must match for a row to be included in the result. No default value. For details, see the fval parameter.
timeRange	The time range, in seconds, for a history query. The default is 30. For details, see the tr parameter.
timeBegin	The begin (minimum) time for a history query. There is no default value. For details, see the tb parameter.
timeEnd	The end (maximum) time for a history query. There is no default value. For details, see the te parameter.
rowsPerPage	The maximum number of rows to be returned. There is no default value. For details, see the rp parameter.
pageNumber	The page number. The default is 0. For details, see the pn parameter.

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

Field	Description
database	The RTView database name. There is no default value. For details, see SQL Table Queries.
sql	The SQL query string. For details, see SQL Table Queries.
maxRows	The maximum number of rows to be returned. There is no default value.

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.

Field	Description
baseURL	A string indicating the prefix to be prepended to the URL used to access the rtvquery Servlet. If the rtvquery Servlet is located on the same application server as the calling application, the value typically would be ../rtvquery. The default value is "".
doneCB	The function to be called when the result is received. It is called with two arguments. If the query fails, the first argument is null. If the query succeeds, the first argument is a JavaScript array whose first element is an array of the column names, and whose second element is an array of the column types. The column types are the strings int, string, etc. (see Response Formats). The rtvQuery object that invoked getCacheColumns is passed as the second argument to the function. The function can access the query result via the rtvQuery response* fields.

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

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.

Field	Description
baseURL	A string indicating the prefix to be prepended to the URL used to access the rtvquery Servlet. Typically, if the rtvquery Servlet is located on the same application server as the calling application, the value would be ../rtvquery. The default value is "".
cache	The name of the RTView cache. There is no default value.
table	The name of the table. Typically, this is either current or history.
doneCB	The function to be called when the result is received. It is called with two arguments. If the query fails, the first argument is null. If the query succeeds, the first argument is a JavaScript array whose first element is an array of the column names, and whose second element is an array of the column types. The column types are the strings int, string, etc. (see Response Formats.) The rtvQuery object that invoked getCacheColumns is passed as the second argument to the function. The function can access the query result via the rtvQuery response* 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: