The API is contained withing a shared library StDbLib.so. It has two versions built from a common source. The version in Offline (under $STAR/lib) contains additional code generated by "rootcint" preprocessor in order to provide command line access to some methods. The Online version does not contain the preprocessed "rootcint" code.

In addition to standard access methods, the API provides the tools needed to facilitate those non-standard access patterns that are known to exist. For example, there will be tasks that need special SQL syntax to be supplied by client codes. Here, a general use C++MySQL object can be made available to the user code on an as needed basis.

The following write-up is intended as a starting point for understanding the C++ API components. Since most clients of database data have an additional software-layer between their codes and the DB-API (e.g St_db_Maker in offline), none of these components will be directly seen by the majority of such users. There will, however, be a number of clients which will need to access the API directly in order to perform some unique database Read/Write tasks.

Click here To view a block diagram of how the C++ API fits general STAR code access.

Click here To view a block diagram of how the C++ API classes work together to provide data to client codes

The main classes which make up the C++ DB-API are divided here into four categories.

• Access Classes
• Data Classes
• MySQL Utilities
• Helper Utilities

The StDbManager class acts as the principle connection between the DB-API and the client codes. It is a singleton class that is responcible for finding Servers & databases, providing the information to the StDbServer class in order that it may connect with the database requested, and forwarding all subsequent (R/W) requests on to the appropriate StDbServer object.

Some public methods that are important to using the DB-API via the manager:

 

// Obtain an instance of this singleton object

static StDbManager* Instance();

 

// set timestamp for requesting & storing data. see Time Stamp for timestamp format information

virtual void setRequestTime(unsigned int time);

virtual void setRequestTime(const char* time);

virtual void setStoreTime(unsigned int time);

virtual void setStoreTime(const char* time);

 

 

// Request-&-Store data contained in StDbTable Object

virtual void fetchDbTable(StDbTableI* table);

virtual void storeDbTable(StDbTableI* table);

 

 

 

// Request-&-Store data list of data contained in StDbConfigNode Object

virtual StDbConfigNode* initConfig(const char* configName);

virtual StDbConfigNode* initConfig(StDbType type, StDbDomain domain, const char* configName=0);

virtual void storeAllTables(StDbConfigNode* node);

 

Some public methods that are primarily used internally in the DB-API:

 

 

// Server Locators By Db-Type, Db-Domain, or "default"

virtual StDbServer* findServer(StDbType type, StDbDomain domain);

virtual StDbServer* findDefaultServer();

StDbServer:

The StDbServer class acts as the contact between the StDbManager and the specific Server-&-Database in which a requested data resides. It is initialized by the StDbManager with all the information needed to connect to the database and it contains an SQL-QueryObject that is specifically structured to navigate the database requested. It is NOT really a user object except in specific situations that require access to a real SQL-interface object which can be retrieved via this object.

Public methods accessed from the StDbManager and forwarded to the SQL-Query Object:

 

 

// Query-DataBase for information via StDbTable and StDbConfigNode Objects

virtual void QueryDb(StDbTable* table, unsigned int reqTime);

virtual void QueryDb(StDbConfigNode* node);

virtual void QueryDescriptor(StDbTable* table);

virtual void WriteDb(StDbTable* table, unsigned int storeTime);

tableQuery & mysqlAccessor:

The tableQuery object is an interface of database queries while mysqlAccessor object is a real implementation based on access to MYSQL. The real methods in mysqlAccessor are those that contain the specific SQL content needed to navigate the database structures.

Public methods passed from StDbServer :

 

 

// Query-DataBase for information via StDbTable and StDbConfigNode Objects

virtual int QueryDb(StDbTable* table, unsigned int reqTime) = 0;

virtual int WriteDb(StDbTable* table, unsigned int storeTime) = 0;

virtual int QueryDb(StDbConfigNode* node) = 0;

virtual int QueryDescriptor(StDbTable* table) = 0;

StDbDefs:

Not a class but a header file containing enumerations of StDbType and StDbDomain that are used to make contact to specific databases. Use of such enumerations may disappear in favor of a string lookup but the simple restricted set is good for the initial implementation.

The StDbTable class contains all the information needed to access a specific table in the database. Specifically, it contains the "address" of the table in the database (name, version, validity-time, ...), the "descriptor" of the c-struct use to fill the memory, the void* to the memory, the number of rows, and whether the data can be retrieved without time-stamp ("BaseLine" attribute).

Any initial request for a table, either in an ensemble list or one-by-one, sets up the StDbTable class instance for the future data request without actually retrieving any data. Rather the database-name, table-name, version-name, and perhaps number of rows & id for each row, are assigned either by the ensemble query via the StDbConfigNode or simply by a single request. In addition, an "descriptor" object can also be requested from the database or set from the client code. After this initial "request", the table can be used with the StDbManager's timestamp information to read/write data from/to the database. if no "descriptor" is in the StDbTable class, the database provides one (the most recent one loaded in the database) upon the first real data access attempted.

Some usefull public methods in StDbTable

 

// Accessors for the MetaData

virtual StDbAccessor getAccessor() const ; // c-struct containing metadata

virtual void setAccessor(StDbAccessor a) ; // c-struct containing metadata

 

// meta data - item by item

virtual char* getTableName() const;

virtual void setTableName(const char* name);

virtual char* getVersion() const ;

virtual void setVersion(char* version) ;

// Note multiple TimeStamp formats

virtual char* getBeginDateTime();

virtual unsigned int getBeginTime() const ;

virtual void setBeginTime(unsigned int time) ;

virtual void setBeginTime(const char* time);

virtual unsigned int getEndTime() const ;

virtual char* getEndDateTime();

virtual void setEndTime(unsigned int time);

virtual void setEndTime(const char* time);

 

// Characteristics of the Data

virtual bool isBaseLine() const;

virtual void setIsBaseLine(bool baseline);

virtual unsigned int getTableSize() const;

virtual StTableDescriptorI* getDescriptorCpy() const;

virtual void setDescriptor(StTableDescriptorI* descriptor);

virtual int* getElementID() const ;

virtual void setElementID(int* elements, int nrows=1) ;

 

// Accessors for the Table & Data

virtual StDbTableI* Clone();

virtual char* GetTable();

virtual void* GetTableCpy();

virtual void SetTable(char* data, int nrows);

virtual void AddRows(char* data, int nrows);

virtual int GetNRows() const;

virtual void SetNRows(int nrows);

StDbConfigNode: (Available at Root CLI)

The StDbConfigNode class provides 2 functions to the C++ API.

The first is as a container for a list of StDbTable objects over which codes can iterate. In fact, the StDbTable constructor need not be called directly in the user codes as the StDbConfigNode class has a method to construct the StDbTable object, add it to its list, and return to the user a pointer to the StDbTable object created. The destructor of the StDbConfigNode will delete all tables within its list.

The second is the management of ensembles of data (StDbTables) in a list structure for creation (via a database configuration request) and update. The StDbConfigNode can build itself from the database and a single "Key" (version string). The result such a "ConfigNode" query will be several lists of StDbTables prepared with the necessary database addresses of name, version, & elementID as well as any characteristic information such as the "descriptor" and the baseline attribute.

Some usefull public methods in StDbConfigNode

 

// Keys for database access: ConfigName=Key

virtual void setConfigName(const char* name);

virtual char* getConfigName() const ;

virtual void setDbType(StDbType type);

virtual StDbType getDbType() const ;

virtual void setDbDomain(StDbDomain domain) ;

virtual StDbDomain getDbDomain() const;

 

// Compliance/Awareness with "Document Object Model" web standard

virtual void setNextNode(StDbConfigNode* node) ;

virtual void setParentNode(StDbConfigNode* node);

virtual void setFirstChildNode(StDbConfigNode* node);

virtual void appendNode(StDbConfigNode* node);

virtual StDbConfigNode* getNextNode() const ;

virtual StDbConfigNode* getParentNode() const ;

virtual StDbConfigNode* getFirstChildNode() const ;

 

// Access to datatables

virtual StDbTable* addDbTable(const char* tableName, char* version="default", bool isBaseLine = false);

virtual StDbTable* addTable(const char* tableName, char* version="default", bool isBaseLine = false);

virtual void removeTable(StDbTable* table);

virtual TableIter* getTableIter();