I_DriverContext Class Reference
[Database Server Interfaces]

Search Toolkit Book for I_DriverContext

#include <interfaces.hpp>

Inheritance diagram for I_DriverContext:

Detailed Description

Definition at line 732 of file interfaces.hpp.

Public Types

typedef int TConnectionMode

enum EConnectionMode { fBcpIn = 0x1, fPasswordEncrypted = 0x2, fDoNotConnect = 0x4 }

Connection mode. More...

enum ECapability { eBcp, eReturnITDescriptors, eReturnComputeResults }

Report if the driver supports this functionality. More...

Public Member Functions

virtual ~I_DriverContext (void)

virtual bool SetLoginTimeout (unsigned int nof_secs=0)=0

Set login timeout.

virtual bool SetTimeout (unsigned int nof_secs=0)=0

Set connection timeouts.

virtual unsigned int GetLoginTimeout (void) const =0

Get login timeout.

virtual unsigned int GetTimeout (void) const =0

Get connection timeout.

virtual bool SetMaxTextImageSize (size_t nof_bytes)=0

Set maximal size for Text and Image objects.

CDB_Connection * Connect (const string &srv_name, const string &user_name, const string &passwd, TConnectionMode mode, bool reusable=false, const string &pool_name=kEmptyStr)

Create new connection to specified server (or service) within this context.

CDB_Connection * ConnectValidated (const string &srv_name, const string &user_name, const string &passwd, IConnValidator &validator, TConnectionMode mode=0, bool reusable=false, const string &pool_name=kEmptyStr)

Create new connection to specified server (within this context).

virtual CDB_Connection * MakeConnection (const CDBConnParams &params)=0

Create connection object using Load Balancer / connection factory.

virtual unsigned int NofConnections (const string &srv_name="", const string &pool_name="") const =0

Return number of currently open connections in this context.

virtual void PushCntxMsgHandler (CDB_UserHandler *h, EOwnership ownership=eNoOwnership)=0

Add message handler "h" to process 'context-wide' (not bound to any particular connection) error messages.

virtual void PopCntxMsgHandler (CDB_UserHandler *h)=0

Remove message handler "h" and all handlers above it in the stack.

virtual void PushDefConnMsgHandler (CDB_UserHandler *h, EOwnership ownership=eNoOwnership)=0

Add `per-connection' err.message handler "h" to the stack of default handlers which are inherited by all newly created connections.

virtual void PopDefConnMsgHandler (CDB_UserHandler *h)=0

Remove `per-connection' mess.

virtual bool IsAbleTo (ECapability cpb) const =0

Check if a driver is acle to provide necessary functionality.

virtual void CloseUnusedConnections (const string &srv_name=kEmptyStr, const string &pool_name=kEmptyStr)=0

Close reusable deleted connections for specified server and/or pool.

virtual void SetApplicationName (const string &app_name)=0

Set application name.

virtual string GetApplicationName (void) const =0

Return application name.

virtual void SetHostName (const string &host_name)=0

Set host name.

virtual string GetHostName (void) const =0

Get host name.

Protected Member Functions

I_DriverContext (void)

virtual CDB_Connection * MakePooledConnection (const CDBConnParams &params)=0

Create connection object WITHOUT using of Load Balancer / connection factory.

Friends

class IDBConnectionFactory

Member Typedef Documentation

typedef int I_DriverContext::TConnectionMode

Definition at line 749 of file interfaces.hpp.

Member Enumeration Documentation

enum I_DriverContext::ECapability

Report if the driver supports this functionality.

Enumerator:

eBcp

eReturnITDescriptors

eReturnComputeResults

Definition at line 999 of file interfaces.hpp.

enum I_DriverContext::EConnectionMode

Connection mode.

Enumerator:

fBcpIn

fPasswordEncrypted

fDoNotConnect

Definition at line 742 of file interfaces.hpp.

Constructor & Destructor Documentation

I_DriverContext::I_DriverContext ( void ) [protected]

Definition at line 266 of file interfaces.cpp.

I_DriverContext::~I_DriverContext ( void ) [virtual]

Definition at line 271 of file interfaces.cpp.

Member Function Documentation

virtual void I_DriverContext::CloseUnusedConnections ( const string & srv_name = kEmptyStr,

const string & pool_name = kEmptyStr

) [pure virtual]

Close reusable deleted connections for specified server and/or pool.

Parameters:

srv_name Server/Service name.

pool_name Name of connection pool.

Implemented in impl::CDriverContext.

CDB_Connection * I_DriverContext::Connect ( const string & srv_name,

const string & user_name,

const string & passwd,

TConnectionMode mode,

bool reusable = false,

const string & pool_name = kEmptyStr

)

Create new connection to specified server (or service) within this context.

Parameters:

srv_name Server/Service name. This parameter can be a SERVER name (host name, DNS alias name, or one of the names found in interfaces file) or an IP address. This parameter can also be a SERVICE name, which is defined by Load Balancer framework. In order to enable using of LB service names you have to call DBLB_INSTALL_DEFAULT() macro before any other DBAPI method.

user_name User name.

passwd User password.

mode Connection mode.

reusable If set to TRUE, then return connection into a connection pool on deletion.

pool_name Name of a pool to which this connection is going to belong.

Returns:
Connection object on success, NULL on error.
NOTE:
It is your responsibility to delete the returned connection object. reusable - controls connection pooling mechanism. If it is set to true then a connection will be added to a pool of connections instead of closing.
srv_name, user_name and passwd may be set to empty string.
If pool_name is provided then connection will be taken from a pool having this name if a pool is not empty.
It is your responsibility to put connections with the same server/user/password values in a pool.
If a pool name is not provided but a server name (srv_name) is provided instead then connection with the same name will be taken from a pool of connections if a pool is not empty.
If a pool is empty then new connection will be created unless you passed mode = fDoNotConnect. In this case NULL will be returned.
If you did not provide either a pool name or a server name then NULL will be returned.
Definition at line 277 of file interfaces.cpp.
References MakeConnection().
Referenced by CBlobLoader::CBlobLoader(), CBlobRetriever::CBlobRetriever(), CDbapiSampleApp::CreateConnection(), CBlobStoreDynamic::GetConn(), main(), MergeExternal(), CDemoeApp::Run(), CDemoApp::RunSample(), and CId2FetchApp::x_InitPubSeqConnection().

CDB_Connection * I_DriverContext::ConnectValidated ( const string & srv_name,

const string & user_name,

const string & passwd,

IConnValidator & validator,

TConnectionMode mode = 0,

bool reusable = false,

const string & pool_name = kEmptyStr

)

Create new connection to specified server (within this context).

Parameters:

srv_name Server/Service name. This parameter can be a SERVER name (host name, DNS alias name, or one of the names found in interfaces file) or an IP address. This parameter can also be a SERVICE name, which is defined by Load Balancer framework. In order to enable using of LB service names you have to call DBLB_INSTALL_DEFAULT() macro before any other DBAPI method.

user_name User name.

passwd User password.

validator Connection validation object.

mode Connection mode.

reusable If set to true put connection into a connection pool on deletion.

pool_name Name of a pool to which this connection is going to belong.

Returns:
Connection object on success, NULL on error.
NOTE:
It is your responsibility to delete the returned connection object. reusable - controls connection pooling mechanism. If it is set to true then a connection will be added to a pool of connections instead of closing.
srv_name, user_name and passwd may be set to empty string.
If pool_name is provided then connection will be taken from a pool having this name if a pool is not empty.
It is your responsibility to put connections with the same server/user/password values in a pool.
If a pool name is not provided but a server name (srv_name) is provided instead then connection with the same name will be taken from a pool of connections if a pool is not empty.
If a pool is empty then new connection will be created unless you passed mode = fDoNotConnect. In this case NULL will be returned.
If you did not provide either a pool name or a server name then NULL will be returned.
Definition at line 299 of file interfaces.cpp.
References MakeConnection(), and CDBDefaultConnParams::SetConnValidator().
Referenced by CDbapiSampleApp::CreateConnection().

virtual string I_DriverContext::GetApplicationName ( void ) const [pure virtual]

Return application name.

Returns:
Application name.

See also:
SetApplicationName()

Implemented in impl::CDriverContext.
Referenced by IDataSource::GetApplicationName().

virtual string I_DriverContext::GetHostName ( void ) const [pure virtual]

Get host name.

Returns:
Host name.

See also:
SetHostName()

Implemented in impl::CDriverContext.

virtual unsigned int I_DriverContext::GetLoginTimeout ( void ) const [pure virtual]

Get login timeout.

Returns:
Login timeout.

See also:
SetLoginTimeout()

Implemented in CTLibContext, and impl::CDriverContext.
Referenced by CDBConnectionFactory::CalculateLoginTimeout().

virtual unsigned int I_DriverContext::GetTimeout ( void ) const [pure virtual]

Get connection timeout.

Returns:
Connection timeout.

See also:
SetTimeout()

Implemented in CTLibContext, and impl::CDriverContext.
Referenced by CDBConnectionFactory::CalculateConnectionTimeout(), and CDBConnectionFactory::MakeDBConnection().

virtual bool I_DriverContext::IsAbleTo ( ECapability cpb ) const [pure virtual]

Check if a driver is acle to provide necessary functionality.

Parameters:

cpb Functionality to query about.

Returns:

true if functionality is present
false if no such functionality.

virtual CDB_Connection* I_DriverContext::MakeConnection ( const CDBConnParams & params ) [pure virtual]

Create connection object using Load Balancer / connection factory.

Parameters:

params Connection parameters.

Returns:
Connection object.

Implemented in impl::CDriverContext.
Referenced by CConnection::CloneCDB_Conn(), Connect(), CConnection::Connect(), and ConnectValidated().

virtual CDB_Connection* I_DriverContext::MakePooledConnection ( const CDBConnParams & params ) [protected, pure virtual]

Create connection object WITHOUT using of Load Balancer / connection factory.

Parameters:

params Connection parameters.

Returns:
Connection object.

Implemented in impl::CDriverContext.
Referenced by IDBConnectionFactory::CtxMakeConnection().

virtual unsigned int I_DriverContext::NofConnections ( const string & srv_name = "",

const string & pool_name = ""

) const [pure virtual]

Return number of currently open connections in this context.

Parameters:

srv_name Server/Service name. If not empty, then return # of connection open to that server.

pool_name Name of connection pool.

Returns:
Return number of currently open connections in this context. If "srv_name" is not NULL, then return # of conn. open to that server.

Implemented in impl::CDriverContext.
Referenced by CDataSource::~CDataSource(), and CDriverManager::~CDriverManager().

virtual void I_DriverContext::PopCntxMsgHandler ( CDB_UserHandler * h ) [pure virtual]

Remove message handler "h" and all handlers above it in the stack.

Parameters:

h Error message handler to be removed.

See also:
PushCntxMsgHandler()

Implemented in impl::CDriverContext.
Referenced by CDataSource::SetLogStream(), CDataSource::~CDataSource(), and CMsgHandlerGuard::~CMsgHandlerGuard().

virtual void I_DriverContext::PopDefConnMsgHandler ( CDB_UserHandler * h ) [pure virtual]

Remove `per-connection' mess.
handler "h" and all above it in the stack.

Parameters:

h Error message handler.

See also:
PushDefConnMsgHandler()

Implemented in impl::CDriverContext.
Referenced by CDataSource::SetLogStream(), CDataSource::~CDataSource(), and CMsgHandlerGuard::~CMsgHandlerGuard().

virtual void I_DriverContext::PushCntxMsgHandler ( CDB_UserHandler * h,

EOwnership ownership = eNoOwnership

) [pure virtual]

Add message handler "h" to process 'context-wide' (not bound to any particular connection) error messages.

Parameters:

h Error message handler.

ownership If set to eNoOwnership, it is user's responsibility to unregister and delete the error message handler. If set to eTakeOwnership, then DBAPI will take ownership of the error message handler and delete it itself.

See also:
PopCntxMsgHandler()

Implemented in impl::CDriverContext.
Referenced by python::CConnection::CConnection(), CMsgHandlerGuard::CMsgHandlerGuard(), CDbCopyApp::Run(), and CDataSource::SetLogStream().

virtual void I_DriverContext::PushDefConnMsgHandler ( CDB_UserHandler * h,

EOwnership ownership = eNoOwnership

) [pure virtual]

Add `per-connection' err.message handler "h" to the stack of default handlers which are inherited by all newly created connections.

Parameters:

h Error message handler.

ownership If set to eNoOwnership, it is user's responsibility to unregister and delete the error message handler. If set to eTakeOwnership, then DBAPI will take ownership of the error message handler and delete it itself.

See also:
PopDefConnMsgHandler()

Implemented in impl::CDriverContext.
Referenced by python::CConnection::CConnection(), CMsgHandlerGuard::CMsgHandlerGuard(), CDbCopyApp::Run(), and CDataSource::SetLogStream().

virtual void I_DriverContext::SetApplicationName ( const string & app_name ) [pure virtual]

Set application name.

Parameters:

app_name defines the application name that a connection will use when connecting to a server.

See also:
GetApplicationName()

Implemented in impl::CDriverContext.
Referenced by IDataSource::SetApplicationName().

virtual void I_DriverContext::SetHostName ( const string & host_name ) [pure virtual]

Set host name.

Parameters:

host_name Host name

See also:
GetHostName()

Implemented in impl::CDriverContext.

virtual bool I_DriverContext::SetLoginTimeout ( unsigned int nof_secs = 0 ) [pure virtual]

Set login timeout.

Parameters:

nof_secs Timeout in seconds. If "nof_secs" is zero or is "too big" (depends on the underlying DB API), then set the timeout to infinite.

Returns:
FALSE on error.

See also:
GetLoginTimeout()

Implemented in CTLibContext, CDBLibContext, and impl::CDriverContext.
Referenced by CDBConnectionFactory::MakeDBConnection(), and CDataSource::SetLoginTimeout().

virtual bool I_DriverContext::SetMaxTextImageSize ( size_t nof_bytes ) [pure virtual]

Set maximal size for Text and Image objects.

Parameters:

nof_bytes Maximal size for Text and Image objects. Text and Image objects exceeding this size will be truncated.

Returns:
FALSE on error (e.g. if "nof_bytes" is too big).

Implemented in CTLibContext, CDBLibContext, and impl::CDriverContext.
Referenced by CBlobStoreDynamic::CBlobStoreDynamic(), CDbapiSendDataApp::RunSample(), and CDbapiCursorApp::RunSample().

virtual bool I_DriverContext::SetTimeout ( unsigned int nof_secs = 0 ) [pure virtual]

Set connection timeouts.

Parameters:

nof_secs Timeout in seconds. If "nof_secs" is zero or is "too big" (depends on the underlying DB API), then set the timeout to infinite.

Returns:
FALSE on error.

See also:
GetTimeout()

Implemented in CTLibContext, CDBLibContext, and impl::CDriverContext.
Referenced by CDBConnectionFactory::MakeDBConnection().

Friends And Related Function Documentation

friend class IDBConnectionFactory [friend]

Definition at line 1079 of file interfaces.hpp.

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

include/dbapi/driver/interfaces.hpp
src/dbapi/driver/interfaces.cpp

Generated on Wed Dec 9 08:12:41 2009 for NCBI C++ ToolKit by

1.4.6

Modified on Wed Dec 09 08:20:12 2009 by modify_doxy.py rev. 173732


Public Types
typedef int	TConnectionMode
enum	EConnectionMode { fBcpIn = 0x1, fPasswordEncrypted = 0x2, fDoNotConnect = 0x4 }
	Connection mode. More...
enum	ECapability { eBcp, eReturnITDescriptors, eReturnComputeResults }
	Report if the driver supports this functionality. More...
Public Member Functions
virtual	~I_DriverContext (void)
virtual bool	SetLoginTimeout (unsigned int nof_secs=0)=0
	Set login timeout.
virtual bool	SetTimeout (unsigned int nof_secs=0)=0
	Set connection timeouts.
virtual unsigned int	GetLoginTimeout (void) const =0
	Get login timeout.
virtual unsigned int	GetTimeout (void) const =0
	Get connection timeout.
virtual bool	SetMaxTextImageSize (size_t nof_bytes)=0
	Set maximal size for Text and Image objects.
CDB_Connection *	Connect (const string &srv_name, const string &user_name, const string &passwd, TConnectionMode mode, bool reusable=false, const string &pool_name=kEmptyStr)
	Create new connection to specified server (or service) within this context.
CDB_Connection *	ConnectValidated (const string &srv_name, const string &user_name, const string &passwd, IConnValidator &validator, TConnectionMode mode=0, bool reusable=false, const string &pool_name=kEmptyStr)
	Create new connection to specified server (within this context).
virtual CDB_Connection *	MakeConnection (const CDBConnParams &params)=0
	Create connection object using Load Balancer / connection factory.
virtual unsigned int	NofConnections (const string &srv_name="", const string &pool_name="") const =0
	Return number of currently open connections in this context.
virtual void	PushCntxMsgHandler (CDB_UserHandler *h, EOwnership ownership=eNoOwnership)=0
	Add message handler "h" to process 'context-wide' (not bound to any particular connection) error messages.
virtual void	PopCntxMsgHandler (CDB_UserHandler *h)=0
	Remove message handler "h" and all handlers above it in the stack.
virtual void	PushDefConnMsgHandler (CDB_UserHandler *h, EOwnership ownership=eNoOwnership)=0
	Add `per-connection' err.message handler "h" to the stack of default handlers which are inherited by all newly created connections.
virtual void	PopDefConnMsgHandler (CDB_UserHandler *h)=0
	Remove `per-connection' mess.
virtual bool	IsAbleTo (ECapability cpb) const =0
	Check if a driver is acle to provide necessary functionality.
virtual void	CloseUnusedConnections (const string &srv_name=kEmptyStr, const string &pool_name=kEmptyStr)=0
	Close reusable deleted connections for specified server and/or pool.
virtual void	SetApplicationName (const string &app_name)=0
	Set application name.
virtual string	GetApplicationName (void) const =0
	Return application name.
virtual void	SetHostName (const string &host_name)=0
	Set host name.
virtual string	GetHostName (void) const =0
	Get host name.
Protected Member Functions
	I_DriverContext (void)
virtual CDB_Connection *	MakePooledConnection (const CDBConnParams &params)=0
	Create connection object WITHOUT using of Load Balancer / connection factory.
Friends
class	IDBConnectionFactory

I_DriverContext Class Reference [Database Server Interfaces]

Detailed Description

Public Types

Public Member Functions