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 highlyfunctional, 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 maincomponents:

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 andtimestamps, 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 theserver, 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 providedby 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 orpartial source frames, depending upon the requested time slice. There are three modes by which a sink can get data froma server:

RequestSubscribe

Monitor

Requests are for a particular time interval, for which there is a single response for each such request. It is also possible tomake 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 serverpasses to the PlugIn any requests for PlugIn channels to the PlugIn sink connection. Upon receipt of a request, a PlugInacts 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, theyare a means of "advertising" available channels. With registered channels, only requests for those specific channels will beforwarded 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 thirdparty 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 supportedvia various higher-level layers, such as via HTTP using the WebTurbine interface. There is also a lurking MS dot-Netinterface 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 itsdocumentation 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 theCOMSOL "javaDeclare" and MANIFEST.MF files.

2 ChannelMap

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

Channels are individually identified and "staged" using the ChannelMap.Add method prior to being transferred (Fetch orFlush). 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-likenaming 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 mayitself 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) isautomatically 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. Forcompatability 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-settingmethod is called again. Thus, you can choose to timestamp data point by point, channel by channel, or frame by framedepending 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 tonever 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.RequestRegistrationfor 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 thecorresponding 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, thisindex can be used as the reference index for use in the PutData method. It is safe to presume this index starts at 0 andincrements 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 (withGetName 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 itwhen 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 ofthe DataTypeCodes. Use the channel index from the associated ChannelMap.Add method, or use the GetIndexmethod.

Note: Mixing different DataTypes in a single channel is not supported, and may cause difficulties for Sink applicationsthat 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 correspondsto one of the DataType Codes. For example, PutDataAsFloat32 lets you directly send a floating point data array withno 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 willbe timestamped accordingly. For example, you can call PutTime once for the whole ChannelMap, in which case all datafor all channels share a common timestamp. Or you can PutTime separately before every PutData call, giving uniquetimestamps 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 localChannelMap. Prior to getting data, the ChannelMap is sent from the RBNB server to the client via the Sink.Fetchmethod.

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 XXXcorresponds to one of the DataType Codes. For example, GetDataAsFloat32 lets you retrieve a floating point dataarray 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 onetime 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 usedto 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 thismethod 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 ofChannelMap.Add is a reliable channel index. For Sinks, you may need to use this method to determine the referenceindex of Fetched channels.

2.6 Channel Trees

The ChannelTree class provides per-node channel hierarchy construction and identification methods. It replaces thedeprecated ChannelList and NodeList methods. It is a client-side layer that provides read-only access to the underlyingChannelMap object.

The ChannelTree has Controller, Server, Source, Plugin, Sink, Folder, Channel, and Empty nodes. Thesecorrespond 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 classencapsulates 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, Stringpassword)

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

Clients optionally provide a userName and password as part of the connection process. If these are defaulted toNULL, 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 ofRBNB 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 methoddisconnects 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 Sourceclients.

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 berepeated as desired:

Define a ChannelMapSet 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 channelindices, 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 referencethe channels by the index returned by ChannelMap.Add. They provide data either as a generic byte-array or as aparticular data type.

PutData may be called multiple times per channel per Flush, building up a many-point-per-channel data frame in apiecemeal manner as may be convenient to the application. The SAPI has internal logic which automatically consolidatesand organizes data into efficient channel map structures. It will always be more effective to handle fewer, larger databuffers, 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 issent as a consolidated RMap with the Flush method.

Each call to Flush involves round-trip network communication, therefore staging larger data frames (with larger buffersand/or multiple calls to PutData) prior to flushing them may provide a significant performance advantage. Of course, youneed 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 aresent 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 defaultsto 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 aloop 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 ChannelMapExtract 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 bycalls 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 thefuture. 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 behinduntil 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 necessaryto 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 abortif 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. ThetimeRef 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 frommidnight, 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 dataretrieved 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 whichhas 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 ofthese 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, durationextends 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 emptyChannelMap.

void RequestRegistration(ChannelMap cmap)

Sends a request to the server for the current registration map for the channels in the specified cmap. The channel mapretrieved 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 PlugInfills 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 forthe 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 beforwarded 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 returnedas 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 thestart/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 simpleexample 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 ofinter-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 andover 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 oneopportunity 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 tofind 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 inthat 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 serverappear 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 aclient 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 isa “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 anRBNB 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 astreaming 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 URLFile 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 customapplications 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 youhave 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 Filemenu, 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 touse 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 APIIt 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.