DbAccess manages programatic access to a database through profiles. More...

#include <DbAccess.h>

Inheritance diagram for Isis::DbAccess:

Collaboration diagram for Isis::DbAccess:

Public Member Functions
	DbAccess ()

	DbAccess (const QString &dbaccFile, const QString &defProfileName="")
	Construct with a given database access configuration file.

	DbAccess (PvlObject &pvl, const QString &defProfileName="")
	Constructor that accepts a Database Pvl Object.

virtual	~DbAccess ()
	Destructor ensures everything is cleaned up properly.

int	profileCount () const
	Reports the number of user profiles to access this database.

bool	profileExists (const QString &profile) const
	Checks existance of a database user profile.

const DbProfile	getProfile (const QString &name="") const
	Retrieves the specified access profile.

const DbProfile	getProfile (int nth) const
	Returns the nth specified DbProfile in the list.

void	addProfile (const DbProfile &profile)
	Adds a profile to the database profile.

void	load (const QString &filename)
	Loads a Database access configuration file.

void	load (PvlObject &pvl)
	Load a database access profile configuration from a PvlObject.

QString	getDefaultProfileName () const
	Determine the name of the default profile.

bool	isValid () const
	Reports if this is a valid profile.

int	size () const
	Reports the number of keywords in this user profile.

void	setName (const QString &name)
	Set the name of this profile.

QString	Name () const
	Returns the name of this property.

bool	exists (const QString &key) const
	Checks for the existance of a keyword.

void	add (const QString &key, const QString &value="")
	Adds a keyword and value pair to the profile.

void	replace (const QString &key, const QString &value="")
	Adds a keyword and value pair to the profile.

void	remove (const QString &key)
	Removes a keyword from the profile.

int	count (const QString &key) const
	Report number of values in keyword.

QString	key (int nth) const
	Returns the nth key in the profile.

QString	value (const QString &key, int nth=0) const
	Returns the specified value for the given keyword.

QString	operator() (const QString &key, int nth=0) const
	Returns the specified value for the given keyword.

Protected Types
typedef CollectorMap< IString, PvlKeyword, NoCaseStringCompare >	KeyList

Protected Member Functions
void	loadkeys (PvlContainer &pvl)
	Loads DbProfile keys from the given Pvl construct.

const KeyList &	getKeyList () const
	Returns a reference to the key list.

Detailed Description

DbAccess manages programatic access to a database through profiles.

This class reads a Pvl formatted file and constructs access profiles on the fly from the contents. It is intended to specify any and all information sufficient to establish a database connection in software applications.

The input file to this class is typically created with an editor. It can contain any keyword = value combination. It must contain a Database object and may optionally contain Profile groups. The Database object can contain kewords such as User, Host, DbName, and so forth. Here is an example of what the file, named upc.conf, of this type would look like:

Object = Database
  Name = UPC
  Dbname = upc
  Type = PostgreSQL
  Host = "upcdb0.wr.usgs.gov"
  Port = 3309
  Description = "UPC provides GIS-capable image searches"
  AlternateHosts = "upcdb1.wr.usgs.gov"
EndObject

The code used to load and access this profile is:

DbAccess upc("upc.conf");

DbProfile default = upc.getProfile();

Isis::DbAccess

DbAccess manages programatic access to a database through profiles.

Definition DbAccess.h:106

Isis::DbProfile

A DbProfile is a container for access parameters to a database.

Definition DbProfile.h:51

Additionally, you can add specific profiles that alter some or all of the parameters contained in the Object section of the file. Simply add one or more Profile groups that grant or specify different access profiles for the given database. For example the example below names the Profile "upcread" and adds an additional user and password to the profile.

Object = Database
  Name = UPC
  Dbname = upc
  Type = PostgreSQL
  Host = "upcdb0.wr.usgs.gov"
  Port = 3309
  Description = "UPC provides GIS-capable image searches"
  AlternateHosts = "upcdb1.wr.usgs.gov"
  DefaultProfile = "upcread"
 
  Group = Profile
    Name = "upcread"
    User = "upcread"
    Password = "public"
  EndGroup
EndObject

To access this profile, use:

DbProfile upcread = upc.getProfile("upcread");

It will look for the Name keyword as the specifed named profile. What actually happens when the above code is invoked is all the keywords contained in the Database object, such as Dbname, Type, as well as Name are copied to a new dynamic profile named "upcread". Then any keywords found in the actual Profile group with Name = "upcread" are copied to the newly created dynamic one replacing any existing keywords with the ones found in the requested Profile. This ensures precedence is given to requested profiles and common parameters in the Database object are retained.

Author: 2006-07-01 Kris Becker

Member Typedef Documentation

◆ KeyList

typedef CollectorMap<IString, PvlKeyword, NoCaseStringCompare> Isis::DbProfile::KeyList

protectedinherited

Constructor & Destructor Documentation

◆ DbAccess() [1/3]

Isis::DbAccess::DbAccess ( )

inline

◆ DbAccess() [2/3]

Isis::DbAccess::DbAccess	(	const QString &	dbaccFile,
		const QString &	defProfileName = "" )

Construct with a given database access configuration file.

This constructor accepts the name of a Pvl formatted file that must contain a object named Database. It loads keywords in the order they occur in the object. Keywords should be unique - if not, previous keywords are silently replaced by subsequent occuring keywords.

Then all groups named Profile are loaded and established as additional, distinct access profiles. They all should have unique names. Subsequent profiles with the same name are replaced.

The caller may additionally provide the name of the default profile to use when none is given. If one is not provided, then should a keyword called DefaultProfile is searched for and the value of this keyword serves as the default profile. See the getProfile() method for details on how this situation is resolved.

Parameters

dbaccFile	Name of a Pvl formatted file containing the access specifications for a database
defProfileName	Optional name of the default access profile

References load().

◆ DbAccess() [3/3]

Isis::DbAccess::DbAccess	(	PvlObject &	pvl,
		const QString &	defProfileName = "" )

Constructor that accepts a Database Pvl Object.

The functionality of this constructor is exactly the same as file constructor except with a PvObject named "Database" as an argument.

Parameters

pvl	A Database PvlObject containing access information
defProfileName	Optional name of the default profile

References load().

◆ ~DbAccess()

virtual Isis::DbAccess::~DbAccess ( )

inlinevirtual

Destructor ensures everything is cleaned up properly.

Member Function Documentation

◆ add()

void Isis::DbProfile::add	(	const QString &	key,
		const QString &	value = "" )

inherited

Adds a keyword and value pair to the profile.

This method adds a keyword and value pair to the profile if it doesn't exist. If the keyword already exists,it appends the value to the existing keyword.

Parameters

key	Keyword to add or ammend
value	Value to add to the keyword

References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::add(), Isis::PvlKeyword::addValue(), Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::exists(), Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::get(), Isis::DbProfile::key(), and Isis::DbProfile::value().

Referenced by Isis::DatabaseFactory::addAccessProfile().

◆ addProfile()

void Isis::DbAccess::addProfile ( const DbProfile & profile )

inline

Adds a profile to the database profile.

Inheritors may add profiles to the user profile list. Note that duplicate profiles are not allowed, therefore existing profiles with the same name is replaced.

Parameters

profile Profile to add

References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::add(), and Isis::DbProfile::Name().

◆ count()

int Isis::DbProfile::count ( const QString & key ) const

inherited

Report number of values in keyword.

This method will return the number of values in the specified keyword. If the keyword does not exist, 0 is returned.

Parameters

key	Name of key to get value count for

Returns: int Number values in key, or 0 if the key does not exist

References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::exists(), Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::get(), Isis::DbProfile::key(), and Isis::PvlKeyword::size().

◆ exists()

bool Isis::DbProfile::exists ( const QString & key ) const

inlineinherited

Checks for the existance of a keyword.

Parameters

key	Name of keyword to check

Returns: bool True if it exists, false if it doesn't

References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::exists(), and Isis::DbProfile::key().

Referenced by Isis::Database::configureAccess(), getDefaultProfileName(), and Isis::LoadCSV::load().

◆ getDefaultProfileName()

QString Isis::DbAccess::getDefaultProfileName ( ) const

Determine the name of the default profile.

This method is called to determine the real name of the default profile as predetermined at load time. This determination is made either through the default specified in the configuration Database object, the DefaultProfile keyword, or provided by the application progirammer in the constructor.

Returns: QString Name of default profile it it can be determined otherwise an empty string is returned.

References Isis::DbProfile::exists(), and Isis::DbProfile::value().

Referenced by getProfile().

◆ getKeyList()

const KeyList & Isis::DbProfile::getKeyList ( ) const

inlineprotectedinherited

Returns a reference to the key list.

Direct access to the keyword container allows class developers some additional flexibility whilst maintaining integrity through the public interface.

Returns: const KeyList& Reference to keyword list

◆ getProfile() [1/2]

const DbProfile Isis::DbAccess::getProfile ( const QString & name = "" ) const

Retrieves the specified access profile.

This method retrieves the named profile. If no name is provided, the default profile is returned.

There are two ways to specify the default. The first source of a named default comes from within the configuration file. A keyword specified in the Database object section named DefaultProfile can specify a named profile, the value of the Name keyword in a Profile group. The second source comes from the application programmer. In the constructor call to this object, the application programmer can provide a named profile as the default, which could ultimately come from the user (interface).

If no default is specified, then only the keywords contained in the Database object section of the configuration file is returned when requesting an unnamed profile.

Parameters

name	Optional name of the profile to return

Returns: const DbProfile The specified profile. One should test the validatity of the profile returned as this is the only indication of success.

References Isis::DbProfile::DbProfile(), Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::exists(), Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::get(), and getDefaultProfileName().

◆ getProfile() [2/2]

const DbProfile Isis::DbAccess::getProfile ( int nth ) const

Returns the nth specified DbProfile in the list.

This method allows user to iterate through the list of DbProfiles in this access scheme. If the caller provides an index that exceeds the number contained, an exception is thrown. Use profileCount() to determine the number of profiles.

Parameters

nth	Zero-based index of profile to return

Returns: const DbProfile The requested nth profile

References Isis::DbProfile::DbProfile(), and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::getNth().

◆ isValid()

bool Isis::DbProfile::isValid ( ) const

inlineinherited

Reports if this is a valid profile.

A valid profile is simply defined to contain keys. If there are no keys defined for the profile, it is deemed invalid.

Returns: bool True if the profile is valid, therefore containing keys

References Isis::DbProfile::size().

Referenced by Isis::Database::init(), and Isis::Database::init().

◆ key()

QString Isis::DbProfile::key ( int nth ) const

inlineinherited

Returns the nth key in the profile.

This method returns the name of the nth keyword in the profile so one can iterate through all existing keys. Note that database passwords could be vulnerable to exposure via this method.

Keywords in the profile are sorted in alphabetical order and not in the order in which they are read.

Parameters

nth	Specifies the nth key in the profile

Returns: QString Name of nth keyword in the profile.

Exceptions

Out-of-range exception if the nth keyword does not exist

References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::key().

Referenced by Isis::DbProfile::add(), Isis::DbProfile::count(), Isis::DbProfile::exists(), Isis::DbProfile::loadkeys(), Isis::DbProfile::operator()(), Isis::DbProfile::remove(), Isis::DbProfile::replace(), and Isis::DbProfile::value().

◆ load() [1/2]

void Isis::DbAccess::load ( const QString & filename )

Loads a Database access configuration file.

Given the name of a file, it will open the file using Isis Pvl classes. See the load(pvl) class for additonal information what takes place in this method.

Note the file may use environment variables.

Parameters

filename Name of Pvl file to open.

References Isis::PvlObject::findObject(), and load().

Referenced by DbAccess(), DbAccess(), and load().

◆ load() [2/2]

void Isis::DbAccess::load ( PvlObject & pvl )

Load a database access profile configuration from a PvlObject.

This method loads all keywords found in the Object section of the PvlObject and then searches for each Group named Profile. Profile groups contain augmentations to the object keywords to add to or replace object level access specifications. Each profile group must contain a Name keyword to uniquely identify the (group) access parameters.

Profiles are loaded and stored in this object for subsequent access.

Parameters

pvl	A PvlObject that contains keywords and option Profile groups.

References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::add(), and Isis::DbProfile::loadkeys().

◆ loadkeys()

void Isis::DbProfile::loadkeys ( PvlContainer & pvl )

protectedinherited

Loads DbProfile keys from the given Pvl construct.

This method iterates through all keywords in the Pvl container and loads them into this property.

Parameters

pvl	Container of keywords that will be loaded

References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::add(), and Isis::DbProfile::key().

Referenced by Isis::DbProfile::DbProfile(), and load().

◆ Name()

QString Isis::DbProfile::Name ( ) const

inlineinherited

Returns the name of this property.

Returns: QString Name of this property

Referenced by Isis::DatabaseFactory::addProfile(), addProfile(), and Isis::Database::init().

◆ operator()()

QString Isis::DbProfile::operator()	(	const QString &	key,
		int	nth = 0 ) const

inherited

Returns the specified value for the given keyword.

This method returns a value from the specified keyword. If the keyword or the specified value does not exist, an exception is thrown.

Parameters

key	Name of keyword to return value for.
nth	Specifies the nth value in the keyword

Returns: QString The requested value in the keyword

References Isis::DbProfile::key(), and Isis::DbProfile::value().

◆ profileCount()

int Isis::DbAccess::profileCount ( ) const

inline

Reports the number of user profiles to access this database.

Returns: int Number access profiles

References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::size().

◆ profileExists()

bool Isis::DbAccess::profileExists ( const QString & profile ) const

inline

Checks existance of a database user profile.

Parameters

profile Name of profile to check for existance

Returns: bool True if the profile exists, false otherwise

References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::exists().

◆ remove()

void Isis::DbProfile::remove ( const QString & key )

inherited

Removes a keyword from the profile.

Parameters

key	Keyword to remove

References Isis::DbProfile::key(), and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::remove().

◆ replace()

void Isis::DbProfile::replace	(	const QString &	key,
		const QString &	value = "" )

inherited

Adds a keyword and value pair to the profile.

This method adds a keyword and value pair to the profile if it doesn't exist.

If the keyword already exists, it is deleted and replaced with this new keyword and value.

Parameters

key	Keyword to replace
value	Value to add to the keyword

References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::add(), Isis::DbProfile::key(), and Isis::DbProfile::value().

◆ setName()

void Isis::DbProfile::setName ( const QString & name )

inlineinherited

Set the name of this profile.

Parameters

name	QString used to set the name of this profile

◆ size()

int Isis::DbProfile::size ( ) const

inlineinherited

Reports the number of keywords in this user profile.

Returns: int Number keywords found in profile

References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::size().

Referenced by Isis::DbProfile::isValid().

◆ value()

QString Isis::DbProfile::value	(	const QString &	key,
		int	nth = 0 ) const

inherited

Returns the specified value for the given keyword.

This method returns a value from the specified keyword. If the keyword or the specified value does not exist, an exception is thrown.

Parameters

key	Name of keyword to return value for.
nth	Specifies the nth value in the keyword

Returns: QString The requested value in the keyword

References _FILEINFO_, Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::get(), Isis::DbProfile::key(), and Isis::IException::Programmer.

Referenced by Isis::DbProfile::add(), Isis::DbProfile::DbProfile(), getDefaultProfileName(), Isis::DbProfile::operator()(), and Isis::DbProfile::replace().

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

/Users/chkim/repos/ISIS3/isis/src/database/objs/DbAccess/DbAccess.h
/Users/chkim/repos/ISIS3/isis/src/database/objs/DbAccess/DbAccess.cpp

Public Member Functions

Protected Types

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ KeyList

Constructor & Destructor Documentation

◆ DbAccess() [1/3]

◆ DbAccess() [2/3]

◆ DbAccess() [3/3]

◆ ~DbAccess()

Member Function Documentation

◆ add()

◆ addProfile()

◆ count()

◆ exists()

◆ getDefaultProfileName()

◆ getKeyList()

◆ getProfile() [1/2]

◆ getProfile() [2/2]

◆ isValid()

◆ key()

◆ load() [1/2]

◆ load() [2/2]

◆ loadkeys()

◆ Name()

◆ operator()()

◆ profileCount()

◆ profileExists()

◆ remove()

◆ replace()

◆ setName()

◆ size()

◆ value()