#

# RBNB DataTurbine

# Software Developer Guide

# V3.0

## February, 2008

# Table of Contents

> 1 Introduction

> > 1.1 Purpose
> > 1.2 Object Overview
> > 1.3 Programming Environments

> 2 ChannelMaps

> > 2.1 Channel Names
> > 2.2 Channel DataTypes
> > 2.3 Channel TimeStamps
> > 2.4 ChannelMap Registration
> > 2.5 ChannelMap Methods
> > 2.6 Channel Trees

> 3 Clients

> > 3.1 Base Client
> > 3.2 Source Client
> > 3.3 Sink Client
> > 3.4 PlugIn Client

> 4 Routing and Mirrors
> 4.1 Mirrors
> 4.2 Routing
> 5 WebTurbine
> 5.1 WebTurbine Introduction
> 5.2 Web URL Access
> 5.3 File System Access
> 5.4 Programmer Interface

# 1 Introduction

This is an update to the older V2 Developer Guide. It trims some deprecated and obsolete material, updates and expands where things have changed (e.g. ChannelTree, PlugInTemplate), and adds new sections for the WebTurbine and Routing capabilities.

## 1. 1 Purpose

This manual provides an overview of the RBNB Application Programming Interface, for historical reasons known as the "Simple API" (SAPI). The SAPI is designed to provide maximum capability with minimum complexity. This document is not a complete reference for all available SAPI methods. For a rigorous reference document, see the associated Javadoc and Doxygen documentation.

The SAPI is implemented as a set of methods on top of the RBNB Java "RMap" or "Full" API, which is what the RBNB server itself is written to. The full RMap API is not supported for open access, but the SAPI is meant to be a highly functional, self contained interface to the RBNB.

## 1.2 Object Overview

There are two main types of objects in the Simple API:

> - `ChannelMap`
> - `Client`

The ChannelMap object organizes data. ChannelMaps are used by RBNB clients to send, request, and retrieve data from an RBNB server.

A Client object can be one of the following sub-classes:

> - `Source`
> - `Sink`
> - `PlugIn`

An RBNB software developer writes RBNB "clients". Clients communicate with an RBNB server to send and retrieve data via ChannelMaps. A Source client sends data to the RBNB Server. A Sink fetches data from an RBNB Server. A PlugIn receives requests (from the server on behalf of a Sink) and responds with data (thus acting like both a Sink and Source).
The following figure illustrates how Source and Sink clients connect to an RBNB server. Overall geometric scalability (MxN) is achieved through a combination of linear (1xM and Nx1) internal objects.
RBNB Achieves Geometric Scalability with Linear Internal Structures

### Channel Map

All RBNB data is organized in "channel maps". RBNB clients manipulate channel maps as a means to make requests (sinks) and submit data (sources). A channel map consists of a collection of channel objects, each with three main components:

Name | Text name e.g. "myChannel"
Data | Binary data of various types
TimeStamp | Monotonically increasing floating point number

A source client builds a channel map consisting of one or more named channels. For each channel it provides data of a specified type and quantity. It also specifies a timestamp for the channel map as a whole, or for the various pieces (channels and data) separately. After being so built, the channel map is sent from the source client to the RBNB server. This process can be repeated, adding new channels or new data to existing channels.

A sink client builds a channel map in order to request data. Here, the channel map consists of named channels and timestamps, which is sent to the RBNB server as a request. The response to this request is another channel map, this time with the data filled in for the various channels.

A "channel tree" is an optional channel map accessory that provides a hiearchical read-only view of a channel map.

### Source Client

Source clients are "active", that is they initiate data transmittal to the server. Each time a source sends some data to the server, it is called a "frame". A source can send a sequence of frames to the server. Each frame can consist of one or more named "channels". Each channel can consist of one or more data points per frame.

Key to the idea of RBNB is that all data has monotonically increasing time-stamps. Timestamps can be per frame, per channel, and/or per data point. Timestamps can be explicit (provided by the source), or implicit (automatically provided by the client API or RBNB server).

### Sink Client

Sink clients are "active", that is they initiate data retrieval from the server. Just as for a source, each time a sink gets frames of data from a server. Each frame consists of one or more named channels, with each channel consisting of one or more data points.

A sink requests data by both channel name(s) and timestamp. The data returned to a sink can consist of multiple or partial source frames, depending upon the requested time slice. There are three modes by which a sink can get data from a server:

> - Request
> - Subscribe
> - Monitor

Requests are for a particular time interval, for which there is a single response for each such request. It is also possible to make a single request that is automatically repeated over a specified number of time intervals.

Subscribe and Monitor modes are open-ended in that new data is automatically sent (from the server to the sink client) as it becomes available. Subscribe mode fetches all data, even if this means falling behind real-time. Monitor mode skips data in order to stay current.

### PlugIn Client

PlugIn clients are "passive sources", that is they appear to other clients as RBNB sources, but wait for data requests before sending data to in response to those requests. PlugIns implement both sink and source connections. The server passes to the PlugIn any requests for PlugIn channels to the PlugIn sink connection. Upon receipt of a request, a PlugIn acts as a source and sends its response to the server, which forwards it to the requesting sink.

A PlugIn optionally registers the specific channels it can provide. Registered channels do not have any data in them, they are a means of "advertising" available channels. With registered channels, only requests for those specific channels will be forwarded by the server to that PlugIn. Otherwise, any request (e.g. "Plugin/anychan") is forwarded to the PlugIn, which can invent channels on-the-fly.

Thus, a PlugIn can provide "services" that can involve fetching and processing other RBNB data on the demand of third party applications. PlugIns can process data from other PlugIns, thus cascading sequences of processing steps.

## 1.3 Programming Environments

Whereas earlier versions of the RBNB flirted with supporting various programming languages and environments, the latest version is focused on Java as the primary programmer API-level interface. Other environments remain supported via various higher-level layers, such as via HTTP using the WebTurbine interface. There is also a lurking MS dot-Net interface via J# in a Java-compatable mode.

### Java

The RBNB server and its API are themselves developed using 100% pure Java. Thus, the core API and its documentation is Java based.

### MATLAB

With Version 6 and later of Matlab, direct calls to Java are supported from the command line mode of Matlab. Thus, Matlab uses the native Java RBNB API directly. Several simple utility M-files are provided as examples.

In order to access the RBNB API from Matlab, you must edit the Matlab classpath.txt file to include the rbnb.jar file.

RBNB also works via the Matlab-compatable COMSOL script environment. To enable this, one must setup the COMSOL "javaDeclare" and MANIFEST.MF files.

# 2 ChannelMap

Clients manipulate data via a "ChannelMap" object. A ChannelMap is comprised of one or more RBNB channels, each consisting of a name, timestamp, and (optional) data.

Channels are individually identified and "staged" using the ChannelMap.Add method prior to being transferred (Fetch or Flush). Behind the scenes, the SAPI incrementally builds up and maintains the underlying "RMap" data structures.

## 2.1 Channel Names

Multi-tiered hierarchical channel structures can be created, requested, and referenced through a simple directory-like naming convention. A fully specified channel name consists of three main parts:

> `Server/Source/Channel`

Where:

> `Server: serverName assigned at Server startup (command line argument)`
> `Source: clientName given by Source via OpenRBNBConnection method`
> `Channel: channelName given by Source via ChannelMap.Add method`

Data Sources define channels (ChannelMap.Add) with the Server and Source parts implied. The channel name part may itself be multi-tiered, such as:

> `Chan0`
> `Test43/C0`
> `Test43/C1`
> `A/B/C`

Data Sinks request channels (ChannelMap.Add) using either relative or absolute (full-path) names. For example:

> `/Server/MySource/Test43/C2 # absolute path`
> `MySource/Test43/C2 # relative path`

Absolute paths start with a slash, and include the top level (parent) server all the way down to the channel name(s). Relative paths do not start with a slash, and begin with a Source name on the local server.

For Sinks, and when requesting a list of available Server channels, wildcards can also be used, as in:

> `MySource/Test/...`
> `*/c0`
> `/Server/*/_Msg/...`

The following Table summarizes the wildcard syntax available to the ChannelMap.Add (Sink-only) and Sink.RequestRegistration methods.

Match String | Description
`"*"` | All objects (servers/sources/channels) at this level (one deep)
`"..."` | All channels this level and down (recursive depth). Must be last part of multi-tiered name.
SAPI Channel Naming Wildcard Notation

## 2.2 Channel DataTypes

ChannelMap Data (PutData) can be specified as a particular primitive data type, per the following table.

DataType Code | Description
`TYPE_FLOAT32` | Single precision (32 bit) floating point number
`TYPE_FLOAT64` | Double precision (64 bit) floating point number
`TYPE_INT8` | 8-bit integer (byte)
`TYPE_INT16` | 16-bit integer (short int)
`TYPE_INT32` | 32-bit integer (int)
`TYPE_INT64` | 64-bit integer (long)
`TYPE_STRING` | Variable length String (character array) object
`TYPE_UNKNOWN` | Unknown or unspecified (byte array)
`TYPE_BYTEARRAY` | Array of arrays of bytes (byte[][])
`TYPE_USER` | User metadata
SAPI DataType Codes

When specifying a primitive DataType with a word length greater than 8 bits (1 byte), the word order (MSB,LSB) is automatically set to match that of the local native CPU upon which the Source application runs.

## 2.3 Channel TimeStamps

A Source sets the timestamp for subsequent data transmittal using either a manual (PutTime) or automatic (PutTimeAuto) method. A timestamp is a monotonically-increasing double-precision number that defines "when" the data occurred. The simplest form of timestamp would be to simply count by whole-numbers, e.g. t=0,1,2,3,...
Default (automatic) timestamp are floating-point number of seconds since 1970, re native Java time or Unix time. For compatability with other applications, it is suggested (but not required) that you adhere to this time-stamping convention.

Each manual timestamp applies to the data specified by one or more subsequent calls to PutData, until a time-setting method is called again. Thus, you can choose to timestamp data point by point, channel by channel, or frame by frame depending on how you interleave your calls to PutTime and PutData.

Automatic time stamps are updated once upon each data Flush. Thus, automatic timestamps are always frame by frame.

Note that RBNB timestamps must monotonically increase. Thus, if you are manually providing timestamps, be sure to never decrease the start time call-to-call.

## 2.4 ChannelMap Registration

When a Source puts ChannelMaps to a server, the channels are automatically registered. See Sink.RequestRegistration for how to get the ChannelMap from which a list of channel strings may be obtained.
A Source or PlugIn can also specifically register its channels, and in so doing add "metadata" (descriptive information) about the channels. That is, the datablock in the registration ChannelMap is descriptive meta-data about the corresponding Source channel. Since the registration information is not part of the ring-buffer, this meta-data is static (i.e. does not change with time, nor does it "drop off" the ring buffer).

## 2.5 ChannelMap Methods

### 2.5.1 Construction

The following ChannelMap methods build, edit and access the list of channels.

#### `int Add(String channelName)`

Each call to ChannelMap.Add builds up the list of channels to be either sent or fetched by the Source or Sink, respectively. ChannelMap.Add returns an index that increments with the number of channels added. For Sources, this index can be used as the reference index for use in the PutData method. It is safe to presume this index starts at 0 and increments by 1 each call to Add with a new or cleared ChannelMap.
For Sinks, it is possible to get more or less channels than you specify (e.g. using wildcards), so you must inquire (with GetName or GetIndex) which channels have been Fetched.

#### `void Clear()`

This method clears out the channel map built by the ChannelMap.Add method, and frees associated memory. Use it when you want to build a new channel map from a "clean slate".

### 2.5.2 Putting Data and Timestamps

The following methods put data in a ChannelMap. These are generally used by Data Sources (and PlugIns).

Note that putting data into a ChannelMap does not send the data to an RBNB server, it builds a local ChannelMap. After building the ChannelMap, it is sent from the client to the RBNB server via the Source.Flush method.

#### `void PutData(int chanIndex, byte[] rawData, int typeID)`

The generic PutData method sets the data to be sent as a byte-array plus an associated `typeID`. The `typeID` is one of the DataTypeCodes. Use the channel index from the associated ChannelMap.Add method, or use the GetIndex method.

Note: Mixing different DataTypes in a single channel is not supported, and may cause difficulties for Sink applications that try to extract mixed-type data.

#### `void PutDataAsXXX(int chanIndex, XXX[] data)`

The family of PutDataAsXXX methods specifies the primitive type of the supplied data array, where XXX corresponds to one of the DataType Codes. For example, PutDataAsFloat32 lets you directly send a floating point data array with no need to first convert it to a byte array. (Overloaded methods are not used to enhance portability of the SAPI).

Note: PutDataAsString puts a single String object, which is considered to be an indivisible data word.

#### `void PutTime(int chanIndex, double start, double duration)`

#### `void PutTimes(double[] times)`

#### `void PutTimeAuto(String timeMode)`

`void PutTimeRef(ChannelMap sourceMap, int channelIndex)`

These methods establish the time-stamping method for the ChannelMap. All PutData calls following a PutTime call will be timestamped accordingly. For example, you can call PutTime once for the whole ChannelMap, in which case all data for all channels share a common timestamp. Or you can PutTime separately before every PutData call, giving unique timestamps to every data point for every channel.

### 2.5.3 Getting Data and Timestamps

The following methods access the data in a ChannelMap. These are generally used by Data Sinks (and PlugIns).

Note that getting data from a ChannelMap does not fetch it from the RBNB server, it extracts it from a local ChannelMap. Prior to getting data, the ChannelMap is sent from the RBNB server to the client via the Sink.Fetch method.

#### `byte[] GetData(int chanIndex)`

This generic extract data method gets data as a byte-array from the ChannelMap.

#### `XXX[] GetDataAsXXX(int chanIndex)`

The family of ChannelAsXXX methods specifies the primitive data type of the returned data array, where XXX corresponds to one of the DataType Codes. For example, GetDataAsFloat32 lets you retrieve a floating point data array with no need to convert it from a byte array. If the fetched data does not match the type, an exception will be thrown. You can check the type using the ChannelType method.

Note: GetDataAsString gets an array of `String` objects, where each `String` is considered to be an indivisible, individually time-stamped, variable-length data word.

#### `double[] GetTimes(chanIndex)`

This method returns an array of double precision RBNB time values for the specified channel index. There will be one time point per data point.If necessary, the point times will be linearly interpolated from the underlying start time and duration of the corresponding data array. See PutTime.

### 2.5.4 DataType Info

These methods provide information about the datatype of a channel.

#### `int GetType(int chanIndex)`

This method returns a DataType Code for the primitive data type of the fetched data for a given channel. It can be used to determine which of the GetDataAsXXX methods to call.

#### `int TypeID(String type)`

#### `String TypeName(int typeID)`

These methods convert the datatype string to numerical constant, and vice versa.
There are several methods to let you inspect and get the names of the channels in a ChannelMap object. The methods are:

#### `String GetName(int index)`

#### ``String[] GetChannelList()``

These utility methods provide means to get the channel name(s) for a given ChannelMap. For Sinks, you can use this method to discover which channels were successfully Fetched.

#### `int GetIndex(String channelName)`

This utility method provides a means to get the channel `index` given the `channelName`. For Sources, the return value of ChannelMap.Add is a reliable channel index. For Sinks, you may need to use this method to determine the reference index of Fetched channels.

## 2.6 Channel Trees

The ChannelTree class provides per-node channel hierarchy construction and identification methods. It replaces the deprecated ChannelList and NodeList methods. It is a client-side layer that provides read-only access to the underlying ChannelMap object.
The ChannelTree has Controller, Server, Source, Plugin, Sink, Folder, Channel, and Empty nodes. These correspond to logical filesystem-like entities rather than a direct correspondence to the ChannelMap object.

#### `ChannelTree createFromChannelMap(ChannelMap cmap)`

Creates a new read-only view of the provided channel map.
See the SAPI Javadoc for additional ChannelTree methods.

# 3 Clients

Clients manipulate ChannelMaps to send and receive data from an RBNB server.

## 3.1 Base Client

The Client class is the base class of all simple clients (Source, Sink, PlugIn) to RBNB servers. The base Client class encapsulates functionality common to all clients.

### 3.1.1 Client Connections

Clients have methods to open and close connections between the client application and an RBNB server.

#### `void OpenRBNBConnection(String serverAddress, String clientName, String userName, String password)`

To open a connection identify the server (`serverAddress`), and identify the client (`clientName`). The `clientName` is used for display in applications such as rbnbAdmin, and provides a handle for other applications to administer and access data from this client.

Clients optionally provide a `userName` and `password` as part of the connection process. If these are defaulted to NULL, there will be no user name by which you can be granted access to restricted data.

Note: `userName` and `password` authorization has limited utility and is only implemented by some clients. The subject of RBNB data access authorization is the subject of other documents.

#### `void CloseRBNBConnection()`

Close the connection with the server, and free up associated resources. The related Source.Detach method disconnects while leaving data intact.

### 3.1.2 Get Server Info

It is possible to get a the name of the connected server, and of yourself (the connected client).

#### `String[] GetServerName()`

#### `String[] GetClientName()`

These methods return the name of the local RBNB server, and the name of the connected client application, respectively.

### 3.1.3 Ring Buffer Properties

#### `SetRingBuffer (int cacheSize, String archiveMode, int archiveSize)`

Clients can set the size of the RBNB server ring buffer associated with its data. Normally, this only applies to Source clients.

The `cacheSize` and `archiveSize` parameters specify the sizes of the RAM and disk ring buffers (in frames), respectively. Each call to "Flush" by a Source constitutes one "frame".

The `archiveMode` parameter has one of the following values:

`"none" -` No archive is to be used (default)
`"load" -` Load the archive that matches this application `clientName`
`"create" -` Create a new archive, delete an existing one if one is present
`"append" -` Add to an existing archive, create a new one if necessary

## 3.2 Source Client

An RBNB data source sends data to and RBNB server. A data Source client has the following tasks, which may be repeated as desired:

> - Define a ChannelMap
> - Set TimeStamp(s)
> - Specify data for channel(s)
> - Flush data to RBNB server

### 3.2.1 Define Channel Map

A Source channel map is defined by calls to the ChannelMap.Add method. This associates channel names with channel indices, which in turn are used for efficient, potentially repeated references in the ChannelMap.PutData method.

### 3.2.2 Time Stamps

ChannelMap timestamps are specified using the ChannelMap.PutTime method(s).

### 3.2.3 Specify Channel Data

The `PutData` methods specify the channel data to send at the next call to the `Flush` method. These methods reference the channels by the index returned by ChannelMap.Add. They provide data either as a generic byte-array or as a particular data type.

PutData may be called multiple times per channel per Flush, building up a many-point-per-channel data frame in a piecemeal manner as may be convenient to the application. The SAPI has internal logic which automatically consolidates and organizes data into efficient channel map structures. It will always be more effective to handle fewer, larger data buffers, however.

### 3.2.4 Flush Data

Once things are set up, send the data to the server.

#### `int Source.Flush(ChannelMap cmap, boolean blockingIO)`

After staging information with the time and data setting methods (i.e. PutTime and PutData), the specified channel map is sent as a consolidated RMap with the Flush method.

Each call to Flush involves round-trip network communication, therefore staging larger data frames (with larger buffers and/or multiple calls to PutData) prior to flushing them may provide a significant performance advantage. Of course, you need to also consider the associated impact on memory use and latency when deciding how often to Flush your data.

If the `blockingIO` parameter is `true`, it will block until the data is sent. If there is no data to send, calling `Flush(cmap,true)` will synchronize your application with the server. It returns the number of channels sent.

Note: Flushing the channel map clears the data. Thus, only new data (via PutData) since the previous call to Flush are sent each time.

### 3.2.5 Source Example Code

The following code opens a connection to a local RBNB server and sends a message string to it. The timestamp defaults to time-of-day in lieu of using the PutTime method.

`// RBNB Developer Guide Simple Source Example
import com.rbnb.sapi.*;
class simpleSource
{
public static void main(String[] arg) throws Exception
{
Source mySource = new Source();
ChannelMap cmap = new ChannelMap();
mySource.OpenRBNBConnection("localhost", "mySource");
cmap.Add("myChan");
cmap.PutDataAsString(0, "Hello World!");
mySource.Flush(cmap, true);
Thread.sleep(5000); // sleep to let data be viewed
mySource.CloseRBNBConnection(); // data goes poof on close
}
}`

Simple Source Example Code

##

The following code is a more complex example, showing how to write sequential data frames for multiple channels in a loop with simply-indexed timestamps.

// RBNB Developer Guide Looping Source Example
import com.rbnb.sapi.*;
class loopSource
{
public static void main(String[] arg) throws Exception
{
int nchan = 3, nframe = 10;
Source mySource = new Source();
ChannelMap cmap = new ChannelMap();
for(int i = 0; i < nchan; ++i) cmap.Add("C"+i);
mySource.OpenRBNBConnection("localhost", "mySource");
for (int j = 0; j < nframe; ++j) {
for (int i = 0; i < nchan; ++i) {
cmap.PutTime((double)i, 0.);
cmap.PutDataAsString(i, "Data for Channel C" + i);
mySource.Flush(cmap, true);
}
}
mySource.Detach(); // data remains after Detach
}
}

Looping Source Example Code

## 3.3 Sink Client

An RBNB data sink fetches data from and RBNB server. A sink client has the following tasks, repeated as desired:

> - Specify request ChannelMap
> - Select sink mode
> - Fetch response ChannelMap
> - Extract data and time from response ChannelMap

### 3.3.1 Request ChannelMap

A Sink clients formulates a request ChannelMap that defines the names and timestamps of the data to be fetched. Channel names are defined by calls to the ChannelMap.Add method, and the associated channel times are defined by calls to the ChannelMap.PutTime method(s).

### 3.3.2 Sink Modes

There are three types of sink data fetch modes:

- `Subscribe -` All new data is to be streamed without gaps
- `Monitor -` "Current" up-to-date live information is to be sent best-effort.
- `Request -` A particular time-slice of data is requested

Each sink fetch mode applies to the group of channels specified by the ChannelMap.

#### `void Subscribe(ChannelMap cmap)`

This is the simplest data fetch mode. It takes a channel map as an argument and returns no value. It initiates a streaming "push" of data (from server to client) for all specified channels starting at the time of this call, and proceeding into the future. A single call to Subscribe can be followed by repeated calls to Fetch, where the next frame of data is received. Note that the frame size is determined by the source application(s).

Subscribe is the most efficient mode in that data frames are streamed from the server without waiting for acknowledgment from the sink client. If the client does not keep up, the data delivered will fall further and further behind until it falls off the beginning (oldest) data in the source ring buffer, at which point the stream aborts.

#### `void Monitor(ChannelMap cmap, int gapControl)`

This provides a variation on the subscribe mode. It initiates a stream of "current" data that will skip-forward as necessary to stay up to date. Full source frames are returned each Fetch. The `gapControl` argument specifies how many frames behind it can get before it will jump ahead (and miss data) in order to stay current.

When Monitor mode keeps up, it is much like Subscribe, except that there is more round-trip traffic between the client and server for Monitor mode (to establish the `gapControl` criterion). Unlike Subscribe mode, the stream will not abort if the client doesn't keep up; but data can be dropped with resulting gaps.

Note: As of the current release, the gapcontrol logic is (still) not fully implemented.

#### `void Request(ChannelMap cmap, double start, double duration, String timeRef)`

The basic Request mode asks for a time-slice of data beginning at `start` and running for a `duration` amount. The `timeRef` argument specifies the time-reference for `start`. The following table summarizes the most commonly used timeRef options. See the Javadoc for a complete reference.

timeRef | Description
"absolute" | Request a `duration` amount of data at a `start` time specified in absolute-seconds from midnight, Jan 1st, 1970 UTC. The data retrieved will be that which has time in the interval: start <= time < (start+duration)
"oldest" | Request a `duration` amount of data where `start` is relative to the oldest available data (beginning of ring-buffer). With a zero start-time, it retrieves the oldest duration of data. In general, the data retrieved will be that which has time in the interval: (oldest+start) <= time < (oldest + start + duration)
"newest" | Request a `duration` amount of most recent data (end of ring-buffer). With a zero start-time, it retrieves the newest duration of data. In general, the data retrieved will be that which has time in the interval: (newest-duration-start) < time <= (newest-start)

Additional timeRef options include "aligned", "after", "modified", "next", "previous". These enable sequences of relative requests moving back and forth in time without overlapping data. Refer to the SAPI Javadoc for detailed description of these advanced options.
Note that both start and duration are always positive numbers. For "absolute" and "oldest" time-references, duration extends to right (future) of the start point. For all the other (e.g. "newest") time-references, duration extends to the left (prior) of the start point. For example, to get the most recent data, use a start of zero: `
`
`sink.Request(cmap, 0, 1, "newest")`

There is always one `Fetch'`d channel map returned for each `Request`, even if this is a NULL map for the cases where there is no data. A NULL map can occur for the "after" or "modified" cases, or when there is simply no data at the requested time.

A duration of zero (0.) is a special case. It retrieves a single point (frame) of data at-or-before the specified time. Note that a non-zero duration can specify an interval that is in-between other data, thus returning an empty ChannelMap.

#### `void RequestRegistration(ChannelMap cmap)`

Sends a request to the server for the current registration map for the channels in the specified cmap. The channel map retrieved via the followup Fetch call can be inspected using the GetChannelList method to get a list of channels and other server objects (sources, sinks). The Registration channel map will contain any source-provided metadata.

### 3.3.3 Fetch Response

After building the ChannelMap and setting the Sink Mode (in that order), get the RBNB data using the Fetch method.

#### `ChannelMap Fetch(boolean blockingIO)`

This method reads the data from the RBNB server for all channels in the current local Channel List (built by ChannelMap.Add). It returns the number of channels retrieved.

If the `blockingIO` parameter is `true`, it will block until the data is retrieved. Otherwise, it will either return a positive integer indicating data was ready and has been read, or a zero (0) indicating no data was yet available.

### 3.3.4 Extract Data

Fetched data is stored the ChannelMap returned by Fetch. Access to the data and time is via the associated ChannelMap.Get methods.

### 3.3.5 Sink Example Code

The following code will fetch the message sent to the local RBNB Server by the earlier Data-Source example.

// RBNB Developer Guide Simple Sink Example
import com.rbnb.sapi.*;
class simpleSink
{
public static void main(String[] arg) throws Exception
{
Sink mySink = new Sink();
mySink.OpenRBNBConnection("localhost", "mySink");
ChannelMap reqmap = new ChannelMap();
reqmap.Add("mySource/myChan");
mySink.Request(reqmap, 0., 0., "newest"); // get most recent data
ChannelMap getmap = mySink.Fetch(1000);
System.out.println(getmap.GetName(0)+": "+getmap.GetDataAsString(0)[0]);
mySink.CloseRBNBConnection();
}
}

Sink Example Code

##

## 3.4 PlugIn Client

An RBNB PlugIn is a special client that connects as a combination source/sink. When a third-party sink requests a channel from the PlugIn, this request (via a ChannelMap object) is sent from the RBNB server to that PlugIn. The PlugIn fills in the answer (puts data) into this request map and returns it, thus dynamically responding to data requests.

A PlugIn client shares the Fetch and Flush methods from the Sink and Source classes, respectively.

#### `void PlugIn.Register(ChannelMap cmap)`

A PlugIn may (optionally) register the channels that it can provide. These channels become part of the ChannelList for the PlugIn, i.e. they are a means of "advertising" available channels.. Data contained in Registered channels are considered metadata.

If any channels are registered by a PlugIn, only requests for those specific channels will be forwarded by the server to that PlugIn. If no channels are registered by a PlugIn, then any requests to that PlugIn (e.g. "Plugin/anychan") will be forwarded to the PlugIn, that must look at the channel name(s) and decided what to do.

### 3.4.1 PlugInChannelMap

A PlugInChannelMap is a dual-purpose object. It is fetched to determine a request, and filled in with data to be returned as a response. It is required that the response ChannelMap is the same object as the fetched (request) ChannelMap, as this ties the response to the request.

PlugIns extend regular ChannelMaps to add a few methods unique to their needs.

#### `double GetRequestStart()`

#### `double GetRequestDuration()`

The request start and duration indicate the time-slice to be processed. By default, these values constitute the start/duration of the response. That is, there is no need to call PutTime on the response map unless the response map time is different than the request map.

#### `String GetRequestReference()`

This method returns the type of request being made. The following correspond to the timeRef argument of the corresponding Sink.Request call:

> `"newest", "oldest", "absolute", "modified", "after"`

The following correspond to Sink.Subscribe and Sink.Monitor data requests, respectively:

> `"subscribe", "monitor"`

Note: "subscribe" and "monitor" modes are not supported for PlugIns, but are implemented for Plugin Templates.

### 3.4.2 PlugIn Example Code

The following PlugIn code echos the name of the requested channel in response to any request.

// RBNB Developer Guide Simple PlugIn Example
import com.rbnb.sapi.*;
class simplePlugIn
{
public static void main(String[] arg) throws Exception
{
PlugIn myPlugIn = new PlugIn();
myPlugIn.OpenRBNBConnection("localhost", "myPlugIn");
while(true) { // run until killed
PlugInChannelMap cmap = myPlugIn.Fetch(1000);
for (int i = 0; i < cmap.NumberOfChannels(); i++) {
String response = new String("Got request for: "+cmap.GetName(i));
cmap.PutDataAsString(i, response);
}
myPlugIn.Flush(cmap);
}
}
}

PlugIn Example Code

### 3.4.3 Plugin Template

The PlugInTemplate class is an abstract base class that simplifies PlugIn development. It automatically provides data-streaming (i.e. subscribe and monitor) support by converting such streams to a sequence of requests that the plugin template developer can handle one-by-one.

#### ``void processRequest(ChannelMap fwdData, PlugInChannelMap out)``

Most plugin implemenations will only need to overload this method in order to have a fully functional plugin.
When a sink requests data from this plugin with follow-on reference to other RBNB data, this data is automatically provided via the fwdData parameter. The method returns its results via the out parameter. The following simple example echoes the name of the requested channel.

// RBNB Developer Guide Simple PlugIn Template Example
import com.rbnb.sapi.*;
class simplePlugInTemplate extends com.rbnb.plugins.PlugInTemplate
{
public simplePlugInTemplate()
{}
protected void processRequest
(ChannelMap fwdData, PlugInChannelMap picm) throws SAPIException
{
// only process first channel
picm.PutDataAsString(0, "Got request to process: "+fwdData.GetName(0));
return;
}
public static void main(String[] arg) throws Exception
{
simplePlugInTemplate myPlugInTemplate = new simplePlugInTemplate();
myPlugInTemplate.start();
}
}

PlugIn Template Example Code

# 4 Routing and Mirrors

RBNB servers can communicate with each other directly to form connected networks of servers. The two main forms of inter-RBNB communication are Routing and Mirrors.

## 4.1 Mirrors

Mirrors "push" data from one data Source to destination, making a copy of the Source on another RBNB server. Thus with a mirror, a copy of the data is automatically sent from the origin-source to the destination-mirror as it arrives.

There are a two kinds of mirrors: a "From" mirror and a "To" mirror. The difference is the side from which the connection is established; after which the data is pushed from source to sink the same as any other mirror.

## 4.2 Routing

Whereas Mirrors connect one Source to another, Routes connect entire servers. Routes or routing "pull" data. Thus with a route, only the registration (channel metadata) is supplied a priori from source to sink; the data is fetched (over and over again) on-demand.

There are various forms of routing. Two types of routing are built into the RBNB server: parent/child and shortcuts.

RBNB Routing: Parent/Child and Shortcuts

### 4.2.1 Parent/Child Routes

Parent/child routes RBNB form a rigid hierarchy with only one "top" parent RBNB. An RBNB server has only one opportunity to establish its parent server at startup. Parent/child routes are always bidirectional; i.e. a parent can see and fetch data from its children and grandchildren, and a child can see and fetch data from its (single) parent, grandparents, cousins, etc.

### 4.2.2 Shortcuts

Shortcuts are on-the-fly routes that can be established (and terminated) after RBNB servers are running. They behave and function much like parent/child routes after they are established, i.e. data is pulled on-demand across them. Shortcuts form no rigid hierarchy - this makes them flexible but lack the simple rules that parent/child routes can use to find data. Shortcuts are also inherently one-way connections.

### 4.2.3 Routing via Plugins

Finally, it is possible to implement routes (and to a lesser extent mirrors) via clients such as plugins. The "robust routing plugin" provided with the RBNB distribution is just one implementation of a routing plugin that tries to be more robust in that it will carefully watch for network disconnects and automatically try to reconnect.

# 5 WebTurbine

## 5.1 WebTurbine Introduction

The WebTurbine interface is tied to the Apache Tomcat web server. It provides a layer that makes an RBNB server appear to be an HTTP web server. There exists URL syntax for putting and getting RBNB channels (one at a time).

### 5.1.1 WebDAV

WebDAV is an extension to the ubiquitous HTTP protocol. WebDAV stands for “Web Document Authoring and Versioning.” With traditional HTTP, a Web server is a read-only device. WebDAV adds protocol commands enabling a client to write content to a Web server, with mechanisms to lock files while they are being accessed/edited. With this write-capability, a WebDAV server becomes a full-featured network file server. Its advantage versus other approaches is its use of the existing Web infrastructure and the widely supported HTTP protocol.

### 5.1.2 WebDAV Enabled RBNB

The RBNB “WebTurbine” adds a web-server layer between the RBNB server and client applications. Specifically, it is a “servlet” that runs under the Apache Tomcat web server.
The popular open-source Apache Tomcat (Java) Web server includes a fully featured WebDAV interface that connects to an RBNB server instead of the traditional local file-set. RBNB data channels can be HTTP URLs and network-mounted WebDAV “files”. Each root-level directory is an RBNB data source, and each “file” below this source is an RBNB channel. This provides a web URL and file-folder interface to the entire contents of the RBNB.

### 5.1.3 URL Syntax

In the tradition of the Web, from a browser or other HTTP application, access to RBNB data channels is via URL of the form:

http://rbnb-host:port/RBNB/rbnb-server/source/channel

Seen as Web objects or files, URLs to RBNB data channels by default reference the most-recent data point of a streaming time-sequence. A “point” is an indivisible data word. For example, it may be an image, a file, or one floating point number from a signal stream. To specify a range of data points over a time interval, you can use a URL “munge” syntax as follows:

- mydata?d=10
- video.jpg?t=360&d=0.2
- chatmsg?t=600&r=newest

In the above examples, “t” refers to time-stamp, “d” to duration of the time-slice, and “r” is an optional reference to oldest or newest time (versus absolute). Concatenate multiple references with the “&” symbol.

Note that although URLs are typically used to get or read data, it is also possible to PUT or POST content to a web server via URL. The RBNB web interface is fully bi-directional. Munging the timestamp on a write specifies the time of the data being written. By default, data writes are automatically time-stamped with current time-of-day.

A complete reference to the WebDAV options is bundled with the RBNB DataTurbine software release.

### 5.1.4 Interface Options

There are several ways in which applications can access the WebDAV-enabled WebTurbine system:

- Web URL
- File System
- Programmer

Each of these goes through the rbnbDAV server, using the HTTP/WebDAV protocol. These are each described in turn in the following sections.

## 5.2 Web URL Access

Launched as a Web server “servlet,” all RBNB content may be accessed via URL references. For example, through a link such as http://localhost/RBNB, you may peruse live current content via your browser or any other application that can open Web URLs.

WebTurbine Browser Interface

The RBNB Web interface operates as a WebDAV server, so you can even write content to the RBNB using this means. Many applications (such as Microsoft Office) are “WebDAV enabled,” and it is easy to write custom applications that use this bidirectional read/write interface.

Once you have launched the WebTurbine and RBNB servers, you can point your browser at the WebTurbine servlet-root at “/RBNB” below your Web server home URL. For example, if you are running the Tomcat web server at localhost:8080, and an RBNB server with name Server, the URL to the root directory to the RBNB data channels would be:

http://localhost:8080/RBNB

Below this point appears what looks like a file system consisting of the various RBNB data sources and channels. If you have routed RBNB servers together, you can continue down this hierarchy to access content from remotely routed RBNBs.

## 5.3 File System Access

RBNB file system mapping is accomplished via built-in WebDAV support in Windows XP, Mac OS X, Mandrake Linux, and several other systems and third party packages. Many WebDAV file system clients provide full access to any application that can read and write files.

### 5.3.1 File Explorer Interface

The RBNB server can be mapped as a network drive, giving you a familiar file-folder interface to RBNB dynamic data files. An easy way to do this is as a WebFolder via Microsoft Internet Explorer. Simply Open... under the IE File menu, enter the RBNB server site (e.g., http://localhost/RBNB), and check the Open as WebFolder box. The resulting folder window lets you browse and read content across a network of routed RBNB servers.

WebTurbine File Explorer Interface

Windows also (sometimes) works using the "Map Network Drive" feature pointing to the WebTurbine servlet URL, e.g. http://localhost/RBNB. Other operating systems also provide WebDAV file-system support. On the Mac OS X, use the top-panel Go/Connect to Server interface. On Linux, use the "dav2fs" utility.

### 5.3.2 Shell Interface

This syntax can be used by shell commands, as part of Web URLs, and in any programming language that supports simple file I/O. The following illustrates RBNB dynamic file access via Unix shell commands:

$ cd /mnt/RBNB/rbnbSource % change to rbnbDAV source folder
$ cp c0 /usr/mjm/mycopy % grab most recent data (default)
$ cat c0@t=4&d=1 % type data at time=4, duration=1
$ cd /mnt/RBNB % change to rbnbDAV server root folder
$ mkdir myStuff % create a new RBNB source (RBO)
$ cp /usr/mjm/foo myStuff % put data channel “foo” (at default TOD)
$ echo “hi” > myStuff/c0@t=47 % put message in at time=47

Equivalent functions are available from other operating systems, such as the Windows command prompt.

Note that the '@' symbol is an optional substitute for the '?' munge character; this helps when '?' is a shell wildcard.

### 5.3.3 File I/O Interface

Any software program can access RBNB data as if it were a file. The following “C” code is a simple example of an RBNB data source. Note that no RBNB-specific API or libraries are used. All that is necessary is for the “rbnbDAV” server to be mounted as a local file system using standard OS-vendor utilities or open-source libraries.

// Simple “C” Example of RBNB Data Source using rbnbDAV #include <stdio.h> main() { char dbuf[256]; FILE *fp = fopen(“myChan@t=3”,“w”); // open channel printf(“Enter:”); fgets(dbuf, 256, stdin); // get user message fwrite(dbuf, 1, strlen(dbuf), fp); // write it to RBNB }

An RBNB data sink to read this source (located far away across a network of servers) could simply open this same “file” for read access.

## 5.4 Programmer Interface

It is possible to write programs which open, read, and write via HTTP connections. With this approach, it is possible to use the Web interface in lieu of the standard RBNB Java API libraries for programmatic access to RBNB data. This has several advantages:

- It requires no special RBNB libraries or code at the client side
- It is arguably simpler than the standard RBNB Java API
- It is portable to programming languages other than Java

For the Java programmer, this approach has the disadvantages:

- Somewhat restricted supported features (e.g. no subscribe-mode, one channel at a time)
- It requires a WebTurbine/WebDAV server to be running
- Performance is less optimal due to the additional data-hop and software layer

The syntax for how to program HTTP I/O is beyond the scope of this document.

###