USGS Astrogeology Isis API

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.

Definition at line 84 of file Database.h.


Public Types
enum	Access { Connect, DoNotConnect }
	Access status for database creation. More...
Public Member Functions
	Database ()
	Default database constructor.
	Database (Access dbConn)
	Construction of the unamed database with optional connection.
	Database (const std::string &connName, const std::string &driverType)
	Create database connection specified by name and driver type.
	Database (const std::string &name, Access dbConn=Connect)
	Create a named database object.
	Database (const DbProfile &profile, Access dbConn=Connect)
	Create database connection using the supplied DbProfile.
virtual	~Database ()
	Database destructor.
std::string	Name () const
	Return the name of this database as specifed upon creation.
void	makePersistant ()
	Makes this instance persistant.
bool	isPersistant () const
	Checks persistancy state of a database instantiation.
void	setAsDefault ()
	Sets this database connection/profile as the default.
Database	clone (const std::string &name) const
	Clones this database into another giving it another name.
std::vector< std::string >	getTables () const
	Returns a vector string containing all the tables in the database.
std::vector< std::string >	getViews () const
	Returns a vector string containing all views within the database.
std::vector< std::string >	getSystemTables () const
	Returns vector strings of all available system tables in the database.
Static Public Member Functions
static void	remove (const std::string &name)
	Removes the named database from pool.
static bool	addAccessConfig (const std::string &confFile)
	Adds a user specifed access configuration file to system.
static DbProfile	getProfile (const std::string &name)
	Retrieves the named database access profile.
Protected Member Functions
	Database (const QSqlDatabase &other, const std::string &name)
	Constructor creates a clone/copy from an existing one.
QSqlDatabase	init (const DbProfile &profile, Access dbConn=Connect)
	Create and initialize a new database connection from a DbProfile.
QSqlDatabase	init (const std::string &name="", const std::string &driverType="")
	Initializes a database by connection name and driver type.
void	configureAccess (QSqlDatabase &db, const DbProfile &profile)
	Set access parameters from a database DbProfile access specification.
Private Member Functions
void	tossDbError (const std::string &message, const char *f, int l) const throw (iException &)
	Generic exception tosser.
Private Attributes
std::string	_name
	Needed due to peculiar issues with Database construction techniques Name of the connection.
Static Private Attributes
static std::string	_actualConnectionName = ""

Member Enumeration Documentation

enum Isis::Database::Access

Access status for database creation.

Enumerator:

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

Definition at line 87 of file Database.h.

Constructor & Destructor Documentation

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.

Definition at line 46 of file Database.cpp.

Referenced by clone().

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.

Definition at line 66 of file Database.cpp.

References _actualConnectionName, _FILEINFO_, _name, Connect, and tossDbError().

Isis::Database::Database	(	const std::string &	connName,
		const std::string &	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.

Definition at line 117 of file Database.cpp.

References _actualConnectionName, and _name.

Isis::Database::Database	(	const std::string &	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.

Definition at line 88 of file Database.cpp.

References _actualConnectionName, _FILEINFO_, _name, Connect, and tossDbError().

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.

Definition at line 137 of file Database.cpp.

References _actualConnectionName, _FILEINFO_, _name, Connect, and tossDbError().

Isis::Database::Database	(	const QSqlDatabase &	other,
		const std::string &	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)

Definition at line 159 of file Database.cpp.

Member Function Documentation

bool Isis::Database::addAccessConfig ( const std::string & 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.

Definition at line 286 of file Database.cpp.

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

Database::Database Isis::Database::clone

(

const std::string &

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:: Database::Database The cloned database

Definition at line 512 of file Database.cpp.

References Database().

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.

Definition at line 468 of file Database.cpp.

References Isis::DbProfile::exists(), and Isis::iString::ToQt().

DbProfile Isis::Database::getProfile ( const std::string & 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.

Definition at line 323 of file Database.cpp.

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

std::vector< std::string > 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<std::string> List of system tables with the database

Definition at line 549 of file Database.cpp.

References Isis::iString::ToStd().

std::vector< std::string > 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<std::string> List of tables in the database

Definition at line 524 of file Database.cpp.

References Isis::iString::ToStd().

std::vector< std::string > 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<std::string> List of all accessable views in the database

Definition at line 537 of file Database.cpp.

References Isis::iString::ToStd().

QSqlDatabase Isis::Database::init	(	const std::string &	connName = `""`,
		const std::string &	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

Definition at line 354 of file Database.cpp.

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

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.

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

Definition at line 414 of file Database.cpp.

References _FILEINFO_, Isis::DbProfile::isValid(), Isis::iException::Message(), and Isis::DbProfile::Name().

Referenced by init().

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

Definition at line 218 of file Database.cpp.

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

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

Definition at line 202 of file Database.cpp.

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

std::string Isis::Database::Name ( ) const [inline]

Return the name of this database as specifed upon creation.

Returns:: std::string The name of this database

Definition at line 104 of file Database.h.

References _name.

void Isis::Database::remove ( const std::string & 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)

Definition at line 265 of file Database.cpp.

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

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

Definition at line 237 of file Database.cpp.

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

void Isis::Database::tossDbError	(	const std::string &	message,
		const char *	f,
		int	l
	)	const throw (iException &) `[private]`

Generic exception tosser.

This method is used from within this class to construct and deploy an exception when an error occurs in some of the methods in this class.

Parameters:

	message	Text of message to include in exception
	f	Name of method initiating the exception
	l	Line number the error occured

Definition at line 563 of file Database.cpp.

References Isis::iException::Message(), and Isis::iString::ToStd().

Referenced by Database().

Isis::Database Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation