BdsApi Documentation

0.0.0

Author:

Dr Terry Barnaby

Version:

0.0.0

Date:

2008-02-04

Introduction

This document covers the BEAM BdsApi software API for the Blacknest Data System. This API provides the ability to access data and adminsiter the BDS system. The API is an object orientated API implemented in 'C++' and PHP with a number of object classes. The API operates over a network type interface using an RPC type mechanism.

The BdsApi API makes use of the BEAM 'C++' class library. The BEAM 'C++' class library provides a small set of low level 'C++' classes for strings, lists and system interface functions. There is some brief information on the BEAM class library later on in this page and a full API definition is available in the libBeam documentation.

Overview

Generally users of the system are only concerned with the DataAccess API.

The BdsApi has been developed using the BOAP (BEAM Object Access Protocol). This provides a simple but powerful Object Orientated RPC mechanism. The BdsApi is written in a high level interface definition language (IDL). The bidl tool generates the client and server side 'C++' and PHP interface and implementation files for the API. These are then provided as a set of 'C++' header files and a binary library file for the clients to link to. The BOAP system employs a simple BOAP name server process that provides a translation between object names and IPAddress/Socket numbers. The BOAP name server runs on the BDS Controller. More information on the BOAP system can be found in the libBeam documentation.

THE BDS API implements a number of data storage classes and three interface objects. The interface objects are:

1. Bds::DataAccess BDS Data API: This will provide read only access to the data and meta data. It will be used by the AutoDRM email and Web systems as well as for program access to the data.
2. Bds::DataAddAccess BDS DataAdd API: This will provide read and restricted write access to enable the adding of data to the system. It will not allow deletions of data to be performed. It is designed to be used by manual and automatic data adding programs.
3. Bds::AdminAccess BDS Admin API: This will provide full read/write access to the data and meta data as well as administrative configuration information.

Examples

There are some examples of client applications using the BdsApi in the bdsExamples directory of the source code. A simple Data Access client example is listed below:

/*******************************************************************************  *      BdsDataClient.cpp       BDS API example code for a Data Client  *                      T.Barnaby,      BEAM Ltd,       2008-03-19  *******************************************************************************  *  *      This is a very basic example of using the BdsApi from a data access  *      perspective. It is designed to give an overview of using the API.  */ #include <iostream> #include <stdio.h> #include <BdsD.h> #include <BdsC.h>  using namespace Bds; using namespace std;   // Function to read some data BError bdsTest(DataAccess& dataAccess){         BError                  err;         DataSelection           dataSelection;         BList<DataInfo>         dataInfoList;         StationInfo             stationInfo;         BArray<UInt8>           formatedData;         Data                    data;                  // Set up selection         stationInfo.name = "EKA";                  dataSelection.networks.append("BKNAS");         dataSelection.stations.append(stationInfo);         dataSelection.timePeriod.startTime = "2000-01-02T10:00:00.345";         dataSelection.timePeriod.endTime = "2000-01-02T11:00:00.345";          // Get list of all data available for the selection                      if(err = dataAccess.searchData(dataSelection, dataInfoList)){                 return err.set(1, BString("Error: Searching for data: ") + err.getString());         }          // We should now choose which set of data we would like from the list, here we just         // choose the first entry and get the data in appropriate format.         if(err = dataAccess.getDataFormated(dataInfoList[0], "IMS1.0", formatedData)){                 return err.set(1, BString("Error: Getting data: ") + err.getString());         }                  // Here we get the data in structued form for further processing         if(err = dataAccess.getData(dataInfoList[0], data)){                 return err.set(1, BString("Error: Getting data: ") + err.getString());         }                  return err; }  int main(int argc, char** argv){         BError                  err;         BString                 host = "localhost";         DataAccess              dataAccess;          if(argc == 2)                 host = argv[1];          // Connect to the DataAccess service         if(err = dataAccess.connectService(BString("//") + host + "/dataAccess")){                 cerr << "Error: " << err.getString() << "\n";                 return 1;         }                  // Run a normal data gathering as a normal data access client would.         if(err = bdsTest(dataAccess)){                   cerr << "Error: " << err.getString() << "\n";                 return 1;         }                          return 0; }