Environment Class

The Environment class provides an OCCI environment to manage memory and other resources for OCCI objects.

The application can have multiple OCCI environments. Each environment would have its own heap and thread-safety mutexes.

Table 10-14 Constants of the Environment Class

Constant	Description
DEFAULT	The default mode for creating an `Environment` object; no thread safety or object support
OBJECT	Mode for creating an `Environment` object; uses object features.
SHARED	Shared mode for creating an `Environment` object.
NO_USERCALLBACKS	Mode for creating an `Environment` object; does not support user callbacks.
THREADED_MUTEXED	Thread safe mode for creating an `Environment` object, mutexed internally by OCCI
THREADED_UNMUTEXED	Thread safe mode for creating an `Environment` object, client is responsible for mutexing.
EVENTS	Mode for creating an `Environment` object; supports registration for event notification (Advanced Queuing).
USE_LDAP	Mode for creating an `Environment` object; supports registration with LDAP.

Table 10-15 Summary of Environment Methods

Method	Summary
createConnection()	Establish a connection to the specified database.
createConnectionPool()	Create a connection pool.
createEnvironment()	Create an `Environment` object.
createStatelessConnectionPool()	Create a stateless connection pool.
enableSubscription()	Enables subscription notification
disableSubscription()	Disables subscription notification
getCacheMaxSize()	Retrieve the Cache Max heap size.
getCacheOptSize()	Retrieve the cache optimal heap size.
getCacheSortedFlush()	Retrieve the setting of the cache sorting flag.
getCurrentHeapSize()	Return the current amount of memory allocated to all objects in the current environment.
getEnvironment()	Returns the `Environment` used for creating a `Subscription`.
getLDAPAdminContext()	Returns the administrative context when using LDAP open notification registration.
getLDAPAuthentication()	Returns the authentication mode when using LDAP open notification registration.
getLDAPHost()	Returns the host on which the LDAP server runs.
getLDAPPort()	Returns the port on which the LDAP server is listening.
getMap()()	Return the Map for the current environment.
getOCIEnvironment()	Return the OCI environment associated with the current environment.
getXAConnection()	Create an XA connection to a database.
getXAEnvironment()	Create an XA `Environment` object.
releaseXAConnection()	Release all resources allocated by a getXAConnection() call.
releaseXAEnvironment()	Release all resources allocated by a getXAEnvironment() call.
setCacheMaxSize()	Specifies the maximum size for the client-side object cache as a percentage of the optimal size.
setCacheOptSize()	Specifies the optimal size for the client-side object cache in bytes.
setCacheSortedFlush()	Speechifies whether to sort cache in table order prior to flushing.
setLDAPAdminContext()	Speechifies the administrative context for the LDAP client.
setLDAPAuthentication()	Speechifies the LDAP authentication mode.
setLDAPHostAndPort()	Speechifies the LDAP server host and port.
setLDAPLoginNameAndPassword()	Speechifies the login name and password when connecting to an LDAP server.
terminateConnection()	Close the connection pool and free all related resources.
terminateConnectionPool()	Close the connection pool and free all related resources.
terminateEnvironment()	Destroy the environment.
terminateStatelessConnectionPool()	Close the stateless connection pool and free all related resources.

createConnection()

This method establishes a connection to the database specified.

Syntax Description

Syntax	Description
Connection * createConnection( const string &username, const string &password, const string &connectString);	Creates a default connection.
Connection * createConnection( const UString &username, const UString &password, const UString &connectString);	Creates a connection (Unicode support). The client `Environment` should be initialized in `OCCIUTIF16` mode.

Connection * createConnection(
   const string &username,
   const string &password,
   const string &connectString);

Creates a default connection.

Connection * createConnection(
   const UString &username,
   const UString &password,
   const UString &connectString);

Creates a connection (Unicode support). The client Environment should be initialized in OCCIUTIF16 mode.

Parameter	Description
username	The name of the user with which to connect.
password	The password of the user.
connectString	The database to which the connection is made.

createConnectionPool()

Create a connection pool based on the parameters specified.

Syntax Description

Syntax	Description
ConnectionPool* createConnectionPool( const string &poolUserName, const string &poolPassword, const string &connectString = "", unsigned int minConn = 0, unsigned int maxConn = 1, unsigned int incrConn = 1);	Creates a default connection pool.
ConnectionPool* createConnectionPool( const UString &poolUserName, const UString &poolPassword, const UString &connectString, unsigned int minConn = 0, unsigned int maxConn = 1, unsigned int incrConn = 1);	Creates a connection pool (Unicode support). The client `Environment` should be initialized in `OCCIUTIF16` mode.

ConnectionPool* createConnectionPool(
   const string &poolUserName,
   const string &poolPassword,
   const string &connectString = "",
   unsigned int minConn = 0,
   unsigned int maxConn = 1,
   unsigned int incrConn = 1);

Creates a default connection pool.

ConnectionPool* createConnectionPool(
   const UString &poolUserName,
   const UString &poolPassword,
   const UString &connectString,
   unsigned int minConn = 0,
   unsigned int maxConn = 1,
   unsigned int incrConn = 1);

Creates a connection pool (Unicode support). The client Environment should be initialized in OCCIUTIF16 mode.

Parameter	Description
poolUserName	The pool user name.
poolPassword	The pool password.
connectString	The connection string for the server
minConn	The minimum number of connections in the pool. The minimum number of connections are opened by this method. Additional connections are opened only when necessary. Generally, `minConn` should be set to the number of concurrent statements the application is expected to run.
maxConn	The maximum number of connections in the pool. Valid values are 1 and greater.
incrConn	The increment by which to increase the number of connections to be opened if the current number of connections is less than `maxConn`. Valid values are 1 and greater.

createEnvironment()

Create an Environment object. It is created with the specified memory management functions specified in the setMemMgrFunctions() method. If no memory manager functions are specified, then OCCI uses its own default functions. An Environment object must eventually be closed to free all the system resources it has acquired.

If the mode specified is THREADED_MUTEXED or THREADED_UNMUTEXED, then all three memory management functions must be thread-safe.

Syntax Description

Syntax	Description
static Environment * createEnvironment( Mode mode = DEFAULT, void ctxp = 0, void (malocfp)(void ctxp, size_t size) = 0, void (ralocfp)(void ctxp, void memptr, size_t newsize) = 0, void (mfreefp)(void ctxp, void *memptr) = 0);	Creates a default environment.
static Environment * createEnvironment( Mode mode = DEFAULT, void ctxp = 0, void (malocfp)(void ctxp, size_t size) = 0, void (ralocfp)(void ctxp, void memptr, size_t newsize) = 0, void (mfreefp)(void ctxp, void *memptr) = 0, const std::string &charset, const std::string &ncharset);	Creates an environment with the specified character set and `NCHAR` character set ids (Unicode support). The client `Environment` should be initialized in `OCCIUTIF16` mode.

static Environment * createEnvironment(
   Mode mode = DEFAULT,
   void *ctxp = 0,
   void *(*malocfp)(void *ctxp,
                    size_t size) = 0,
   void *(*ralocfp)(void *ctxp, 
                    void *memptr,
                    size_t newsize) = 0,
   void (*mfreefp)(void *ctxp,
                   void *memptr) = 0);

Creates a default environment.

static Environment * createEnvironment(
   Mode mode = DEFAULT,
   void *ctxp = 0,
   void *(*malocfp)(void *ctxp,
                    size_t size) = 0,
   void *(*ralocfp)(void *ctxp, 
                    void *memptr,
                    size_t newsize) = 0,
   void (*mfreefp)(void *ctxp,
                   void *memptr) = 0,
   const std::string &charset,
   const std::string &ncharset);

Creates an environment with the specified character set and NCHAR character set ids (Unicode support). The client Environment should be initialized in OCCIUTIF16 mode.

Parameter	Description
mode	Valid values are (see Table 10-14 for descriptions) `DEFAULT`, `THREADED_MUTEXED`, `THREADED_UNMUTEXED`, `OBJECT`.
ctxp	Context pointer for user-defined memory management function.
size	The size of the memory to be allocated by user-defined memory allocation function.
newsize	The new size of the memory to be reallocated.
memptr	the existing memory that needs to be reallocated to new size.
malocfp	User-defined memory allocation function.
ralocfp	User-defined memory reallocation function.
mfreefp	User-defined memory free function.
charset	Character set id that will replace the one specified in `NLS_LANG`.
ncharset	Character set id that will replace the one specified in `NLS_NCHAR`.

createStatelessConnectionPool()

Create a StatelessConnectionPool object with specified pool attributes.

Syntax

StatelessConnectionPool* createStatelessConnectionPool(
   const string &poolUserName,
   const string &poolPassword,
   const string connectString="",
   unsigned int maxConn=1,
   unsigned int minConn=0,
   unsigned int incrConn=1,
   enum StatelessConnectionPool::Mode=StatelessConnectionPool::HETEROGENEOUS);

Parameter	Description
poolUserName	The pool user name.
poolPassword	The pool password.
connectString	The connection string for the server
maxConn	The maximum number of connections that can be opened in the pool; additional sessions cannot be open.
minConn	The number of connections initially created in a pool. This parameter is considered only if the mode is set to `HOMOGENEOUS`.
incrConn	The number of connections by which to increment the pool if all open connections are busy, up to a maximum open connections specified by `maxConn` parameter. This parameter is considered only if the mode is set to `HOMOGENEOUS`.
Mode	The mode of the connection pool, which can be either `HIOMOGENEOUS` or `HETEROGENEOUS`. `HETEROGENEOUS` -- default mode; connections with different authentication contexts can be created in the same pool. `HOMOGENEOUS` -- 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.

enableSubscription()

Enables subscription notification.

Syntax

void enableSubscription(
   Subscription &subscr);

Parameter	Description
subscr	The Subscription.

disableSubscription()

Disables subscription notification.

Syntax

void disableSubscription(
   Subscription &subscr);

Parameter	Description
subscr	The Subscription.

getCacheMaxSize()

Retrieves the Cache Max heap size.

Syntax

unsigned int getCacheMaxSize() const;

getCacheOptSize()

Retrieves the Cache optimal heap size.

Syntax

unsigned int getCacheOptSize() const;

getCacheSortedFlush()

Retrieves the current setting of the cache sorting flag; TRUE or FALSE.

Syntax

bool getCacheSortedFlush();

getCurrentHeapSize()

Returns the amount of memory currently allocated to all objects in this environment.

Syntax

unsigned int getCurrentHeapSize() const;

getEnvironment()

Returns the Environment used for creating a Subscription.

Syntax

Environment* getEnvironment() const;

getLDAPAdminContext()

Returns the administrative context when using LDAP open notification registration.

Syntax

string getLDAPAdminContext() const;

getLDAPAuthentication()

Returns the authentication mode when using LDAP open notification registration.

Syntax

unsigned int getLDAPAuthentication() const;

getLDAPHost()

Returns the host on which the LDAP server runs.

Syntax

string getLDAPHost() const;

getLDAPPort()

Returns the port on which the LDAP server is listening.

Syntax

string unsigned intgetLDAPPort() const;

getMap()

Returns a pointer to the map for this environment.

Syntax

Map *getMap() const;

getOCIEnvironment()

Returns a pointer to the OCI environment associated with this environment.

Syntax

LNOCIEnv *getOCIEnvironment() const;

getXAConnection()

Returns a pointer to an OCCI Connection object that corresponds to the one opened by the XA library.

Syntax

get XAConnection(
   const string &dbname);

Parameter	Description
dbname	The database name; same as the optional `dbname` provided in the Open String (and used in connection to the Resource Manager).

getXAEnvironment()

Returns a pointer to an OCCI Environment object that corresponds to the one opened by the XA library.

Syntax

getXAEnvironment(
   const string &dbname);

Parameter	Description
dbname	The database name; same as the optional `dbname` provided in the Open String (and used in connection to the Resource Manager).

releaseXAConnection()

Release/deallocate all resources allocated by the getXAConnection() method.

Syntax

releaseXAConnection(
   Connection* conn);

Parameter	Description
conn	The connection returned by the getXAConnection() method.

releaseXAEnvironment()

Release/deallocate all resources allocated by the getXAEnvironment() method.

Syntax

releaseXAEnvironment(
   Environment* env);

Parameter	Description
env	The environment returned by the getXAEnvironment() method.

setCacheMaxSize()

Sets the maximum size for the client-side object cache as a percentage of the optimal size. The default value is 10%.

Syntax

void setCacheMaxSize(
   unsigned int maxSize);

Parameter	Description
maxSize	The value of the maximum size, as a percentage.

setCacheOptSize()

Sets the optimal size for the client-side object cache in bytes. The default value is 8MB.

Syntax

void setCacheOptSize(
   unsigned int optSize);

Parameter	Description
optSize	The value of the optimal size, in bytes.

setCacheSortedFlush()

Sets the cache flushing protocol. By default, objects in cache are flushed in the order they are modified; flag=FALSE. To improve server-side performance, set flag=TRUE, so that the objects in cache are sorted in table order prior to flushing from client cache.

Syntax

void setCacheSortedFlush(
   bool flag);

Parameter	Description
flag	`FALSE` (default) -- no sorting; `TRUE` -- sorting in table order

setLDAPAdminContext()

Sets the administrative context of the client. This is usually the root of the Oracle RDBMS LDAP schema in the LDAP server.

Syntax

void setLDAPAdminContext(
   const string &ctx);

Parameter	Description
ctx	The client context

setLDAPAuthentication()

Specifies the authentication mode. Currently the only supported value is 0x1: Simple authentication; username/password authentication.

Syntax

void setLDAPAuthentication(
   unsigned int mode);

Parameter	Description
mode	The authentication mode

setLDAPHostAndPort()

Specifies the host on which the LDAP server is running, and the port on which it is listening for requests.

Syntax

void setLDAPHostAndPort(
   const string &host,
   unsigned int port);

Parameter	Description
host	The host for LDAP
port	The port for LDAP

setLDAPLoginNameAndPassword()

Specifies the login distinguished name and password used when connecting to an LDAP server.

Syntax

void setLDAPLoginNameAndPassword(
   const string &login,
   const &passwd);

Parameter	Description
login	The login name
passwd	The login password

terminateConnection()

Closes the connection to the environment, and frees all related system resources.

Syntax

void terminateConnection(
   Connection *connection);

Parameter	Description
connection	A pointer to the connection instance to be terminated.

terminateConnectionPool()

Closes the connections in the connection pool, and frees all related system resources.

Syntax

void terminateConnectionPool(
   ConnectionPool *poolPointer);

Parameter	Description
poolPointer	A pointer to the connection pool instance to be terminated.

terminateEnvironment()

Closes the environment, and frees all related system resources.

Syntax

void terminateEnvironment(
   Environment *env);

Parameter	Description
env	Environment to be closed.

terminateStatelessConnectionPool()

Destroy the specified Stateless Connection Pool.

Syntax

void termimnateStatelessConnectionPool(
   StatelessConnectionPool* scp,
   StatelessConnectionPool::DestroyMode mode=StatelessConnectionPool::DEFAULT);

Parameter	Description
scp	The `Stateless ConnectionPool` to be destroyed.
mode	Valid values are: `StatelessConnectionPool::DEFAULT` -- if there are still active busy connections in the pool, ORA24422 error is thrown. `StatelessConnectionPool::SPD_FORCE` -- any busy connections in the pool will be forcefully terminated and the pool destroyed.

Warning:

When the pool is terminated using the StatelessConnectionPool::SPD_FORCE mode, the user will lose memory corresponding to the number of connections forcefully terminated.