NCBI C++ ToolKit
Public Types | Public Member Functions | Static Public Member Functions | Private Types | Private Member Functions | Static Private Member Functions | Private Attributes | Friends | List of all members
CSDB_ConnectionParam Class Reference

Search Toolkit Book for CSDB_ConnectionParam

Convenience class to initialize database connection parameters from URL-like strings and/or application configuration and/or hard-code. More...

#include <dbapi/simple/sdbapi.hpp>

+ Collaboration diagram for CSDB_ConnectionParam:

Public Types

enum  EComposeUrlFlags { fThrowIfIncomplete = 0x1 , fHidePassword = 0x2 , eThrowIfIncomplete = fThrowIfIncomplete , eAllowIncomplete = 0 }
 Flags affecting URL composition. More...
 
enum  EParam {
  eUsername , ePassword , ePasswordFile , ePasswordKeyID ,
  eService , ePort , eDatabase , eLoginTimeout ,
  eIOTimeout , eExclusiveServer , eUseConnPool , eConnPoolName ,
  eConnPoolMinSize , eConnPoolMaxSize , eConnPoolIdleTime , eConnPoolWaitTime ,
  eConnPoolAllowTempOverflow , eContinueAfterRaiserror , eConnPoolMaxConnUse , eLogMinorMessages ,
  eArgsString
}
 "Essential" (e.g. More...
 
enum  EWithOverrides { eWithoutOverrides , eWithOverrides }
 Whether to report values from configuration files, or just those set in code (which have a lower priority). More...
 
enum  ESetFlags { fAsDefault = 0x1 }
 Flags affecting parameter setting. More...
 
typedef int TComposeUrlFlags
 
typedef int TSetFlags
 

Public Member Functions

 CSDB_ConnectionParam (const string &url_string=kEmptyStr)
 Get database connection parameters from a string and from the application configuration. More...
 
string ComposeUrl (TComposeUrlFlags flags=0) const
 Compose database connection URL string out of this class. More...
 
bool IsEmpty (void) const
 
string Get (EParam param, EWithOverrides with_overrides=eWithoutOverrides) const
 Get one of the "essential" database connection parameters. More...
 
CSDB_ConnectionParamSet (EParam param, const string &value, TSetFlags flags=0)
 Set one of the "essential" database connection parameters, unless overridden in a configuration file. More...
 
CSDB_ConnectionParamSet (const string &url_string, TSetFlags flags=0)
 Merge existing settings with those from url_string. More...
 
CSDB_ConnectionParamSet (const CSDB_ConnectionParam &param, TSetFlags flags=0)
 Merge existing settings with those from param. More...
 
const CUrlArgsGetArgs (void) const
 Access to additional (e.g. More...
 
CUrlArgsGetArgs (void)
 Access to additional (e.g. More...
 
 CSDB_ConnectionParam (const CSDB_ConnectionParam &param)
 Copy ctor (explicit, to avoid accidental copying) More...
 
CSDB_ConnectionParamoperator= (const CSDB_ConnectionParam &param)
 Assignment. More...
 

Static Public Member Functions

static void SetGlobalDecryptor (CRef< CSDB_Decryptor > decryptor)
 Use the specified password decryptor. More...
 
static CRef< CSDB_DecryptorGetGlobalDecryptor (void)
 Get the current password decryptor, if any. More...
 

Private Types

typedef map< EParam, stringTParamMap
 Map of any parameters set in the configuration file, which override those set in code. More...
 

Private Member Functions

void x_FillParamMap (void)
 Populate m_ParamMap according to the current server or service name. More...
 
void x_FillLowerParams (CDBConnParamsBase *params) const
 Fill parameters for low-level DBAPI from what is set here and in the configuration file. More...
 
void x_FillBoolParam (CDBConnParamsBase *params, const string &name, EParam id) const
 
string x_GetPassword () const
 Determine what password to use, accounting for possible encryption or indirection. More...
 
void x_ReportOverride (const CTempString &name, CTempString code_value, CTempString reg_value) const
 

Static Private Member Functions

static const char * x_GetName (EParam param)
 
static bool x_IsKnownArg (const string &name)
 

Private Attributes

CUrl m_Url
 URL storing all parameters set in code. More...
 
TParamMap m_ParamMap
 

Friends

class CSDBAPI
 
class CDatabaseImpl
 

Detailed Description

Convenience class to initialize database connection parameters from URL-like strings and/or application configuration and/or hard-code.

Definition at line 932 of file sdbapi.hpp.

Member Typedef Documentation

◆ TComposeUrlFlags

Definition at line 994 of file sdbapi.hpp.

◆ TParamMap

Map of any parameters set in the configuration file, which override those set in code.

Definition at line 1130 of file sdbapi.hpp.

◆ TSetFlags

Definition at line 1055 of file sdbapi.hpp.

Member Enumeration Documentation

◆ EComposeUrlFlags

Flags affecting URL composition.

See also
ComposeUrl
Enumerator
fThrowIfIncomplete 

Throw an exception if missing any "essential" parameters.

(It's normally necessary to have the server name, the database name, the username, and either a password or a password file.)

fHidePassword 
eThrowIfIncomplete 

Obscure passwords.

eAllowIncomplete 

Definition at line 984 of file sdbapi.hpp.

◆ EParam

"Essential" (e.g.

those located before '?' in the URL) database connection parameters

Enumerator
eUsername 
ePassword 
ePasswordFile 
ePasswordKeyID 
eService 

Named service, interfaces-file alias, or raw server name, per http://ncbi.github.io/cxx-toolkit/pages/ch_dbapi#ch_dbapi.Getting_started.

Note
In the interfaces file, if there are multiple choices for a given alias, FreeTDS (used by SDBAPI) will always attempt to connect to the last one, even if it's out of commission.
ePort 

DB server's port (when not using an alias or named service)

eDatabase 
eLoginTimeout 
eIOTimeout 
eExclusiveServer 
eUseConnPool 
eConnPoolName 
eConnPoolMinSize 
eConnPoolMaxSize 
eConnPoolIdleTime 
eConnPoolWaitTime 
eConnPoolAllowTempOverflow 
eContinueAfterRaiserror 
eConnPoolMaxConnUse 
eLogMinorMessages 
eArgsString 

Definition at line 1006 of file sdbapi.hpp.

◆ ESetFlags

Flags affecting parameter setting.

See also
Set
Enumerator
fAsDefault 

The specified value is merely a default, which Set should ignore if a non-empty setting for that parameter is already present.

Definition at line 1050 of file sdbapi.hpp.

◆ EWithOverrides

Whether to report values from configuration files, or just those set in code (which have a lower priority).

Enumerator
eWithoutOverrides 
eWithOverrides 

Definition at line 1037 of file sdbapi.hpp.

Constructor & Destructor Documentation

◆ CSDB_ConnectionParam() [1/2]

CSDB_ConnectionParam::CSDB_ConnectionParam ( const string url_string = kEmptyStr)
inline

Get database connection parameters from a string and from the application configuration.

Parameters
url_stringGet connection parameters from this URL-like string, formatted as: dbapi://[username[:password]@][server[:port]][/database][?k1=v1;...] or dbapi://[username[:password]@][service][/database][?k1=v1;...] or service

Each token must be URL-encoded.

Also application configuration is looked for section with name "service.dbservice" ("service" can be passed to the ctor or to Set() method). If such section exists then the following parameters are read from it, and if present will override corresponding parameters extracted from the URL or specified later via Set.

  • username
  • password
  • service
  • port
  • database
  • args
  • login_timeout
  • io_timeout
  • exclusive_server
  • use_conn_pool
  • conn_pool_name
  • conn_pool_minsize
  • conn_pool_maxsize
  • conn_pool_idle_time
  • conn_pool_wait_time
  • conn_pool_allow_temp_overflow
  • continue_after_raiserror
  • conn_pool_max_conn_use
  • log_minor_messages
  • password_file
  • password_key

Most of these parameters can also come as named URL parameters; "args" is a catch-all for any other parameters, which can appear directly as URL parameters. (Settings from the configuration file's "args" string override URL parameters on an individual basis.)

Definition at line 1458 of file sdbapi.hpp.

References CUrl::GetArgs(), m_Url, CUrl::SetIsGeneric(), CUrl::SetScheme(), CUrl::SetUrl(), NStr::StartsWith(), and x_FillParamMap().

◆ CSDB_ConnectionParam() [2/2]

CSDB_ConnectionParam::CSDB_ConnectionParam ( const CSDB_ConnectionParam param)
inlineexplicit

Copy ctor (explicit, to avoid accidental copying)

Definition at line 1477 of file sdbapi.hpp.

Member Function Documentation

◆ ComposeUrl()

string CSDB_ConnectionParam::ComposeUrl ( TComposeUrlFlags  flags = 0) const

Compose database connection URL string out of this class.

Parameters
flagsAny desired flags from EComposeUrlFlags.

Definition at line 1030 of file sdbapi.cpp.

References CUrl::ComposeUrl(), CUrlArgs::eAmp_Char, ctll::empty(), ePasswordFile, eRetriable_No, fHidePassword, flags, fThrowIfIncomplete, Get(), CUrl::GetHost(), CUrl::GetPassword(), CUrl::GetPath(), CUrl::GetUser(), m_Url, NCBI_THROW, and CUrl::SetPassword().

◆ Get()

string CSDB_ConnectionParam::Get ( EParam  param,
EWithOverrides  with_overrides = eWithoutOverrides 
) const
inline

◆ GetArgs() [1/2]

CUrlArgs & CSDB_ConnectionParam::GetArgs ( void  )
inline

Access to additional (e.g.

those located after '?' in the URL) database connection parameters

Definition at line 1490 of file sdbapi.hpp.

References CUrl::GetArgs(), and m_Url.

◆ GetArgs() [2/2]

const CUrlArgs & CSDB_ConnectionParam::GetArgs ( void  ) const
inline

Access to additional (e.g.

those located after '?' in the URL) database connection parameters

Definition at line 1496 of file sdbapi.hpp.

References CUrl::GetArgs(), and m_Url.

◆ GetGlobalDecryptor()

CRef< CSDB_Decryptor > CSDB_ConnectionParam::GetGlobalDecryptor ( void  )
static

Get the current password decryptor, if any.

See also
SetGlobalDecryptor

Definition at line 1018 of file sdbapi.cpp.

References s_Decryptor, and s_DecryptorInitialized.

Referenced by x_GetPassword().

◆ IsEmpty()

bool CSDB_ConnectionParam::IsEmpty ( void  ) const

◆ operator=()

CSDB_ConnectionParam & CSDB_ConnectionParam::operator= ( const CSDB_ConnectionParam param)
inline

Assignment.

Definition at line 1482 of file sdbapi.hpp.

References m_ParamMap, and m_Url.

◆ Set() [1/3]

CSDB_ConnectionParam & CSDB_ConnectionParam::Set ( const CSDB_ConnectionParam param,
TSetFlags  flags = 0 
)

Merge existing settings with those from param.

The flags indicate how to resolve conflicts.

Definition at line 1073 of file sdbapi.cpp.

References eArgsString, eUsername, flags, Get(), i, and Set().

◆ Set() [2/3]

CSDB_ConnectionParam & CSDB_ConnectionParam::Set ( const string url_string,
TSetFlags  flags = 0 
)
inline

Merge existing settings with those from url_string.

The flags indicate how to resolve conflicts.

Definition at line 1681 of file sdbapi.hpp.

References flags, and Set().

◆ Set() [3/3]

CSDB_ConnectionParam & CSDB_ConnectionParam::Set ( EParam  param,
const string value,
TSetFlags  flags = 0 
)
inline

Set one of the "essential" database connection parameters, unless overridden in a configuration file.

Settings from [*.dbservice] sections always take precedence because they're more visible and easier to adjust.

Parameters
paramParameter to set
valueThe value to set the parameter to. Empty string un-sets it.
flagsAny desired flags from ESetFlags.

Definition at line 1604 of file sdbapi.hpp.

References _ASSERT, eArgsString, eConnPoolAllowTempOverflow, eConnPoolIdleTime, eConnPoolMaxConnUse, eConnPoolMaxSize, eConnPoolMinSize, eConnPoolName, eConnPoolWaitTime, eContinueAfterRaiserror, eDatabase, eExclusiveServer, eIOTimeout, eLoginTimeout, eLogMinorMessages, ctll::empty(), map_checker< Container >::end(), ePassword, ePasswordFile, ePasswordKeyID, ePort, eService, eUseConnPool, eUsername, fAsDefault, map_checker< Container >::find(), flags, Get(), CUrlArgs::GetArgs(), CUrl::GetArgs(), CUrlArgs::IsSetValue(), kEmptyStr, m_ParamMap, m_Url, CUrl::SetHost(), CUrl::SetPassword(), CUrl::SetPath(), CUrl::SetPort(), CUrlArgs_Parser::SetQueryString(), CUrl::SetUser(), CUrlArgs::SetValue(), rapidjson::value, x_FillParamMap(), x_GetName(), and x_ReportOverride().

Referenced by CSdbapiTest::Run(), Set(), CSdbapiSimpleApp::SetupDb(), and CDBLBClientApp::x_RunLookup().

◆ SetGlobalDecryptor()

void CSDB_ConnectionParam::SetGlobalDecryptor ( CRef< CSDB_Decryptor decryptor)
static

Use the specified password decryptor.

See also
GetGlobalDecryptor

Definition at line 1011 of file sdbapi.cpp.

References s_Decryptor, and s_DecryptorInitialized.

◆ x_FillBoolParam()

void CSDB_ConnectionParam::x_FillBoolParam ( CDBConnParamsBase params,
const string name,
EParam  id 
) const
private

◆ x_FillLowerParams()

void CSDB_ConnectionParam::x_FillLowerParams ( CDBConnParamsBase params) const
private

◆ x_FillParamMap()

void CSDB_ConnectionParam::x_FillParamMap ( void  )
private

◆ x_GetName()

const char * CSDB_ConnectionParam::x_GetName ( EParam  param)
inlinestaticprivate

◆ x_GetPassword()

string CSDB_ConnectionParam::x_GetPassword ( ) const
private

◆ x_IsKnownArg()

bool CSDB_ConnectionParam::x_IsKnownArg ( const string name)
inlinestaticprivate

Definition at line 1535 of file sdbapi.hpp.

References eArgsString, eLoginTimeout, and x_GetName().

Referenced by x_FillLowerParams(), and x_ReportOverride().

◆ x_ReportOverride()

void CSDB_ConnectionParam::x_ReportOverride ( const CTempString name,
CTempString  code_value,
CTempString  reg_value 
) const
private

Friends And Related Function Documentation

◆ CDatabaseImpl

friend class CDatabaseImpl
friend

Definition at line 1102 of file sdbapi.hpp.

◆ CSDBAPI

friend class CSDBAPI
friend

Definition at line 1101 of file sdbapi.hpp.

Member Data Documentation

◆ m_ParamMap

TParamMap CSDB_ConnectionParam::m_ParamMap
private

Definition at line 1131 of file sdbapi.hpp.

Referenced by Get(), operator=(), Set(), x_FillLowerParams(), x_FillParamMap(), and x_GetPassword().

◆ m_Url

CUrl CSDB_ConnectionParam::m_Url
mutableprivate

URL storing all parameters set in code.

Definition at line 1126 of file sdbapi.hpp.

Referenced by ComposeUrl(), CSDB_ConnectionParam(), Get(), GetArgs(), IsEmpty(), operator=(), Set(), x_FillLowerParams(), x_FillParamMap(), and x_ReportOverride().


The documentation for this class was generated from the following files:
Modified on Wed Jul 17 13:20:09 2024 by modify_doxy.py rev. 669887