BPS datastore class. More...

#include <bpsdatastore.h>

Signals
void	connected ()
	Signal is emitted after successful connection.
void	disconnected ()
	Signal is emitted after disconnection.
Public Member Functions
QVariant	actorKey () const
	Return the actor's key (c_key in the t_actors table).
QString	application () const
	BpsDatastore (QObject *aParent=0)
	Constructor for the BpsDatastore objects.
void	checkin (const QString &aTerminalName=QString(), const QString &aApplicationName=QString())
	Check in the user by creating a record in table t_actors.
void	checkout ()
	Check out the user by dropping the record in table t_actors.
void	clearKeys (QVariant aId)
	Delete a key list from table t_keys.
void	commit ()
	Commit an open transaction.
void	connect ()
	Connect to database server using the current settings in the properties username, password, driver, database, host and port.
QString	connection () const
	Get the connection name.
QDateTime	currentTimestamp ()
QString	database () const
	Get database name for PostgreSQL, or TNS service name or SID for Oracle.
void	disconnect ()
	Disconnect from database server if currently connected.
QString	driver () const
	Get driver name (QPSQL or QOCI).
void	dropConnection (BpsSettings::Scopes aScopes=BpsSettings::LocalUserScope)
	Drop connection.
bool	hasDivisionAccess (const QVariant &aDivisionKey)
	Checks if the current user is authorized for the division.
bool	hasPermission (const QString &aPermission)
	Checks if the current user is authorized for the named permission.
bool	hasZoneAccess (const QVariant &aZoneKey)
	Checks if the current user is authorized for the zone.
QString	host () const
	Get host IP name or address.
bool	indexExists (const QString &aName, const QString &aSchema=QString())
	Check if a certain index exists.
bool	inTransaction () const
bool	isConnected () const
	Check current connection status.
bool	isOracle () const
	Check if current driver is for Oracle.
bool	isOwner () const
	Check if the current user is the BPS owner.
bool	isPostgres () const
	Check if current driver is for PostgreSQL.
QSqlDatabase &	link ()
	Get QSqlDatabase object.
bool	loadConnection (BpsSettings::Scopes aScopes=BpsSettings::LocalScopes)
	Load connection settings.
bool	lockTable (const QString &aTable, int aTimeout)
	Start a transaction with the given table locked in exclusive mode.
QVariant	nextIdent (const QString &aSeqenceName)
	Get the next sequence value.
QVariant	nextKey (const QString &aName)
	Get the next unused key for a table.
QString	password () const
	Get database user password.
int	port () const
	Get host IP port number.
QSqlIndex *	primaryIndex (const QString &aTableName)
	Get the primary index for a certain table.
void	purgeActors ()
	Purge actors which are no longer connected.
QSqlRecord *	record (const QString &aTableName)
	Get the record info for a certain table.
void	renameConnection (const QString &aConnection, BpsSettings::Scopes aScopes=BpsSettings::LocalUserScope)
	Rename the connection.
Bps::Access	reportAccess (const QVariant &aReportKey)
	Check access to a certain report.
QStringList	roles ()
	Get a list of all roles.
void	rollback ()
	Rollback an open transaction.
void	saveConnection (BpsSettings::Scopes aScopes=BpsSettings::LocalUserScope)
	Save the connection settings.
QString	schema () const
	Get BPS datastore schema name.
bool	sequenceExists (const QString &aName, const QString &aSchema=QString())
	Check if a certain sequence exists.
QVariant	sessionId () const
	Return the current actors session id (the database internal identifier of the current session).
void	setConnection (const QString &aConnection)
	Set the connection name.
void	setDatabase (const QString &aDatabase)
	Set database name.
void	setDriver (const QString &aDriver)
	Set database driver name.
void	setHost (const QString &aHost)
	Set DB server's host name or IP address.
QVariant	setKeys (const QList< qulonglong > &aKeys)
	Insert a key list into table t_keys.
QVariant	setKeys (const QList< qlonglong > &aKeys)
	Insert a key list into table t_keys.
QVariant	setKeys (const QVariantList &aKeys)
	Insert a key list into table t_keys.
void	setPassword (const QString &aPassword)
	Set database user password.
void	setPort (int aPort)
	Set the servers database service IP port number.
void	setSchema (const QString &aSchema)
	Set BPS schema.
void	setUsername (const QString &aUsername)
	Set database user name.
bool	tableExists (const QString &aName, const QString &aSchema=QString())
	Check if a certain table exists.
QStringList	tablespaces ()
	Get a list of all tablespaces.
QString	terminal () const
void	touchActor ()
	Update the actors timestamp.
void	transaction ()
	Start a new transaction.
int	userid () const
	Returns the user id (the numeric bps user identification).
QVariant	userKey () const
	Returns the user's key (c_key in the t_users table).
QString	username () const
	Get database user name.
QStringList	users ()
	Get a list of all database user names.
bool	viewExists (const QString &aName, const QString &aSchema=QString())
	Check if a certain view exists.
Static Public Member Functions
static QStringList	connections ()
	Get all defined connections.
static QString	quote (const QString &aText)
	Quote a literal text in single quotes to include it in a sql statement.
static QString	quote (QChar aChar)
	Quote a char in single quotes to include it in a sql statement.
static QStringList	tnsnames ()
	Get a list of all Oracle TNS names.

Detailed Description

BPS datastore class.

This is the datastore class used throughout the BPS class library. It supports connections to PostgreSQL and to Oracle. The class encapsulates a Qt database connection, adding generic methods for both database types supported by BPS.

Examples:: database1.cpp.

Constructor & Destructor Documentation

BpsDatastore::BpsDatastore ( QObject * aParent = 0 )

Constructor for the BpsDatastore objects.

Parameters:

aParent Pointer to an optional parent object.

Member Function Documentation

QVariant BpsDatastore::actorKey ( ) const

Return the actor's key (c_key in the t_actors table).

A valid actorKey is only returned when checked in, otherwise an invalid QVariant is returned.

Returns:: QVariant with the actor key.

QString BpsDatastore::application ( ) const

Returns:: Application name used at checkin.

void BpsDatastore::checkin	(	const QString &	aTerminalName = `QString()`,
		const QString &	aApplicationName = `QString()`
	)

Check in the user by creating a record in table t_actors.

Checking in is required for active users, because all permanent locks will be referencing the entry in t_actors. In case the current connection was already checked in, it will be checked out before attempting to do the new check in.

Parameters:

[in]	aTerminalName	The terminal name for the session. Pass an empty string to use bps->terminalName().
[in]	aApplicationName	The name of the application. For C++ applications the file path of the executable, for standalone scripts the file path of the script. Pass an empty string to use QCoreApplication::applicationFilePath().

Exceptions:

BpsException When not connected, no valid userid or general sql error.

void BpsDatastore::checkout ( )

Check out the user by dropping the record in table t_actors.

Exceptions:

BpsException When not connected or general sql error.

void BpsDatastore::clearKeys ( QVariant aId )

Delete a key list from table t_keys.

Parameters:

[in] aId The ID of the list.

void BpsDatastore::commit ( )

Commit an open transaction.

Exceptions:

BpsException When not connected or commit fails.

void BpsDatastore::connect ( )

Connect to database server using the current settings in the properties username, password, driver, database, host and port.

Exceptions:

BpsException When driver cannot be loaded or connect fails.

Examples:: database1.cpp.

QString BpsDatastore::connection ( ) const

Get the connection name.

The default connection name is empty. The connection name serves to store the database connection parameters host name, port, database and schema in a convenient way so only the connection needs to be selected to set all four parameters in one go.

Returns:: Connection name.

static QStringList BpsDatastore::connections ( ) [static]

Get all defined connections.

Returns:: A list of all connections that have been declared in the BPS configuration program.

QDateTime BpsDatastore::currentTimestamp ( )

Returns:: The current timestamp from the datastore.

QString BpsDatastore::database ( ) const

Get database name for PostgreSQL, or TNS service name or SID for Oracle.

Note:: For Oracle the database name either refers to the TNS name or to the SID. In case a non-empty host name is given, the database is assumed to be the SID, when the host name is empty it is treated as the TNS name.

Returns:: Database name for PostgreSQL, TNS service name or SID for Oracle.

void BpsDatastore::disconnect ( )

Disconnect from database server if currently connected.

Returns:: Database object reference.

Examples:: database1.cpp.

QString BpsDatastore::driver ( ) const

Get driver name (QPSQL or QOCI).

Returns:: "QPSQL" for PostgreSQL, "QOCI" for Oracle.

void BpsDatastore::dropConnection ( BpsSettings::Scopes aScopes = BpsSettings::LocalUserScope )

Drop connection.

The database properties are removed from the settings.

Parameters:

[in] aScopes Scopes at which the settings are removed. Valid scopes include BpsSettings::LocalUserSettings, BpsSettings::LocalSystemSettings and BpsSettings::LocalInstallSettings.

See also:: saveConnection()

bool BpsDatastore::hasDivisionAccess ( const QVariant & aDivisionKey )

Checks if the current user is authorized for the division.

Note:: When isOwner() is true, hasDivisionAccess() returns always true.

Parameters:

[in] aDivisionKey The key within table t_divisions.

Returns:: True if the division access is granted.

bool BpsDatastore::hasPermission ( const QString & aPermission )

Checks if the current user is authorized for the named permission.

Note:: When isOwner() is true, hasPermission() returns always true.

Parameters:

[in] aPermission The permission name, for example settings.view

Returns:: True if the permission is granted.

bool BpsDatastore::hasZoneAccess ( const QVariant & aZoneKey )

Checks if the current user is authorized for the zone.

Note:: When isOwner() is true, hasZoneAccess() returns always true.

Parameters:

[in] aZoneKey The key within table t_zones.

Returns:: True if the zone access is granted.

QString BpsDatastore::host ( ) const

Get host IP name or address.

Note:: For Oracle, when using a TNS service name the host name must stay empty. If a host name or IP is set for Oracle, then a ad-hoc connection will be made using host name and port, and using the database property as SID.

Returns:: Host IP name or address.

bool BpsDatastore::indexExists	(	const QString &	aName,
		const QString &	aSchema = `QString()`
	)

Check if a certain index exists.

Parameters:

[in]	aName	Name of the index.
[in]	aSchema	Schema name. Default schema is used when omitted.

Exceptions:

BpsException When the query fails.

Returns:: True if the index exists, false otherwise.

bool BpsDatastore::inTransaction ( ) const

Returns:: True if in uncommitted transaction, false if not.

bool BpsDatastore::isConnected ( ) const

Check current connection status.

Returns:: True if currently connected, false otherwise.

bool BpsDatastore::isOracle ( ) const

Check if current driver is for Oracle.

Returns:: True if current driver is QOCI, false otherwise.

bool BpsDatastore::isOwner ( ) const

Check if the current user is the BPS owner.

The schema must not be empty and be equal to the username. Compare of username and schema are done case insensitive.

Returns:: True if the BPS owner, false otherwise.

bool BpsDatastore::isPostgres ( ) const

Check if current driver is for PostgreSQL.

Returns:: True if current driver is QPSQL, false otherwise.

QSqlDatabase& BpsDatastore::link ( )

Get QSqlDatabase object.

Returns:: Qt database object used by the BPS datastore class for direct usage of Qt functions.

bool BpsDatastore::loadConnection ( BpsSettings::Scopes aScopes = BpsSettings::LocalScopes )

Load connection settings.

When loading a connection that has been previously saved, the properties for node, schema, database, driver, host and port are searched and loaded from the locations defined in aScopes.

Parameters:

[in] aScopes Scopes at which the settings are searched. Valid scopes include BpsSettings::LocalUserSettings, BpsSettings::LocalSystemSettings and BpsSettings::LocalInstallSettings.

Returns:: True if the connection settings were found and loaded.

bool BpsDatastore::lockTable	(	const QString &	aTable,
		int	aTimeout
	)

Start a transaction with the given table locked in exclusive mode.

Commit or rollback the transaction to release the lock.

Parameters:

[in]	aTable	Name of the table to lock.
[in]	aTimeout	Time out in seconds while waiting for lock. Special values: 0 = no wait, -1 = wait endless.

Returns:: True if the lock was successful, false if not.

QVariant BpsDatastore::nextIdent ( const QString & aSeqenceName )

Get the next sequence value.

Parameters:

[in] aSeqenceName The name of the sequence.

Returns:: Next identifier as QVariant.

QVariant BpsDatastore::nextKey ( const QString & aName )

Get the next unused key for a table.

Parameters:

[in] aName The base name of the sequence and table, where the prefix s_ and t_ is added. Example: aName = users, sequence = s_users and table = t_users.

Returns:: Next key as QVariant.

QString BpsDatastore::password ( ) const

Get database user password.

Returns:: Database user password.

int BpsDatastore::port ( ) const

Get host IP port number.

The default is -1 which will assume 5432 for PostgreSQL and 1531 for Oracle (in case not using TNS).

Returns:: Host IP port number.

QSqlIndex* BpsDatastore::primaryIndex ( const QString & aTableName )

Get the primary index for a certain table.

If no primary index exists an empty QSqlIndex is returned.

Parameters:

[in] aTableName The name of the table.

Returns:: The primary index.

void BpsDatastore::purgeActors ( )

Purge actors which are no longer connected.

Such records can be present in case of crashed sessions. Removing them will release all permanent locks that still may be held.

Exceptions:

BpsException When not connected or general sql error.

static QString BpsDatastore::quote ( const QString & aText ) [static]

Quote a literal text in single quotes to include it in a sql statement.

Takes care of any single quotes within the literal.

Parameters:

[in] aText Literal text to be quoted.

Returns:: Quoted literal text.

static QString BpsDatastore::quote ( QChar aChar ) [static]

Quote a char in single quotes to include it in a sql statement.

Takes care of char being a single quote itself.

Parameters:

[in] aChar Char to be quoted.

Returns:: Quoted char.

QSqlRecord* BpsDatastore::record ( const QString & aTableName )

Get the record info for a certain table.

Parameters:

[in] aTableName The name of the table.

Returns:: The record of the found table, or an empty record if no such table found.

void BpsDatastore::renameConnection	(	const QString &	aConnection,
		BpsSettings::Scopes	aScopes = `BpsSettings::LocalUserScope`
	)

Rename the connection.

Parameters:

[in]	aConnection	New name of the connection.
[in]	aScopes	Scopes at which the settings are renamed. Valid scopes include BpsSettings::LocalUserSettings, BpsSettings::LocalSystemSettings and BpsSettings::LocalInstallSettings.

Bps::Access BpsDatastore::reportAccess ( const QVariant & aReportKey )

Check access to a certain report.

The connection must be established and checked in.

Parameters:

aReportKey The key within table t_reports.

Returns:: Access for current user.

QStringList BpsDatastore::roles ( )

Get a list of all roles.

Exceptions:

BpsException When the query fails.

Returns:: List of all roles in lowercase.

void BpsDatastore::rollback ( )

Rollback an open transaction.

Exceptions:

BpsException When not connected or rollback fails.

void BpsDatastore::saveConnection ( BpsSettings::Scopes aScopes = BpsSettings::LocalUserScope )

Save the connection settings.

The database properties are saved for subsequent availability by setConnection().

Parameters:

[in] aScopes Scopes at which the settings are saved. Valid scopes include BpsSettings::LocalUserSettings, BpsSettings::LocalSystemSettings and BpsSettings::LocalInstallSettings.

See also:: dropConnection()

QString BpsDatastore::schema ( ) const

Get BPS datastore schema name.

Returns:: BPS datastore schema name.

bool BpsDatastore::sequenceExists	(	const QString &	aName,
		const QString &	aSchema = `QString()`
	)

Check if a certain sequence exists.

Parameters:

[in]	aName	Name of the sequence.
[in]	aSchema	Schema name. Default schema is used when omitted.

Exceptions:

BpsException When the query fails.

Returns:: True if the sequence exists, false otherwise.

QVariant BpsDatastore::sessionId ( ) const

Return the current actors session id (the database internal identifier of the current session).

A valid sessionId is only returned when connected, otherwise an invalid QVariant is returned.

Returns:: QVariant with the session id.

void BpsDatastore::setConnection ( const QString & aConnection )

Set the connection name.

The database connection name is used to identify a certain connection within the application.

Parameters:

[in] aConnection Name of the connection.

See also:: connection()

void BpsDatastore::setDatabase ( const QString & aDatabase )

Set database name.

Parameters:

[in] aDatabase Database name for PostgreSQL, TNS name or SID for Oracle.

See also:: database() const

Examples:: database1.cpp.

void BpsDatastore::setDriver ( const QString & aDriver )

Set database driver name.

The database driver name as "QPSQL" for PostgreSQL, or "QOCI" for Oracle.

Parameters:

[in] aDriver Database driver name as "QPSQL" for PostgreSQL, or "QOCI" for Oracle.

Examples:: database1.cpp.

void BpsDatastore::setHost ( const QString & aHost )

Set DB server's host name or IP address.

Either the database servers host name, or it's numeric IP address.

Parameters:

[in] aHost Database server's host name or IP address.

See also:: host()

QVariant BpsDatastore::setKeys ( const QList< qulonglong > & aKeys )

Insert a key list into table t_keys.

Only unique keys are inserted, duplicates are silently ignored. The list will get automatically deleted on checkout. However it is good practice to purge no longer used lists with method clearKeys().

Select example:

 QVariant kid = mDatastore->setKeys(myKeyList);
 BpsQuery q(mDatastore);
 q.prepare(bStr(
     "select * from t_sometable t "
     "inner join t_keys k on k.c_id=? and t.c_key=k.c_key"
 ));
 q.bind(kid);
 q.execute();
 mDatastore->clearKeys(kid);

Update example:

 QVariant kid = mDatastore->setKeys(myKeyList);
 BpsQuery q(mDatastore);
 q.prepare(bStr(
     "update t_sometable ... "
     "where c_key in (select c_key from t_keys where c_id=?)"
 ));
 q.bind(kid);
 q.execute();
 mDatastore->clearKeys(kid);

Parameters:

[in] aKeys The list of keys to insert.

Returns:: ID referencing the key list.

QVariant BpsDatastore::setKeys ( const QList< qlonglong > & aKeys )

Insert a key list into table t_keys.

Only unique keys are inserted, duplicates are silently ignored. The list will get automatically deleted on checkout. However it is good practice to purge no longer used lists with method clearKeys().

Parameters:

[in] aKeys The list of keys to insert.

Returns:: ID referencing the key list.

QVariant BpsDatastore::setKeys ( const QVariantList & aKeys )

Insert a key list into table t_keys.

Only unique keys are inserted, duplicates are silently ignored. The list will get automatically deleted on checkout. However it is good practice to purge no longer used lists with method clearKeys().

Parameters:

[in] aKeys The list of keys to insert.

Returns:: ID referencing the key list.

void BpsDatastore::setPassword ( const QString & aPassword )

Set database user password.

Set the password before connecting to the database.

Parameters:

[in] aPassword Password of the database user.

Examples:: database1.cpp.

void BpsDatastore::setPort ( int aPort )

Set the servers database service IP port number.

Parameters:

[in] aPort Database service port number on server.

See also:: port() const

void BpsDatastore::setSchema ( const QString & aSchema )

Set BPS schema.

Parameters:

[in] aSchema BPS schema name.

void BpsDatastore::setUsername ( const QString & aUsername )

Set database user name.

Set the username before connection to the database.

Parameters:

[in] aUsername Name of the database user.

Examples:: database1.cpp.

bool BpsDatastore::tableExists	(	const QString &	aName,
		const QString &	aSchema = `QString()`
	)

Check if a certain table exists.

Parameters:

[in]	aName	Name of the table.
[in]	aSchema	Schema name. Default schema is used when omitted.

Exceptions:

BpsException When the query fails.

Returns:: True if the table exists, false otherwise.

QStringList BpsDatastore::tablespaces ( )

Get a list of all tablespaces.

Exceptions:

BpsException When the query fails.

Returns:: List of all tablespaces in lowercase.

QString BpsDatastore::terminal ( ) const

Returns:: Terminal name used at checkin.

static QStringList BpsDatastore::tnsnames ( ) [static]

Get a list of all Oracle TNS names.

Returns:: List of all TNS names found.

Note:: Because Oracle has never provided an API or discloses any information how the TNS names can be found, you cannot rely that all TNS names are found by this function. So you should allow your software to also use TNS names not returned in this list.

void BpsDatastore::touchActor ( )

Update the actors timestamp.

Will usually be called by license check routines.

void BpsDatastore::transaction ( )

Start a new transaction.

The transaction will be closed either by a call to commit, or a call to rollback.

Exceptions:

BpsException When not connected or transaction cannot be started.

int BpsDatastore::userid ( ) const

Returns the user id (the numeric bps user identification).

No valid userid is returned when the username is not made up by {schema}{userid}. The userid of the BPS owner is 0.

Returns:: The userid, or -1 if the userid is invalid.

QVariant BpsDatastore::userKey ( ) const

Returns the user's key (c_key in the t_users table).

A valid userKey is only returned when checked in, otherwise an invalid QVariant is returned.

Returns:: QVariant with the user key.

QString BpsDatastore::username ( ) const

Get database user name.

Returns:: Database user name.

QStringList BpsDatastore::users ( )

Get a list of all database user names.

Exceptions:

BpsException When the query fails.

Returns:: List of all database user names in lowercase.

Examples:: database1.cpp.

bool BpsDatastore::viewExists	(	const QString &	aName,
		const QString &	aSchema = `QString()`
	)

Check if a certain view exists.

Parameters:

[in]	aName	Name of the view.
[in]	aSchema	Schema name. Default schema is used when omitted.

Exceptions:

BpsException When the query fails.

Returns:: True if the view exists, false otherwise.

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

bpsdatastore.h

Signals

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation