Isis database class providing generalized access to a variety of databases. More...

#include <Database.h>

Inheritance diagram for Isis::Database:

Collaboration diagram for Isis::Database:

Public Types
enum	Access { Connect, DoNotConnect }
	Access status for database creation. More...

Public Member Functions
	Database ()
	Default database constructor. More...

	Database (Access dbConn)
	Construction of the unamed database with optional connection. More...

	Database (const QString &connName, const QString &driverType)
	Create database connection specified by name and driver type. More...

	Database (const QString &name, Access dbConn=Connect)
	Create a named database object. More...

	Database (const DbProfile &profile, Access dbConn=Connect)
	Create database connection using the supplied DbProfile. More...

virtual	~Database ()
	Database destructor. More...

QString	Name () const
	Return the name of this database as specifed upon creation. More...

void	makePersistant ()
	Makes this instance persistant. More...

bool	isPersistant () const
	Checks persistancy state of a database instantiation. More...

void	setAsDefault ()
	Sets this database connection/profile as the default. More...

Database	clone (const QString &name) const
	Clones this database into another giving it another name. More...

QStringList	getTables () const
	Returns a vector string containing all the tables in the database. More...

QStringList	getViews () const
	Returns a vector string containing all views within the database. More...

QStringList	getSystemTables () const
	Returns vector strings of all available system tables in the database. More...

Static Public Member Functions
static void	remove (const QString &name)
	Removes the named database from pool. More...

static bool	addAccessConfig (const QString &confFile)
	Adds a user specifed access configuration file to system. More...

static DbProfile	getProfile (const QString &name)
	Retrieves the named database access profile. More...

Protected Member Functions
	Database (const QSqlDatabase &other, const QString &name)
	Constructor creates a clone/copy from an existing one. More...

QSqlDatabase	init (const DbProfile &profile, Access dbConn=Connect)
	Create and initialize a new database connection from a DbProfile. More...

QSqlDatabase	init (const QString &name="", const QString &driverType="")
	Initializes a database by connection name and driver type. More...

void	configureAccess (QSqlDatabase &db, const DbProfile &profile)
	Set access parameters from a database DbProfile access specification. More...

Detailed Description

Isis database class providing generalized access to a variety of databases.

This class provides database connections within the Isis application programming interface (API) environment. It is based upon the DatabaseFactory class and utilizes its features to let users control access to databases. See the documentation for that class to get a full description of generalized access methods as defined by users.

This class also provides programmer derived access using either database profiles (DbProfile) containing access (DbAccess) specifications.

// Use the UPC profile

Database upc("upc")

Connections can be made to specific databases using named drivers also provided from the DatabaseFactory class.

//  Set up one for UPC directly
 Database upc1("upcDirect", "PostgreSQL");   // "QPSQL" also works
 upc1.setHostName("upcdb0.wr.usgs.gov");
 upc1.setDatabaseName("upc");
 upc1.setUserName("upcread");
 upc1.setPort(3309);
 upc1.open();

Since this class is derived from the Qt QSqlDatabase class, it can and is intended to be used in the Qt environment directly. IMPORTANT NOTE: The init() function returns a QSqlDatabase instance in all constructors which means that the class has not yet completed constructing. The implications of this are that the Database class elements, namely data constructs, are generally off limits until after the return from init(). This is primarily the reason for some of the implimentation decisions made in this class.

Member Enumeration Documentation

◆ Access

enum Isis::Database::Access

Access status for database creation.

Enumerator
Connect	Connect to database immediately.
DoNotConnect	Do not connect to database.

Constructor & Destructor Documentation

◆ Database() [1/6]

Isis::Database::Database ( )

Default database constructor.

This constructor does not interact at all with the DatabaseFactory class but uses the default condition for the Qt QSqlDatabase state.

Referenced by clone().

◆ Database() [2/6]

Isis::Database::Database ( Database::Access dbConn )

Construction of the unamed database with optional connection.

This Database constructor essentially will attempt to invoke the default profile as provided by the DatabaseFactory class. That profile is read when the factory is created using the IsisPreferences class. If there is a Database object there and it contains a specification of an AccessConfig profile, the contents of the profile mentioned there govern the action of this constructor.

If the caller provides true to this class, it will immediately attempt a connection. Otherwise it will not attempt a connection to the database.

Use the isOpen Qt method to check for the status of the connection.

Parameters

dbConn If Connect, an immediate connection is attempted, otherwise connection is deferred.

References _FILEINFO_, and Connect.

◆ Database() [3/6]

Isis::Database::Database	(	const QString &	connName,
		const QString &	driverType
	)

Create database connection specified by name and driver type.

This constructor is useful for creating a named database with a specific driver type. The following example creates a PostgreSQL database named "sparky".

Database db("sparky", "postgresql");

If you do not provide a driver (driverType = ""), then it will attempt to find an existing database connection named "sparky" and use it or it will attempt to resolve the request by searching for a DbProfile named "sparky".

Parameters

connName	Name of connect to create or return
driverType	Type of database to created. This is typically MySQL, PostgreSQL or SQLite.

◆ Database() [4/6]

Isis::Database::Database	(	const QString &	name,
		Database::Access	dbConn = `Connect`
	)

Create a named database object.

This construction scheme assumes the named database either already exists as a persistant database connection or exists as a user specified profile in the DatabaseFactory environment.

Parameters

name	Name of the desired database connection to establish
dbConn	If Connect, an immediate connection is attempted, otherwise connection is deferred.

References _FILEINFO_, and Connect.

◆ Database() [5/6]

Isis::Database::Database	(	const DbProfile &	profile,
		Database::Access	dbConn = `Connect`
	)

Create database connection using the supplied DbProfile.

This constructor accepts a DbProfile that contains sufficient information to create a complete database connection. The caller can optional request that the connection be established meaning that the profile contain enough information to do so. If connect = false, then upon return, the caller can further add or modify connection parameters as needed.

Parameters

profile	DbProfile containing a single database connection profile or one that provides enough information to determine appropriate access information.
dbConn	If Connect, an immediate connection is attempted, otherwise connection is deferred.

References _FILEINFO_, and Connect.

◆ ~Database()

Isis::Database::~Database ( )

virtual

Database destructor.

This will close the Database connection if it is still open, and, if it is not marked as persistant, it is removed from the named Database pool. It is not completely removed (from the Qt QSqlDatabase pool), however. Use the remove() method to ensure it is completely destroyed/removed from the pool.

References Isis::DatabaseFactory::getInstance(), Isis::DatabaseFactory::isPersistant(), and Isis::DatabaseFactory::remove().

◆ Database() [6/6]

Isis::Database::Database	(	const QSqlDatabase &	other,
		const QString &	newName
	)

protected

Constructor creates a clone/copy from an existing one.

This constructor creates a clone or copy of an existing one. You can be sure that you can send it a Database object as well as a Qt QSqlDatabase since the Database class inherits the QT QSqlDatabase class.

Parameters

other	Database to clone from this one
newName	New name of the cloned database (it can't be the same name)

Member Function Documentation

◆ addAccessConfig()

bool Isis::Database::addAccessConfig ( const QString & confFile )

static

Adds a user specifed access configuration file to system.

This method accepts a file name that contains a Database access configuration file and adds it to the database access profile system. This is actually performed by the DatabaseFactory class.

See also: DatabaseFactory::addAccessProfile()

Parameters

confFile Name of file to add. This can have any valid Isis or environment variable as part of the file specfication.

Returns: bool True if successful, false if the file could not be opened or an error was found in the file.

References Isis::DatabaseFactory::addAccessProfile(), and Isis::DatabaseFactory::getInstance().

◆ clone()

Database Isis::Database::clone ( const QString & name ) const

Clones this database into another giving it another name.

This database object is cloned into another one and names it the provided name. All access parameters are retained as initiallyt set up.

Parameters

name	Name to give the cloned database.

Returns: The cloned Database

References Database().

◆ configureAccess()

void Isis::Database::configureAccess	(	QSqlDatabase &	db,
		const DbProfile &	profile
	)

protected

Set access parameters from a database DbProfile access specification.

This method takes a database and a database access configuration setup and applies the parameters to it setting up access. This method does not intiate the connection, only sets known, common parameters. These parameters are Host, DbName, User, password, Port and Options. They follow the specifications of the Qt SQL QSqlDatabase class methods.

Parameters

db	The Qt database object to set access parameters for.
profile	The database access parameter source.

References _FILEINFO_, Isis::DbProfile::exists(), Isis::toInt(), and Isis::IException::User.

Referenced by init().

◆ getProfile()

DbProfile Isis::Database::getProfile ( const QString & name )

static

Retrieves the named database access profile.

This method is provided to the calling environment to retrieve any named profile. If an empty string is provided, it returns the default as determined by the DatabaseFactory class rules.

This can be used to determine the default and potentially augment its contents prior to creating a database connection.

For example, here is a small code segment that retrieves the default access profile and tests for its validity. If it is not valid, chances are there is no default established.

DbProfile default = Database::getProfile();
if (!default.isValid()) {
   cerr << "No default access profile established!" << endl;
}
//  Open the database (after optional modification)
Database mydb(default);

See also: DatabaseFactory::getProfile()

Parameters

name	Name of profile to retrieve. An empty string will return the default profile.

Returns: DbProfile Requested profile. Test its validity using the DbProfile::isValid() method.

References Isis::DatabaseFactory::getInstance(), and Isis::DatabaseFactory::getProfile().

◆ getSystemTables()

QStringList Isis::Database::getSystemTables ( ) const

Returns vector strings of all available system tables in the database.

This method returns a vector of strings containing a list of all system tables accessable to the user within the database.

Returns: std::vector<QString> List of system tables with the database

◆ getTables()

QStringList Isis::Database::getTables ( ) const

Returns a vector string containing all the tables in the database.

This method returns a complete list of accessable tables within the database. It is assumed the database connections is established and open.

Returns: std::vector<QString> List of tables in the database

◆ getViews()

QStringList Isis::Database::getViews ( ) const

Returns a vector string containing all views within the database.

This method returns a vector of strings with all views accessable to the user in each element in the vector.

Returns: std::vector<QString> List of all accessable views in the database

◆ init() [1/2]

QSqlDatabase Isis::Database::init	(	const DbProfile &	profile,
		Database::Access	dbConn = `Connect`
	)

protected

Create and initialize a new database connection from a DbProfile.

This init method accepts a DbProfile database access profile that is assumed to contain sufficient information to establish a connection and open it. Note that the connection is opened only if the connect = true. Otherwise, the parameters from teh profile is set but the database is returned without initiating a connection to the database - this so the caller can adjust or provide additional parameters.

NOTE: This method is implemented in such a way that it assumes it is part of the QSqlDatabase initialization phase upon object construction. You will see some implementation decisions based upon this expeectation.

Parameters

profile	A valid database profile specifying access parameters.
dbConn	If Connect, an immediate connection is attempted, otherwise connection is deferred.

Returns: QSqlDatabase A Qt database object with access parameters set

References _FILEINFO_, configureAccess(), Connect, Isis::DatabaseFactory::create(), Isis::DatabaseFactory::getInstance(), Isis::DbProfile::isValid(), Isis::DbProfile::Name(), Isis::IException::Programmer, and Isis::IException::User.

Referenced by init().

◆ init() [2/2]

QSqlDatabase Isis::Database::init	(	const QString &	connName = `""`,
		const QString &	driverType = `""`
	)

protected

Initializes a database by connection name and driver type.

This method accepts (optional) connection name and driver type to establish a database connection. If both passed string parameters are empty, then either the default will be returned or a new database connection is returned using the default profile - if one is established. If neither of these conditions are met, this routine will throw an error.

If only a connection name is given but no driver, then either a persistant connection or a default profile must exist.

If both a name and driver is provided, then a clean database object is returned without any connection parameters set and the application programmer must set them.

NOTE: This method is implemented in such a way that it assumes it is part of the QSqlDatabase initialization phase upon object construction. You will see some implementation decisions based upon this expeectation.

Parameters

connName	Name of the connection to create
driverType	Type of driver/database to create. This is typically MySQL, PostgreSQL or SQLite.

Returns: QSqlDatabase The created database

References Isis::DatabaseFactory::create(), DoNotConnect, Isis::DatabaseFactory::getDefault(), Isis::DatabaseFactory::getInstance(), Isis::DatabaseFactory::getProfile(), init(), Isis::DatabaseFactory::isAvailable(), and Isis::DbProfile::isValid().

◆ isPersistant()

bool Isis::Database::isPersistant ( ) const

Checks persistancy state of a database instantiation.

This method tests to determine if this database connection is persistant so that future access can be utilized in this state.

Returns: bool True if persistant, otherwise false

References Isis::DatabaseFactory::getInstance(), and Isis::DatabaseFactory::isPersistant().

◆ makePersistant()

void Isis::Database::makePersistant ( )

Makes this instance persistant.

Database persistancy in this context means the database remains in whatever state the user leaves it in, such as open, and ensures that the configuration remains available for other uses of the same connection.

This feature is useful if you have a long running application that will make prepeated attempts to access the database using the same configuration parameters. It saves overhead and provides a guaranteed state of access. It can and perhaps should be closed when not used in between long accesses. This will prevent timeouts from the database.

The intended usefulness of the persistant database state is so that at anytime in the life or processing point in the program, the database connection is available.

Note that this uses the DatabaseFactory class to retain its persistancy.

See also: DatabaseFactory

References Isis::DatabaseFactory::add(), Isis::DatabaseFactory::getInstance(), and Isis::DatabaseFactory::isPersistant().

◆ Name()

QString Isis::Database::Name ( ) const

inline

Return the name of this database as specifed upon creation.

Returns: QString The name of this database

◆ remove()

void Isis::Database::remove ( const QString & name )

static

Removes the named database from pool.

This static method is required in order to remove a previous used Database from the database pool. Database configurations hang around after they are used. To completely remove them from application space, you must call this method.

NOTE: The Database destructor only ensure the connection is closed. It does not complete remove them. Persistant databases have their connect state preserved from one Database construction/instantiation to the next. This method is the only way to completely remove a database from global application space connectivity.

WARNING: Do not attempt to remove an active Database! This will cause a spurious warning from Qt and render the database inoperative!

Parameters

name	Name of database to remove (and destroy)

References Isis::DatabaseFactory::destroy(), and Isis::DatabaseFactory::getInstance().

◆ setAsDefault()

void Isis::Database::setAsDefault ( )

Sets this database connection/profile as the default.

Calling this method sets this database instance/connection as the default connection. It is added to the list of persistant connections and can be retreived at will at any point in an application. This will be true even if this instance is released.

It uses the DatabaseFactory class to register it as the default. Note that there is only one default ever and it is designated by name. By definition it is also marked as a persistant connection.

See also: DatabaseFactory

References Isis::DatabaseFactory::add(), Isis::DatabaseFactory::getInstance(), Isis::DatabaseFactory::isPersistant(), and Isis::DatabaseFactory::setDefault().

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

/usgs/pkgs/isis3.9.0_docs/ISIS3/isis/src/database/objs/Database/Database.h
/usgs/pkgs/isis3.9.0_docs/ISIS3/isis/src/database/objs/Database/Database.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ Access

Constructor & Destructor Documentation

◆ Database() [1/6]

◆ Database() [2/6]

◆ Database() [3/6]

◆ Database() [4/6]

◆ Database() [5/6]

◆ ~Database()

◆ Database() [6/6]

Member Function Documentation

◆ addAccessConfig()

◆ clone()

◆ configureAccess()

◆ getProfile()

◆ getSystemTables()

◆ getTables()

◆ getViews()

◆ init() [1/2]

◆ init() [2/2]

◆ isPersistant()

◆ makePersistant()

◆ Name()

◆ remove()

◆ setAsDefault()