an abstract class from which database queries may be launched. More...

#include <carma/dbms/DBConnection.h>

Inheritance diagram for carma::dbms::DBConnection:

Public Types
typedef std::map< std::string, std::string >	file2TableMap
	type to map data file names to tables they should be loaded into More...

Public Member Functions
virtual void	beginTransaction () const
	begin a transaction More...

virtual std::string	caseSensitiveSearchModifier () const
	get the modifier necessary for a case-sensitive text search More...

void	closeConnection ()
	close the ODBC database connection More...

virtual void	commitTransaction () const
	commit a transaction More...

virtual std::string	createMonitorDataTable (const MonitorAverageType &averageType, const MonitorAggregateType &aggType, const std::string &tag, const std::string *const location=NULL) const =0
	create a monitor data table More...

carma::dbms::Table	databaseInfo (const std::string &database="") const
	get info on the database More...

std::string	dataSource () const
	is this object using the production database? More...

virtual void	deleteFromMonitorIndexTable (const std::string &whereClause) const
	delete rows from the MONITOR_INDEX_TABLE More...

virtual void	dropScratchTable (const std::string &table) const
	drop a table from the scratch database More...

virtual void	execSQLDropTable (const std::string &tableName) const
	drop a table. More...

virtual carma::dbms::Table	execSQLSelect (const std::string &statement, const std::string &resultTableName="RESULT TABLE") const
	execute a SELECT query More...

virtual carma::dbms::Table	execSQLSelect (const std::vector< std::string > &columnNames, const std::string &tableName, const std::string &whereClause="", const std::string &orderByClause="", const std::string &groupByClause="", const std::string &havingClause="", const std::string &resultTableName="RESULT TABLE") const
	execute a SELECT query More...

virtual void *	getAggregate (const std::string &column, const std::string &table, const std::string &function, carma::dbms::Table::ColumnType &type) const
	get the specified aggregate value of the specified column from the specified table. More...

Table	getLogMessages (const carma::util::frameType &start, const carma::util::frameType &end=carma::util::Time::computeCurrentFrame(), const std::string *matchString=NULL) const
	get the log messages in the specified frameCount range. More...

virtual long	getRowCount (const std::string &tableName) const
	get the number of rows in the specified table More...

void	insertLogMessage (const std::string &message, const carma::util::frameType &frameCount=carma::util::Time::computeCurrentFrame()) const
	add a log message to the Log table More...

virtual bool	inTransaction () const
	is a transaction being executed? More...

virtual bool	isDBUp ()
	is the RDBMS in question up and accepting connections More...

virtual void	loadDataFromFile (const std::string &filename, const std::string &table, const bool &useTransactions, const int &linesToIgnore=0, const std::string &columnDelimiter="\t") const =0
	load data into a table from a disk file. More...

virtual void	loadDataFromFiles (const file2TableMap &file2Table, const bool &useTransactions, const int &linesToIgnore=0, const std::string &columnDelimiter="\t") const =0
	load data into tables from disk files. More...

virtual unsigned	maxColumnsPerTable () const =0
	the maximum number of columns the RDBMS allows in a table More...

virtual unsigned	maxTablesPerJoin () const =0
	the maximum number of tables the RDBMS allows in a join More...

virtual void	monitorDataTableHasBeenPopulated (const std::string &tableName, const MonitorAverageType &averageType) const
	performs tasks after a monitor data table has been completely populated. More...

void	odbcInfo () const
	print various details about ODBC support More...

std::string	rdbmsName () const
	get the name of the RDBMS associated with this object More...

virtual void	repairMonitorDataTable (const std::string &tableName) const =0
	attempt to repair a corrupt monitor data table More...

virtual void	rollBackTransaction () const
	rollback a transaction More...

bool	tableExists (const std::string &table, const std::string &database) const
	does the specified table exist in the specified database? More...

virtual	~DBConnection ()
	destructor, derived classes may want to override More...

Static Public Member Functions
static std::string	createInsertStatement (const std::string &tableName, const std::vector< std::string > columns, const std::vector< std::string > values)
	create an SQL insert statement More...

static std::string	createInsertStatement (const std::string &tableName, const std::vector< std::string > columns, const std::string values)
	create an SQL insert statement `"INSERT INTO " + tableName + "("` More...

static std::string	createJoinClause (const std::string &leftTable, const std::string &rightTable, const std::string &leftColumn, const std::string &rightColumn="", const std::string &rightTableAlias="", const std::string &indexCol="")
	create a (inner) join clause More...

static std::string	createJoinClause (const std::string &joinTable, const std::string &onClause)
	create a (inner) join clause More...

static bool	isUp (const DBConfigurator *dbconf=NULL)
	is the database specified by the dbconf object up and accepting connections? More...

Protected Member Functions
void	closeODBCConnection_ ()
	close a database connection using ODBC, `henv_` and `hdbc_ are freed here` More...

void	closeODBCConnection_ (SQLHENV henv, SQLHDBC hdbc) const

	DBConnection (const carma::dbms::DBConfigurator *dbconf)
	create a DBConnection object. More...

void	directSQLExec_ (const SQLHSTMT hstmt, const std::string &statement) const
	execute a single SQL statement More...

void	directSQLExec_ (const std::string &statement) const
	execute a single SQL statement directly More...

void	directSQLInsert_ (const std::string &statement) const
	perform a single sql insert statement directly (ie, no prepared statements More...

void	freeSQLStatement_ (const SQLHSTMT &hstmt) const
	free an ODBC statment handle More...

carma::dbms::Table	odbcResultSetToTable_ (const SQLHSTMT &hstmt) const
	convert an ODBC result set to a carma::dbms::Table object More...

void	openODBCConnection_ (SQLHENV henv, SQLHDBC hdbc)
	open a database connection using ODBC, `henv_` and `hdbc_ are initialized here` More...

void	openODBCConnection_ ()

std::string	readPassword_ () const
	read the database user's password so that it can be sent to the ODBC driver as part of the connect string IMPORTANT! Passwords are considered sensitive information and so the files in which they reside should be readable only by the unix account which owns them More...

Protected Attributes
std::vector< SQLHSTMT >	activeStatements

std::string	dataSource_

std::string	dbname_

std::string	dbuser_

SQLHDBC	hdbc_
	connection and environment handles for ODBC interface More...

SQLHENV	henv_

bool	inTxn_

log4cpp::Category &	logger_

std::string	odbcConnectString_

std::string	odbcini_
	odbc config file More...

std::string	passwordFile_

unsigned	port_

std::string	rdbmsName_

std::string	socket_

Friends
class	DBConnectionTest

class	LogDatabase

class	MonitorConfigurationDatabase

class	MonitorDataDatabase

class	MonitorDataQueryManager

Detailed Description

an abstract class from which database queries may be launched.

To obtain an object, Objects of this class are created via DBConnectionFactory::createConnection(). DBConnection objects use configuration information contained in a DBConfiguration object which is passed to DBConnectionFactory::createConnection(). Configuration parameters used by DBConnection objects are dbname, the database name to which to connect (e.g,. carma) user, the user to connect as (e.g., mld) passwordFile, the file from which to read the dbuser's password (this file only be readable by the unix user!) odbcini, the file from which to obtain ODBC configuration information

Definition at line 46 of file DBConnection.h.

Member Typedef Documentation

typedef std::map<std::string, std::string> carma::dbms::DBConnection::file2TableMap

type to map data file names to tables they should be loaded into

Definition at line 58 of file DBConnection.h.

Constructor & Destructor Documentation

virtual carma::dbms::DBConnection::~DBConnection ( )

virtual

destructor, derived classes may want to override

carma::dbms::DBConnection::DBConnection ( const carma::dbms::DBConfigurator * dbconf )

protected

create a DBConnection object.

This constructor does not actually establish a database connection; derived class constructors are responsible for doing that by calling e.g. createODBCConnection() within their constructors

Parameters

dbconf the DBConfigurator object containing configuration info used by this object, if NULL use sensible defaults

See Also: DBConnectionFactory::createConnection

Member Function Documentation

virtual void carma::dbms::DBConnection::beginTransaction ( ) const

virtual

begin a transaction

Exceptions

DBConnectionException

Reimplemented in carma::dbms::PostgresDBConnection, and carma::dbms::MySQLDBConnection.

virtual std::string carma::dbms::DBConnection::caseSensitiveSearchModifier ( ) const

virtual

get the modifier necessary for a case-sensitive text search

Returns: the modifier necessary for a case-sensitive text search

Reimplemented in carma::dbms::MySQLDBConnection.

Definition at line 412 of file DBConnection.h.

void carma::dbms::DBConnection::closeConnection ( )

close the ODBC database connection

void carma::dbms::DBConnection::closeODBCConnection_ ( )

protected

close a database connection using ODBC, henv_ and hdbc_ are freed here

virtual void carma::dbms::DBConnection::commitTransaction ( ) const

virtual

commit a transaction

Exceptions

DBConnectionException

Reimplemented in carma::dbms::PostgresDBConnection, and carma::dbms::MySQLDBConnection.

static std::string carma::dbms::DBConnection::createInsertStatement	(	const std::string &	tableName,
		const std::vector< std::string >	columns,
		const std::vector< std::string >	values
	)

static

create an SQL insert statement

Parameters

table	the table into which to insert a new record
columns	the columns to which the values correspond
values	the values to insert (converted to strings)

static std::string carma::dbms::DBConnection::createInsertStatement	(	const std::string &	tableName,
		const std::vector< std::string >	columns,
		const std::string	values
	)

static

create an SQL insert statement "INSERT INTO " + tableName + "("

carma::util::vectorToString(columns) + ") VALUES (" + values + ")"
Parameters

table the table into which to insert a new record

columns the columns to which the values correspond

values the stringified version of values to insert

static std::string carma::dbms::DBConnection::createJoinClause	(	const std::string &	leftTable,
		const std::string &	rightTable,
		const std::string &	leftColumn,
		const std::string &	rightColumn = `""`,
		const std::string &	rightTableAlias = `""`,
		const std::string &	indexCol = `""`
	)

static

create a (inner) join clause

Parameters

leftTable	the left table in the join, if this table is to have an alias, the alias should be used in place of the table name
rightTable	the (right) table to join
leftColumn	the left table column to join on
rightColumn	the right table join column, if blank (the default), the columns to join in the two tables have the same name
the	alias for the right table, if any
indexCol	MySQL specific Add a USE INDEX(`indexCol`) clause to the table reference if not "".

Returns: the JOIN clause

static std::string carma::dbms::DBConnection::createJoinClause	(	const std::string &	joinTable,
		const std::string &	onClause
	)

static

create a (inner) join clause

Parameters

joinTable	the (right) table to join
onClause	the ON clause describing how the tables should be joined

Returns: the JOIN clause

virtual std::string carma::dbms::DBConnection::createMonitorDataTable	(	const MonitorAverageType &	averageType,
		const MonitorAggregateType &	aggType,
		const std::string &	tag,
		const std::string *const	location = `NULL`
	)		const

pure virtual

create a monitor data table

Parameters

averageType	the average type of the table
dataType	the data type of the table
tag	the tag to be appended to the table name
location	location (directory) at which to create the table, if NULL, use the default location determined by the RDBMS

Returns: the name of the created table

Exceptions

DBConnecitonException

Implemented in carma::dbms::MySQLDBConnection.

carma::dbms::Table carma::dbms::DBConnection::databaseInfo ( const std::string & database = "" ) const

get info on the database

Parameters

database database for which to get info ""=>current database

Returns: Table containing database info

std::string carma::dbms::DBConnection::dataSource ( ) const

is this object using the production database?

Returns: if this object using the production database get the data source string used for an ODBC connection; the datasource string

Definition at line 105 of file DBConnection.h.

virtual void carma::dbms::DBConnection::deleteFromMonitorIndexTable ( const std::string & whereClause ) const

virtual

delete rows from the MONITOR_INDEX_TABLE

Parameters

whereClause the where clause specifying which rows should be deleted

Exceptions

DBConnecitonException

void carma::dbms::DBConnection::directSQLExec_	(	const SQLHSTMT	hstmt,
		const std::string &	statement
	)		const

protected

execute a single SQL statement

Parameters

hstmt	the previously allocated ODBC statement
statement	the SQL statement to execute

Returns: the result of the ODBC directExec function call

void carma::dbms::DBConnection::directSQLExec_ ( const std::string & statement ) const

protected

execute a single SQL statement directly

Parameters

statement the SQL statement to execute

Returns: the result of the ODBC directExec function call

void carma::dbms::DBConnection::directSQLInsert_ ( const std::string & statement ) const

protected

perform a single sql insert statement directly (ie, no prepared statements

Parameters

statement SQL statment to execute

Exceptions

DBConnection exception

virtual void carma::dbms::DBConnection::dropScratchTable ( const std::string & table ) const

virtual

drop a table from the scratch database

Parameters

table the table to drop

virtual void carma::dbms::DBConnection::execSQLDropTable ( const std::string & tableName ) const

virtual

drop a table.

Only volatile tables (monitor data, log) are permitted to be dropped via this interface

Parameters

tableName the table to be dropped

Exceptions

DBConnectionException

virtual carma::dbms::Table carma::dbms::DBConnection::execSQLSelect	(	const std::string &	statement,
		const std::string &	resultTableName = `"RESULT TABLE"`
	)		const

virtual

execute a SELECT query

Parameters

statement	the SELECT query to execute
resultTableName	the name of the results table

Returns: a Table containing the results of the query

Exceptions

DBConnectionException

virtual carma::dbms::Table carma::dbms::DBConnection::execSQLSelect	(	const std::vector< std::string > &	columnNames,
		const std::string &	tableName,
		const std::string &	whereClause = `""`,
		const std::string &	orderByClause = `""`,
		const std::string &	groupByClause = `""`,
		const std::string &	havingClause = `""`,
		const std::string &	resultTableName = `"RESULT TABLE"`
	)		const

virtual

execute a SELECT query

Parameters

columnNames	list of column names to be returned in the results table
tableName	table to execute the query on
whereClase	the SQL WHERE clause ("" => no WHERE clause)
orderByClause	the SQL ORDER BY clause ("" => no ORDER BY clause)
groupByClause	the SQL GROUP BY clause ("" => no GROUP BY clause)
havingClause	the SQL HAVING clause ("" => no HAVING clause)
resultTableName	the name of the results table

Returns: a Table containing the results of the query

Exceptions

DBConnectionException

void carma::dbms::DBConnection::freeSQLStatement_ ( const SQLHSTMT & hstmt ) const

protected

free an ODBC statment handle

Parameters

hstmt the ODBC statement handle

virtual void* carma::dbms::DBConnection::getAggregate	(	const std::string &	column,
		const std::string &	table,
		const std::string &	function,
		carma::dbms::Table::ColumnType &	type
	)		const

virtual

get the specified aggregate value of the specified column from the specified table.

the returned pointer is created internally by calling "new"; callers are responsible for running "delete" on it to prevent memory leaks, the type of the returned pointer can be determined by the output "type" parameter

Parameters

column	[in] the column from which to get the aggregate value
table	[in] table from which to get the aggregate value
function	[in] the aggregate function to use
type	[out] the type of the returned pointer

Returns: the pointer to the value or null

Table carma::dbms::DBConnection::getLogMessages	(	const carma::util::frameType &	start,
		const carma::util::frameType &	end = `carma::util::Time::computeCurrentFrame()`,
		const std::string *	matchString = `NULL`
	)		const

get the log messages in the specified frameCount range.

The returned Table contains two columns the first contains the times and the second contains the messages, e.g, a client can access the info via Table t = dbc->getLogMessage(<starttime>,<stoptime>); vector<int> times = t.getIntegerColumn(0); vector<string> msgs = t.getStringColumn(1);

Parameters

start	the start frameCount
end	the end frameCount
matchString	do additional filtering based on matches of this string in the messages, NULL => no filtering based on substring match

Returns: a two column table containing times (first column) and messages (second column)

Exceptions

DBConnectionException

virtual long carma::dbms::DBConnection::getRowCount ( const std::string & tableName ) const

virtual

get the number of rows in the specified table

Parameters

tableName the name of the table

Returns: the number of rows in the specified table

void carma::dbms::DBConnection::insertLogMessage	(	const std::string &	message,
		const carma::util::frameType &	frameCount = `carma::util::Time::computeCurrentFrame()`
	)		const

add a log message to the Log table

Parameters

message	the message to add
frameCount	the corresponding frameCount which applies to the message

Exceptions

DBConnectionException

virtual bool carma::dbms::DBConnection::inTransaction ( ) const

virtual

is a transaction being executed?

Returns: true if a transaction is being executed

Exceptions

DBConnectionException

Reimplemented in carma::dbms::PostgresDBConnection, and carma::dbms::MySQLDBConnection.

virtual bool carma::dbms::DBConnection::isDBUp ( )

virtual

is the RDBMS in question up and accepting connections

Returns: true if a connection can be made to the database

static bool carma::dbms::DBConnection::isUp ( const DBConfigurator * dbconf = NULL )

static

is the database specified by the dbconf object up and accepting connections?

Parameters

dbconf the DBConfigurator object containing info on how to connect to the database, if NULL use sensible defaults

Returns: true if the specified database is up and available for connections

virtual void carma::dbms::DBConnection::loadDataFromFile	(	const std::string &	filename,
		const std::string &	table,
		const bool &	useTransactions,
		const int &	linesToIgnore = `0`,
		const std::string &	columnDelimiter = `"\t"`
	)		const

pure virtual

load data into a table from a disk file.

Because this is not an ODBC supported operation, derived classes must implement this method using their own native RDBMS interfaces

Parameters

filename	the name of the file from which to load the data
table	the database table into which to load the data
useTransactions	use transcations to load the data, how this parameter is used is determined by the implenting class
linesToIgnore	number of lines to ignore (e.g. header files) at the beginning of the file

Implemented in carma::dbms::MySQLDBConnection.

virtual void carma::dbms::DBConnection::loadDataFromFiles	(	const file2TableMap &	file2Table,
		const bool &	useTransactions,
		const int &	linesToIgnore = `0`,
		const std::string &	columnDelimiter = `"\t"`
	)		const

pure virtual

load data into tables from disk files.

Because this is not an ODBC supported operation, derived classes must implement this method using their own native RDBMS interfaces

Parameters

file2Table	the file to table map
useTransactions	should transactions be used (implementing classes decide how to use this parameter
linesToIgnore	number of lines to ignore (e.g. header files) at the beginning of the file

Implemented in carma::dbms::MySQLDBConnection.

virtual unsigned carma::dbms::DBConnection::maxColumnsPerTable ( ) const

pure virtual

the maximum number of columns the RDBMS allows in a table

Returns: the maximum number of columns permitted in a table

Implemented in carma::dbms::MySQLDBConnection.

virtual unsigned carma::dbms::DBConnection::maxTablesPerJoin ( ) const

pure virtual

the maximum number of tables the RDBMS allows in a join

Returns: the maximum number of tables which can be joined in a SELECT statement

Implemented in carma::dbms::MySQLDBConnection.

virtual void carma::dbms::DBConnection::monitorDataTableHasBeenPopulated	(	const std::string &	tableName,
		const MonitorAverageType &	averageType
	)		const

virtual

performs tasks after a monitor data table has been completely populated.

currently this means a call to updateMonitorIndexTable() is made, although derived classes may have different implementations

Reimplemented in carma::dbms::MySQLDBConnection.

void carma::dbms::DBConnection::odbcInfo ( ) const

print various details about ODBC support

carma::dbms::Table carma::dbms::DBConnection::odbcResultSetToTable_ ( const SQLHSTMT & hstmt ) const

protected

convert an ODBC result set to a carma::dbms::Table object

Parameters

resultSet the ODBC result set

Returns: the carma::dbms::Table object holding the resultSet

void carma::dbms::DBConnection::openODBCConnection_	(	SQLHENV *	henv,
		SQLHDBC *	hdbc
	)

protected

open a database connection using ODBC, henv_ and hdbc_ are initialized here

Exceptions

DBConnectionException if the connection cannot be established

std::string carma::dbms::DBConnection::rdbmsName ( ) const

get the name of the RDBMS associated with this object

Returns: the name of the RDBMS associated with this object

Definition at line 93 of file DBConnection.h.

std::string carma::dbms::DBConnection::readPassword_ ( ) const

protected

read the database user's password so that it can be sent to the ODBC driver as part of the connect string IMPORTANT! Passwords are considered sensitive information and so the files in which they reside should be readable only by the unix account which owns them

Returns: the password

virtual void carma::dbms::DBConnection::repairMonitorDataTable ( const std::string & tableName ) const

pure virtual

attempt to repair a corrupt monitor data table

Parameters

tableName the table name to repair

Implemented in carma::dbms::MySQLDBConnection.

virtual void carma::dbms::DBConnection::rollBackTransaction ( ) const

virtual

rollback a transaction

Exceptions

DBConnectionException

Reimplemented in carma::dbms::PostgresDBConnection, and carma::dbms::MySQLDBConnection.

bool carma::dbms::DBConnection::tableExists	(	const std::string &	table,
		const std::string &	database
	)		const

does the specified table exist in the specified database?

Parameters

table	the table to check the existence of
database	the database in which this table is located. "" => current database

Returns: true if the table exists

Member Data Documentation

SQLHDBC carma::dbms::DBConnection::hdbc_

protected

connection and environment handles for ODBC interface

Definition at line 449 of file DBConnection.h.

std::string carma::dbms::DBConnection::odbcini_

protected

odbc config file

Definition at line 443 of file DBConnection.h.

The documentation for this class was generated from the following file:

carma/dbms/DBConnection.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation