Skip Headers
Oracle® C++ Call Interface Programmer's Guide
10g Release 2 (10.2)

Part Number B14294-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

StatelessConnectionPool Class

This class represents a pool of stateless, authenticated connections to the database.

Table 12-40 Enumerated Values Used by StatelessConnectionPool Class

Attribute Options
PoolType
  • HETEROGENEOUS is the default state; connections with different authentication contexts can be created in the same pool.
  • HOMOGENEOUS indicates that all connections in the pool will be authenticated with the username and password provided during pool creation. No proxy connections can be created. minConn and incrConn values are considered only in these HOMOGENEOUS pools.

BusyOption
  • WAIT indicates that the thread waits and blocks until the connection becomes free.
  • NOWAIT throws and error.

  • FORGET indicates that a new connection will be created, even when maximum number of connections is opened and all are busy.

DestroyMode
  • DEFAULT indicates that if are still active busy connections in the pool, ORA24422 error is thrown
  • SPD_FORCE indicates that the means that any busy connections in the pool will be forcefully terminated and the pool destroyed (the user will lose memory corresponding to the number of connections forcefully terminated)


Table 12-41 Summary of StatelessConnectionPool Methods

Method Description
getAnyTaggedConnection()
Returns a pointer to the connection object, without the restriction of a matching tag.
getAnyTaggedProxyConnection()
Returns a proxy connection from a connection pool.
getBusyConnections()
Returns the number of busy connections in the connection pool.
getBusyOption()
Returns the behavior of the stateless connection pool when all the connections in the pool are busy and the number of connections have reached maximum
getConnection()
Returns a pointer to the Connection object.
getIncrConnections()
Returns the number of incremental connections in the connection pool.
getMaxConnections()
Returns the maximum number of connections in the connection pool.
getMinConnections()
Returns the minimum number of connections in the connection pool.
getOpenConnections()
Returns the number of open connections in the connection pool.
getPoolName()
Returns the name of the connection pool.
getProxyConnection()
Returns a proxy connection from a connection pool.
getTimeOut()
Returns the timeout period of a connection in the connection pool.
releaseConnection()
Releases the connection back to the pool with an optional tag.
setBusyOption()
Specifies the behavior of the stateless connection pool when:
  • all the connections in the pool are busy, and

  • the number of connections have reached maximum.

setPoolSize()
Sets the maximum, minimum, and incremental number of pooled connections for the connection pool.
setTimeOut()
Sets the timeout period of a connection in the connection pool.
terminateConnection()
Closes the connection and remove it from the pool.


getAnyTaggedConnection()

Returns a pointer to the connection object, without the restriction of a matching tag.

During the execution of this call, the pool is first searched based on the tag provided. If a connection with the specified tag exists, it is returned to the user. If a matching connection is not available, an appropriately authenticated untagged connection (with a NULL tag) is returned. In cases where an undated connection is not free, an appropriately authenticated connection with a different tag is returned.


Note:

A getTag() call to the Connection verifies the connection tag received.

Syntax Description
Connection *getAnyTaggedConnection(
   string &tag="")=0;
Returns a pointer to the connection object from a homogeneous stateless connection pool, without the restriction of a matching tag; string support.
Connection* getAnyTaggedConnection(
   const UString &tag)=0; 
Returns a pointer to the connection object from a homogeneous stateless connection pool, without the restriction of a matching tag; UString support.
Connection *getAnyTaggedConnection(
   const string &userNname,
   const string &password,
   const string &tag="")=0;
Returns a pointer to the connection object from a heterogeneous stateless connection pool, without the restriction of a matching tag; string support.
Connection* getAnyTaggedConnection(
   const UString &userName, 
   const UString &Password, 
   const UString &tag)=0 ;
Returns a pointer to the connection object from a heterogeneous stateless connection pool, without the restriction of a matching tag; UString support.

Parameter Description
userName
The database username
password
The database password.
tag
User-defined type of connection requested. This parameter can be ignored if a default connection is requested.


getAnyTaggedProxyConnection()

Returns a proxy connection from a connection pool.

During the execution of this call, the pool is first searched based on the tag provided. If a connection with the specified tag exists, it is returned to the user. If a matching connection is not available, an appropriately authenticated connection with a different tag is returned. In cases where an undated connection is not free, an appropriately authenticated connection with a different tag is returned.

Restrictions for matching the tag may be removed by passing an empty tag argument parameter.


Note:

A getTag() call to the connection verifies the connection tag received.

Syntax Description
Connection *getAnyTaggedProxyConnection(
   const string &name,
   string roles[],
   unsigned int numRoles,
   const string tag="",
   Connection::ProxyType 
      proxyType=Connection::PROXY_DEFAULT);
Get a proxy connection with role specifications from a connection pool; includes support for roles and string support.
Connection* getAnyTaggedProxyConnection(
   const UString &name,
   string roles[],
   unsigned int numRoles,
   const UString &tag,
   Connection::ProxyType 
      proxyType = Connection::PROXY_DEFAULT);
Get a proxy connection with role specifications from a connection pool; includes support for roles and UString support.
Connection *getAnyTaggedProxyConnection(
   const string &name,
   const string tag="",
   Connection::ProxyType       proxyType=Connection::PROXY_DEFAULT);
Get a proxy connection with role specifications from a connection pool; string support.
Connection* getAnyTaggedProxyConnection(
   const UString &name,
   const UString &tag,
   Connection::ProxyType 
      proxyType = Connection::PROXY_DEFAULT);
Get a proxy connection within role specifications from the connection pool; UString support.

Parameter Description
name
The username.
roles
The roles to activate on the database server
numRoles
The number of roles to activate on the database server
tag
User defined tag associated with the connection.
proxyType
The type of proxy authentication to perform; ProxyType is defined in Table 12-11.


getBusyConnections()

Returns the number of busy connections in the connection pool.

Syntax

unsigned int getBusyConnections() const=0;


getBusyOption()

Returns the behavior of the stateless connection pool when all the connections in the pool are busy, and when the number of connections have reached maximum. The return values are defined for BusyOption in Table 12-40.

Syntax

BusyOption getBusyOption()=0; 
 

getConnection()

Returns a pointer to the connection object of a StatelessConnectionPool.

Syntax Description
Connection *getConnection(
   string &tag="")=0;
Returns an authenticated connection, with a connection pool username and password; string support.
Connection* getConnection(
   const UString &tag)=0;
Returns an authenticated connection, with a connection pool username and password; UString support.
Connection *getConnection(
   const string &userName,
   const string &password,
   const string &tag="")=0;
Returns a pointer to the connection object from a heterogeneous stateless connection pool; string support..
Connection* getConnection(
   const UString &userName,
   const UString &password,
   const UString &tag)=0;
Returns a pointer to the connection object from a heterogeneous stateless connection pool; UString support.

Parameter Description
userName
The database username.
password
The database password.
tag
The user defined tag associated with the connection. During the call, the pool is first searched based on the tag provided. If a connection with the specified tag exists it is returned; otherwise a new connection is created and returned.


getIncrConnections()

Returns the number of incremental connections in the connection pool. This call is useful only in cases of homogeneous connection pools.

Syntax

unsigned int getIncrConnections() const=0;


getMaxConnections()

Returns the maximum number of connections in the connection pool.

Syntax

unsigned int getMaxConnections() const=0;


getMinConnections()

Returns the minimum number of connections in the connection pool.

Syntax

unsigned int getMinConnections() const=0;


getOpenConnections()

Returns the number of open connections in the connection pool.

Syntax

unsigned int getOpenConnections() const=0;


getPoolName()

Returns the name of the connection pool.

Syntax

string getPoolName() const=0;


getProxyConnection()

Returns a proxy connection from a connection pool.

Syntax Description
Connection *getProxyConnection(
   const string &name,
   string roles[],
   unsigned int numRoles,
   const string& tag="",
   Connection::ProxyType 
      proxyType=Connection::PROXY_DEFAULT)=0;
Get a proxy connection with role specifications from a connection pool; support for roles and string support.
Connection* getProxyConnection(
   const UString &name,
   string roles[], 
   unsigned int numRoles, 
   const UString &tag, 
   Connection::ProxyType 
      proxyType = Connection::PROXY_DEFAULT);
Get a proxy connection with role specifications from a connection pool; support for roles and UString support.
Connection *getProxyConnection(
   const string &name,
   const string& tag="",
   Connection::ProxyType 
      proxyType=Connection::PROXY_DEFAULT)=0;
Get a proxy connection without role specifications from a connection pool; string support.
Connection* getProxyConnection(
   const UString &name,
   const UString &tag,
   Connection::ProxyType 
   proxyType = Connection::PROXY_DEFAULT)
Get a proxy connection without role specifications from a connection pool; UString support.

Parameter Description
name
The username.
roles
The roles to activate on the database server.
numRoles
The number of roles to activate on the database server.
tag
The user defined tag associated with the connection. During the execution of this call, the pool is first searched based on the tag provided. If a connection with the specified tag exists it is returned; otherwise, a new connection is created and returned.
proxyType
The type of proxy authentication to perform; ProxyType is defined in Table 12-11.


getStmtCacheSize()

Retrieves the size of the statement cache.

Syntax

unsigned int getStmtCacheSize() const=0;


getTimeOut()

Returns the timeout period of a connection in the connection pool.

Syntax

unsigned int getTimeOut() const=0;


releaseConnection()

Releases the connection back to the pool with an optional tag.

Syntax Description
void releaseConnection(
   Connection *connection,
   const string& tag="");
Support for string tag.
void releaseConnection(
   Connection *connection,
   const UString &tag);
Support for UString tag.


Parameter Description
connection
The connection to be released.
tag
The user defined tag associated with the connection. The default of this parameter is "", which untags the connection.


setBusyOption()

Specifies the behavior of the stateless connection pool when all the connections in the pool are busy, and when the number of connections have reached maximum.

Syntax

void setBusyOption( 
   BusyOption busyOption)=0;

Parameter Description
busyOption
Valid values are defined in BusyOption in Table 12-40.


Caution:

When busyOption is set to FORCEGET, an attempt can be made to create more connections than can be supported. In such cases, a request for new connections will return an error that will be propagated to the pool user:

ORA 00018 -- Maximum number of sessions exceeded



setPoolSize()

Sets the maximum, minimum, and incremental number of pooled connections for the connection pool.

Syntax

void setPoolSize( 
   unsigned int maxConn=1,
   unsigned int minConn=0,
   unsigned int incrConn=1)=0;

Parameter Description
maxConn
The maximum number of connections in the connection pool.
minConn
The minimum number of connections, in homogeneous pools only.
incrConn
The incremental number of connections, in homogeneous pools only.


setTimeOut()

Sets the timeout period of a connection in the connection pool. OCCI will terminate any connections related to this connection pool that have been idle for longe4r than the timeout period specified.

Syntax

void setTimeOut( 
   unsigned int connTimeOut=0)=0;

Parameter Description
connTimeOut
The timeout period, given in seconds.


setStmtCacheSize()

Enables or disables statement caching. A nonzero value will enable statement caching, with a cache of specified size. A zero value will disable caching.

If the user changes the cache size of individual connections and subsequently returns the connection back to the pool with a tag, the cache size does not revert to the one set for the pool. If the connection is untagged, the cache size is reset to equal the cache size specified for the pool.

Syntax

void setStmtCacheSize(
   unsigned int cacheSize)=0;
Parameter Description
cacheSize
The size of the statement cache


terminateConnection()

Closes the connection and remove it from the pool.

Syntax

void terminateConnection( 
   Connection *connection)=0;

Parameter Description
connection
The connection to be terminated