rtview-proxy-server

rtview-proxy-server - RTView Proxy Server

The rtview-proxy-server package contains JavaScript utility functions that can be used to create a Node.js application that provides a proxy service to a foreign API provider service. It forwards RTView cache queries to the foreign service tranforming both the query and response as needed.

RTView is a real-time data management, visualization and analytics engine provided by SL Corporation (www.sl.com). It is used by organizations worldwide as a key component of mission-critical monitoring and control systems built around various middleware, infrastructure and IoT data sources.

The RTView DataServer is the data management component that provides in-memory caching and archival to persistent storage. Data stored there may be consumed by displays, dashboards, reports and alerts provided by a visualization and analytics tool such as RTView Cloud.

In some cases, there is a need for RTView to integrate with a third-party or foreign service that provides its own historical data. In this case, an RTView DataServer is not used. Instead, an RTView Proxy Server can be defined to translate requests for cache data into equivalent queries to the foreign service. From the perspective of RTView tools such as RTDraw, the remote service is made to appear as if it were an RTView DataServer. Pretty cool, huh ?

This package provides the framework for launching a proxy server with a custom data handler that forwards and transforms queries to and responses from the foreign API server. Using this package, a proxy server can be constructed for many different foreign services. As an example, this repository contains an implementation of a proxy server that connects to the AirNow.org government portal that serves up near real-time and historical metrics about Air Quality throughout the United States.

Installation

The rtview-proxy-server package is a Node module which can be installed using npm:

npm install rtview-proxy-server

Alternatively, the package.json file could be edited to include the lines below, and a simple call to 'npm install' will suffice.

"dependencies": {
    "rtview-proxy-server": ""
}

Usage

To create an RTView Proxy Server in a JavaScript application, an instance of the rtview-proxy-server package is 'required'. Near the top of your program file, add the following line of code to make an instance:

var rtvproxy = require('rtview-proxy-server')();

The utility functions contained within the package are scoped to this 'rtvproxy' instance and may be invoked from the main program of the application as shown below:

// Launch the RTView Proxy Server
// Pass in a custom data handler for returning data (a function named getData in this example)

rtvproxy.run(getData);

Whenever an RTView application makes a request for data, that request is passed to the custom data handler. The application should define its getData() function similar to the example below:

// query the remote service for data defined by the cacheName, tableName and query parameters

var getData = function (cacheName, tableName, res, query, result, callback) {

    // create an RTView JSON tabular data object based on requested cache and table names
    // by querying the foreign service
    result.data = getForeignData(cacheName, tableName, query);
    
    // pass the result back to RTView via the callback    
    callback(res, result, query);
}

Detailed descriptions of these functions, along with useful examples, are provided in the API section below.

API

Table of Contents

• rtview-proxy-server
  • Examples
• run
  • Parameters
  • Examples
• getData
  • Parameters
  • Examples
• create_datacache
  • Parameters
  • Examples
• set_verbose
  • Parameters
  • Examples

rtview-proxy-server

RTView Proxy Server

A set of functions that can be used to define an RTView Proxy Server.

Examples

// Configure the application to make use of the rtview-proxy-server package
// and reference it using the variable name 'rtview'

var rtview = require('rtview-proxy-server')();

run

Begin execution of the proxy server with a specified custom handler.

This function initiates the execution of a server process on the default port or port specified in environment variables.

Parameters

• getData function a custom handler function that obtains data from foreign service

Examples

// Run the server with a custom handler function named myDataHandler

rtview.run (myDataHandler);

getData

Query the remote service for data. (a Custom Data Handler)

This function will be overridden in the user application code that implements transformation of the query to and data returned from the foreign service.

This API is designed to address both synchronous and asynchronous queries. The res and query objects are passed into the custom handler so that they can be used by the callback when it has completed. Returned data are placed into the 'data' field of the result object, as an array of 'data rows', each of which is an array of 'cells'.

Parameters

• cacheName string name of the cache requested
• tableName string name of the table (current or history)
• res object the response object associated with the query
• query object the query object associated with the query
• result object the result object to be populated by the handler
• callback function the callback invoked by the handler when query complete

Examples

// query the remote service for data defined by the cacheName, tableName and query parameters
// This is a VERY simplistic implementation that returns synchronously
// In a real system, the data are returned asynchronously; see other examples

var getData = function (cacheName, tableName, res, query, result, callback) {

    // create an RTView JSON tabular data object based on requested cache and table names
    // by querying the foreign service
    result.data = [ [ 'cell-1', 123, true, '...' ] ];

    // pass the result back to RTView via the callback
    callback(res, result, query);
}

create_datacache

Create a named data cache in the targeted RTView DataServer with the specified properties and structure.

Call this function once for each named data cache required by the application. The DataServer must be active and accepting requests in order for the cache to be created. Once created, its structure is persisted until this function is called again and it is redefined. Multiple caches may be defined within each DataServer.

See the 'Additional Information' section below for details about cache properties and data types that are supported.

Parameters

• cacheName string name of the cache to create
• properties Object set of name:value pairs defining cache properties
• metadata Array<Object> array of name:value pairs defining type of each data element

Examples

// Create a cache named SensorData with the specified properties and structure

var sensorCacheName  = "SensorData";
var sensorProperties = {
    "indexColumnNames" : "ID",
    "historyColumnNames" : "temperature;humidity"
};
var sensorMetadata = [ 
    { "ID" : "string" },
    { "temperature" : "double" },
    { "humidity" : "double" }
];
rtview.create_datacache(sensorCacheName, sensorProperties, sensorMetadata);

set_verbose

Set Verbose Flag

Enables tracing of the calls to the package for debugging purposes.

Parameters

• verbose_flag boolean if true, enable tracing

Examples

// Enable tracing of calls to rtview-proxy-server

rtvproxy.set_verbose (true);

Implementing a Custom Data Handler

More info to be added later.

Complete Example

The following is a complete example of an RTView Proxy Server that returns a simple test cache table as an example.

// Configure the application to make use of the rtview-proxy-server package
// and reference it using the variable name 'rtvproxy'

var rtvproxy = require('rtview-proxy-server')();

// Initialize the Proxy Server by defining caches for foreign data
// NOTE: the dataserver must be running and available when this proxy is started

rtvproxy.create_datacache('SensorData',
    {   // cache properties
        "indexColumnNames" : "ID",
        "historyColumnNames" : "temperature;humidity"
    }, [ // column metadata
        { 'time_stamp': 'date' },
        { "ID" : "string" },
        { "temperature" : "double" },
        { "humidity" : "double" },
        { "temp_unit" : "string"} 
    ]);

// query the remote service for data defined by the cacheName, tableName and query parameters
// This is a VERY simplistic implementation that returns synchronously
// In a real system, the data are returned asynchronously; see other examples

var getData = function (cacheName, tableName, res, query, result, callback) {

    // create an RTView JSON tabular data object based on requested cache and table names
    // by querying the foreign service
    switch(cacheName) {
        case 'SensorData':

            // create an empty array of data rows'
            rtvdata = [];

            // create a data row and add elements, time_stamp first
            row = [];
            row.push(Date.now());
            row.push('Sensor_01');
            row.push(24.57);
            row.push(44.11);
            row.push('°C');
            rtvdata.push(row);

            result.data = rtvdata;
            break;

        default:
            result.data = [];       // no data rows if unknown cache name
    }

    // pass the result back to RTView via the callback
    callback(res, result, query);
}

// Launch the RTView Proxy Server
// Pass in a custom data handler for returning data (a function named getData in this example)

rtvproxy.run(getData);

back to top