|
Isis 3.0 Object Programmers' Reference |
Home |
#include <DbAccess.h>
Inheritance diagram for Isis::DbAccess:
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:
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.
Definition at line 119 of file DbAccess.h.
Public Member Functions | |
| DbAccess () | |
| DbAccess (const std::string &dbaccFile, const std::string &defProfileName="") | |
| Construct with a given database access configuration file. | |
| DbAccess (PvlObject &pvl, const std::string &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 std::string &profile) const |
| Checks existance of a database user profile. | |
| const DbProfile | getProfile (const std::string &name="") const throw (iException &) |
| Retrieves the specified access profile. | |
| const DbProfile | getProfile (int nth) const throw (iException &) |
| Returns the nth specified DbProfile in the list. | |
| void | addProfile (const DbProfile &profile) |
| Adds a profile to the database profile. | |
| void | load (const std::string &filename) |
| Loads a Database access configuration file. | |
| void | load (PvlObject &pvl) |
| Load a database access profile configuration from a PvlObject. | |
| std::string | 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 std::string &name) |
| Set the name of this profile. | |
| std::string | Name () const |
| Returns the name of this property. | |
| bool | exists (const std::string &key) const |
| Checks for the existance of a keyword. | |
| void | add (const std::string &key, const std::string &value="") |
| Adds a keyword and value pair to the profile. | |
| void | replace (const std::string &key, const std::string &value="") |
| Adds a keyword and value pair to the profile. | |
| void | remove (const std::string &key) |
| Removes a keyword from the profile. | |
| int | count (const std::string &key) const |
| Report number of values in keyword. | |
| std::string | key (int nth) const |
| Returns the nth key in the profile. | |
| std::string | value (const std::string &key, int nth=0) const |
| Returns the specified value for the given keyword. | |
| std::string | operator() (const std::string &key, int nth=0) const |
| Returns the specified value for the given keyword. | |
Protected Types | |
|
typedef CollectorMap< std::string, 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. | |
Private Types | |
| typedef CollectorMap< std::string, DbProfile, NoCaseStringCompare > | ProfileList |
| Define the container for the DbAccess key word list. | |
Private Attributes | |
| std::string | _defProfileName |
| Name of default profile. | |
| ProfileList | _profiles |
| List of profiles. | |
typedef CollectorMap<std::string,DbProfile,NoCaseStringCompare> Isis::DbAccess::ProfileList [private] |
| Isis::DbAccess::DbAccess | ( | const std::string & | dbaccFile, | |
| const std::string & | 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.
| dbaccFile | Name of a Pvl formatted file containing the access specifications for a database | |
| defProfileName | Optional name of the default access profile |
Definition at line 61 of file DbAccess.cpp.
References load().
| Isis::DbAccess::DbAccess | ( | PvlObject & | pvl, | |
| const std::string & | 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.
| pvl | A Database PvlObject containing access information | |
| defProfileName | Optional name of the default profile |
Definition at line 77 of file DbAccess.cpp.
| virtual Isis::DbAccess::~DbAccess | ( | ) | [inline, virtual] |
| void Isis::DbProfile::add | ( | const std::string & | key, | |
| const std::string & | 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.
| key | Keyword to add or ammend | |
| value | Value to add to the keyword |
Definition at line 95 of file DbProfile.cpp.
References Isis::DbProfile::_keys, Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::add(), Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::exists(), and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::get().
| 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.
| profile | Profile to add |
Definition at line 167 of file DbAccess.h.
References _profiles, and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::add().
| int Isis::DbProfile::count | ( | const std::string & | 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.
| key | Name of key to get value count for |
Definition at line 140 of file DbProfile.cpp.
References Isis::DbProfile::_keys, Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::exists(), and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::get().
Referenced by Isis::Gruen::ConfKey().
| bool Isis::DbProfile::exists | ( | const std::string & | key | ) | const [inline, inherited] |
Checks for the existance of a keyword.
| key | Name of keyword to check |
Definition at line 121 of file DbProfile.h.
References Isis::DbProfile::_keys, and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::exists().
Referenced by Isis::Database::configureAccess(), Isis::Gruen::ConfKey(), getDefaultProfileName(), and Isis::Gruen::ParameterKey().
| std::string 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.
Definition at line 205 of file DbAccess.cpp.
References _defProfileName, Isis::DbProfile::exists(), and Isis::DbProfile::value().
| const KeyList& Isis::DbProfile::getKeyList | ( | ) | const [inline, protected, inherited] |
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.
Definition at line 161 of file DbProfile.h.
References Isis::DbProfile::_keys.
| const DbProfile Isis::DbAccess::getProfile | ( | int | nth | ) | const throw (iException &) |
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.
| nth | Zero-based index of profile to return |
Definition at line 142 of file DbAccess.cpp.
References Isis::DbProfile::Name().
| const DbProfile Isis::DbAccess::getProfile | ( | const std::string & | name = "" |
) | const throw (iException &) |
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.
| name | Optional name of the profile to return |
Definition at line 107 of file DbAccess.cpp.
| bool Isis::DbProfile::isValid | ( | ) | const [inline, inherited] |
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.
Definition at line 91 of file DbProfile.h.
References Isis::DbProfile::size().
Referenced by Isis::Database::init().
| std::string Isis::DbProfile::key | ( | int | nth | ) | const [inline, inherited] |
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.
| nth | Specifies the nth key in the profile |
| Out-of-range | exception if the nth keyword does not exist |
Definition at line 145 of file DbProfile.h.
References Isis::DbProfile::_keys, and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::key().
Referenced by Isis::DbProfile::loadkeys().
| 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.
| pvl | A PvlObject that contains keywords and option Profile groups. |
Definition at line 177 of file DbAccess.cpp.
References _profiles, Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::add(), Isis::DbProfile::loadkeys(), and pvl().
| void Isis::DbAccess::load | ( | const std::string & | 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.
| filename | Name of Pvl file to open. |
Definition at line 158 of file DbAccess.cpp.
References pvl().
Referenced by DbAccess().
| void Isis::DbProfile::loadkeys | ( | PvlContainer & | pvl | ) | [protected, inherited] |
Loads DbProfile keys from the given Pvl construct.
This method iterates through all keywords in the Pvl container and loads them into this property.
| pvl | Container of keywords that will be loaded |
Definition at line 197 of file DbProfile.cpp.
References Isis::DbProfile::_keys, Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::add(), Isis::PvlContainer::Begin(), Isis::PvlContainer::End(), Isis::DbProfile::key(), and pvl().
Referenced by Isis::DbProfile::DbProfile(), and load().
| std::string Isis::DbProfile::Name | ( | ) | const [inline, inherited] |
Returns the name of this property.
Definition at line 112 of file DbProfile.h.
References Isis::DbProfile::_name.
Referenced by Isis::DatabaseFactory::addAccessProfile(), Isis::DatabaseFactory::addProfile(), getProfile(), Isis::Database::init(), and Isis::Gruen::init().
| std::string Isis::DbProfile::operator() | ( | const std::string & | 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.
| key | Name of keyword to return value for. | |
| nth | Specifies the nth value in the keyword |
Definition at line 185 of file DbProfile.cpp.
References Isis::DbProfile::value().
| int Isis::DbAccess::profileCount | ( | ) | const [inline] |
Reports the number of user profiles to access this database.
Definition at line 140 of file DbAccess.h.
References _profiles, and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::size().
| bool Isis::DbAccess::profileExists | ( | const std::string & | profile | ) | const [inline] |
Checks existance of a database user profile.
| profile | Name of profile to check for existance |
Definition at line 149 of file DbAccess.h.
References _profiles, and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::exists().
| void Isis::DbProfile::remove | ( | const std::string & | key | ) | [inherited] |
Removes a keyword from the profile.
| key | Keyword to remove |
Definition at line 126 of file DbProfile.cpp.
References Isis::DbProfile::_keys, and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::remove().
| void Isis::DbProfile::replace | ( | const std::string & | key, | |
| const std::string & | 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.
| key | Keyword to replace | |
| value | Value to add to the keyword |
Definition at line 116 of file DbProfile.cpp.
References Isis::DbProfile::_keys, and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::add().
| void Isis::DbProfile::setName | ( | const std::string & | name | ) | [inline, inherited] |
Set the name of this profile.
| name | iString used to set the name of this profile |
Definition at line 105 of file DbProfile.h.
References Isis::DbProfile::_name.
Referenced by Isis::Gruen::init().
| int Isis::DbProfile::size | ( | ) | const [inline, inherited] |
Reports the number of keywords in this user profile.
Definition at line 98 of file DbProfile.h.
References Isis::DbProfile::_keys, and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::size().
Referenced by Isis::DbProfile::isValid().
| std::string Isis::DbProfile::value | ( | const std::string & | 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.
| key | Name of keyword to return value for. | |
| nth | Specifies the nth value in the keyword |
Definition at line 159 of file DbProfile.cpp.
References _FILEINFO_, Isis::DbProfile::_keys, Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::get(), and Isis::iException::Message().
Referenced by Isis::Gruen::ConfKey(), Isis::DbProfile::DbProfile(), getDefaultProfileName(), and Isis::DbProfile::operator()().
std::string Isis::DbAccess::_defProfileName [private] |
Name of default profile.
Definition at line 177 of file DbAccess.h.
Referenced by getDefaultProfileName().
ProfileList Isis::DbAccess::_profiles [private] |
List of profiles.
Definition at line 178 of file DbAccess.h.
Referenced by addProfile(), load(), profileCount(), and profileExists().