Simple Application Programming Interface (SAPI)

Introduction

The Simple Application Programming Interface (SAPI) allows the end user straightward methods for interacting with the guts of DataTurbine.

The SAPI JavaDoc is included with the full OSDT Installation.

Components

Control: Controls RBNB server behavior.
ChannelMap: Fixture that contains a list of channels, each of which contains data.
Source: Generates and sends data to the RBNB DataTurbine server
Sink: Makes requests for data from the RBNB DataTurbine server
Plugin: Accepts requests for data from a sink via the RBNB DataTurbine server and returns the requested data

 

Control

Used to control the server and set up mirrors.

  1. First construct a control object
  2. Connect to the DataTurbine server you wish to control
  3. Evoke one of the many methods of the control object (eg: mirroring, access control, etc…)
  4. Disconnect from the server
1
2
3
4
5
6
Control cont = new Control();
cont.OpenRBNBConnection("localhost:3333","tempConnection”);
//Series of methods evoked on the Control object
cont.CloseRBNBConnection();

ChannelMap

The channel map is a construct that stores data associated with channels. It is used by sources and sinks to send and receive data..

  1. When constructing a channel map to send data:
    1. Construct a channel map object
    2. Add channel by name, it will return a numeric ID
    3. Put a MIME type for the channel
    4. Put timestamp for the data point
    5. Put data into the source by calling the appropriate put method and specifying the numeric id
    1
    2
    3
    4
    5
    ChannelMap sMap = new ChannelMap();
    sMap.Add("HelloWorld");
    sMap.PutMime(0,"application/octet-stream");
    sMap.PutTimeAuto("timeofday");
    sMap.PutDataAsString(0,inStr);
  2. When constructing a channel map to request data:
    1. Construct a channel map object
    2. Add channel by name, making sure to include the name of the source, store the returned id
    1
    2
    ChannelMap rMap = new ChannelMap();
    rMap.Add("HelloWorldSource/HelloWorld");
  3. When receiving data from a channel map:
    1. Receive a channel map object from a sink
    2. Retrieve data from the channel map specifying the same id as the channel map request
    1
    2
    ChannelMap aMap = sink.Fetch(-1);
    aMap.GetDataAsString(0)[0];

Source

A source sends data into DataTurbine. It also manages a connection to the DataTurbine server. It send data to the server when the flush method is called.

1
2
3
4
5
6
7
8
9
Source source = new Source();
source.OpenRBNBConnection("localhost:3333","HelloWorld");
//Create a channel map called sMap
//Place Data into the channel map
source.Flush(sMap);
source.CloseRBNBConnection();

Sink

A sink receives data from a DataTurbine server. It also manages a connection to the DataTurbine server.

  1. Construct a sink object
  2. Connect to a server
  3. Set up a request on what data this sink should fetch.
  4. Send series of fetch requests to the source that retrieve the data
  5. Close connection to the sink
1
2
3
4
5
6
7
8
9
Sink sink=new Sink();
sink.OpenRBNBConnection();
//Create a channel map called rMap
sink.Request(rMap,-10.0,20.0,"newest");
ChannelMap aMap = sink.Fetch(-1);
sink.CloseRBNBConnection();

Plugin

A plugin responds to requests made by sink and provides data.

It has the following set of responsibilities:

  1. Build the list of channels to which this PlugIn responds with ChannelMap.Add(String) and Register(ChannelMap). This step may be omitted, in which case all channels which request from this PlugIn’s name will be forwarded by the server.
  2. Fetch(long,PlugInChannelMap) requests from the RBNB server.
  3. The PlugInChannelMap will be filled with the channels requested by the client, as well as the request mode and time range. These can be determined using PlugInChannelMap.GetRequestStart()PlugInChannelMap.GetRequestDuration(), and PlugInChannelMap.GetRequestReference(). This last method may return “registration”, in which case the registered channels should be returned, with any matching meta-data.
  4. By default, the time-range requested will be used for the output, although this may be overridden by PutTime(). Push data into the map to fulfill the request using the PutData() methods.
  5. When all channels have been set, Flush(PlugInChannelMap) the response to the server.
  6. Repeat steps 2 through 4 indefinitely. For some applications, it will be necessary to spawn a new thread in step 2 to handle each new request. It should NOT be necessary to synchronize on the PlugIn object, as it can Fetch and Flush simultaneously; however, a new PlugInChannelMap object should be created before returning to step 2.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
class MyPlugIn extends com.rbnb.plugins.PlugInTemplate {
    public MyPlugIn() {
        // If this is not a 'filter' plugin, set to false:
        setForwardRequests(false);
        // Consider using this method to help with multithreading access control.
        // One instance of the helper class will be created per thread.
        setUserRequestClass(MyPlugInHelperClass.class);
    }
    protected void processRequest(ChannelMap fwdData, PlugInChannelMap in_out) {
        // If this is not a 'filter' plugin, fwdData is empty.
        for (int ii = 0; ii < in_out.NumberOfChannels(); ++ii) {
            // Put data into in_out as appropriate:
        }
    }
    protected void processRegistrationRequest(ChannelMap fwdData, PlugInChannelMap in_out){
    //similar to process request
    }
    public static class MyPlugInHelperClass {
        public Connection conn; // maybe stores a database connection object
    }
  
}
Open Source DataTurbine Initiative © 2016 Frontier Theme