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.
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.
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:
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]);
}
}
}
});