StatelessConnectionPool Class

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

Example 10-8 Using a StatelessConnectionPool

The pool size is dynamic, in response to changing user requirements, up to the specified maximum number of connections. Assume that a stateless connection pool is created with following parameters:

minConn = 5
incrConn = 2
maxConn = 10

Five connections are opened when the pool is created:

openConn = 5

Using get[AnyTagged][Proxy]Connection() methods, the user consumes all 5 open connection:

openConn = 5
busyConn = 5

When the user wants another connection, the pool will open 2 new connections and return one of them to the user

openConn = 7
busyConn = 6

The upper limit for the number of connections that can be pooled is maxConn specified at the time of creation of the pool by the .

The user can also modify the pool parameters after the pool is created using the setPoolSize() method.

If a heterogenous pool is created, the incrConn and minConn arguments are ignored.

Table 10-36 Summary of StatelessConnectionPool Methods

Method	Description
getAnyTaggedConnection()	Return a pointer to the connection object, without the restriction of a matching tag.
getAnyTaggedProxyConnection()	Return a proxy connection from a connection pool.
getBusyConnections()	Return the number of busy connections in the connection pool.
getBusyOption()	Return 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()	Return a pointer to the `Connection` object.
getIncrConnections()	Return the number of incremental connections in the connection pool.
getMaxConnections()	Return the maximum number of connections in the connection pool.
getMinConnections()	Return the minimum number of connections in the connection pool.
getOpenConnections()	Return the number of open connections in the connection pool.
getPoolName()	Return the name of the connection pool.
getProxyConnection()	Return a proxy connection from a connection pool.
getTimeOut()	Return the timeout period of a connection in the connection pool.
releaseConnection()	Release the connection back to the pool with an optional tag.
setBusyOption()	Specify 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()	Set the maximum, minimum, and incremental number of pooled connections for the connection pool.
setTimeOut()	Set the timeout period of a connection in the connection pool.
terminateConnection()	Close 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="");	Returns a pointer to the connection object from a homogeneous stateless connection pool, without the restriction of a matching tag
Connection *getAnyTaggedConnection( const string &name, const string &password, const string tag="");	Returns a pointer to the connection object from a heterogeneous stateless connection pool, without the restriction of a matching tag

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()

Return 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, string tag="", Connection::ProxyType proxyType=Connection::PROXY_DEFAULT);	Get a proxy connection with role specifications from a connection pool.
Connection *getAnyTaggedProxyConnection( const string &name, string tag="", Connection::ProxyType proxyType=Connection::PROXY_DEFAULT);	Get a proxy connection within role specifications from the connection pool.

Syntax

Description

Connection *getAnyTaggedProxyConnection(
   const string &name,
   string roles[],
   unsigned int numRoles,
   string tag="",
   Connection::ProxyType proxyType=Connection::PROXY_DEFAULT);

Get a proxy connection with role specifications from a connection pool.

Connection *getAnyTaggedProxyConnection(
   const string &name,
   string tag="",
   Connection::ProxyType proxyType=Connection::PROXY_DEFAULT);

Get a proxy connection within role specifications from the connection pool.

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. `PROXY_DEFAULT` represents a database username

getBusyConnections()

Return the number of busy connections in the connection pool.

Syntax

unsigned int getBusyConnections() const;

getBusyOption()

Return the behavior of the stateless connection pool when:

all the connections in the pool are busy, and
the number of connections have reached maximum.

The possible return values are:

WAIT means that the thread waits and blocks until the connection becomes free
NOWAIT throws an error
FORCEGET creates a new connection, although maximum number of connections is opened and all are busy

Syntax

BusyOption getBusyOption();

getConnection()

Return a pointer to the connection object for a either a stateless or statefull Connection Pool.

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

Parameter	Description
username	The database username.
password	The database password.
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.

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;

getMaxConnections()

Returns the maximum number of connections in the connection pool.

Syntax

unsigned int getMaxConnections() const;

getMinConnections()

Returns the minimum number of connections in the connection pool.

Syntax

unsigned int getMinConnections() const;

getOpenConnections()

Returns the number of open connections in the connection pool.

Syntax

unsigned int getOpenConnections() const;

getPoolName()

Returns the name of the connection pool.

Syntax

string getPoolName() const;

getProxyConnection()

Returns a proxy connection from a connection pool.

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

Syntax

Description

Connection *getProxyConnection(
   const string &name,
   string roles[],
   unsigned int numRoles,
   string tag="",
   Connection::ProxyType proxyType=Connection::PROXY_DEFAULT);

Get a proxy connection with role specifications from a connection pool.

Connection *getProxyConnection(
   const string &name,
   string tag="",
   Connection::ProxyType proxyType=Connection::PROXY_DEFAULT);

Get a proxy connection without role specifications from a connection pool

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. `PROXY_DEFAULT` represents a database username

getStmtCacheSize()

Retrieves the size of the statement cache.

Syntax

unsigned int getStmtCacheSize() const;

getTimeOut()

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

Syntax

unsigned int getTimeOut() const;

releaseConnection()

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

Syntax

void releaseConnection( 
   Connection *conn,
   const string tag="");

Parameter	Description
conn	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()

Specify the behavior of the stateless connection pool when:

all the connections in the pool are busy, and
the number of connections have reached maximum.

Syntax

void setBusyOption( 
   BusyOption busyOption);

Parameter	Description
busyOption	Valid values: `WAIT` means that the thread waits and blocks until the connection is free `NOWAIT` throws an error `FORCEGET` creates a new connection, although maximum number of connections is opened and all are busy.

Caution:

When busyOption is set to FORCEGET, an attempt can be made to create more connections than the number that can be supported. In such cases, a request for new connections will return an error 'ORA 00018 -- Maximum number of sessions exceeded' that will be propagated to the pool user.

setPoolSize()

Set 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);

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

setTimeOut()

Set 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);

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.

Note:

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 size);

Parameter	Description
size	The size of the statement cache

terminateConnection()

Close the connection and remove it from the pool.

Syntax

void terminateConnection( 
   Connection *conn);

Parameter	Description
conn	The connection to be terminated