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.

LNCPP20943 Table 13-17 Enumerated Values Used by Environment Class

Attribute Options

Attribute	Options
Mode	`DEFAULT` is used for creating an Environment object; it has no thread safety or object support. `OBJECT` is for creating an Environment object; it uses object features. `SHARED` is for creating an Environment object. `NO_USERCALLBACKS` is for creating an Environment object; it does not support user callbacks. `THREADED_MUTEXED` is a thread safe mode for creating an Environment object, mutexed internally by OCCI. `THREADED_UNMUTEXED` is a thread safe mode for creating an Environment object; the client is responsible for mutexing. `EVENTS` supports registration for event notification used in Oracle Streams Advanced Queuing. `USE_LDAP` supports registration with LDAP.

Mode

DEFAULT is used for creating an Environment object; it has no thread safety or object support.
OBJECT is for creating an Environment object; it uses object features.
SHARED is for creating an Environment object.
NO_USERCALLBACKS is for creating an Environment object; it does not support user callbacks.
THREADED_MUTEXED is a thread safe mode for creating an Environment object, mutexed internally by OCCI.
THREADED_UNMUTEXED is a thread safe mode for creating an Environment object; the client is responsible for mutexing.
EVENTS supports registration for event notification used in Oracle Streams Advanced Queuing.
USE_LDAP supports registration with LDAP.

LNCPP20944 Table 13-18 Summary of Environment Methods

Method	Summary
createConnection()	Establishes a connection to the specified database.
createConnectionPool()	Creates a connection pool.
createEnvironment()	Creates an `Environment` object.
createStatelessConnectionPool()	Creates a stateless connection pool.
enableSubscription()	Enables subscription notification
disableSubscription()	Disables subscription notification
getCacheMaxSize()	Retrieves the Cache Max heap size.
getCacheOptSize()	Retrieves the cache optimal heap size.
getCacheSortedFlush()	Retrieves the setting of the cache sorting flag.
getClientVersion()	Returns the version of the client library.
getCurrentHeapSize()	Returns the current amount of memory allocated to all objects in the current environment.
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()()	Returns the Map for the current environment.
getOCIEnvironment()	Returns the OCI environment associated with the current environment.
getXAConnection()	Creates an XA connection to a database.
getXAEnvironment()	Creates an XA `Environment` object.
releaseXAConnection()	Releases all resources allocated by a getXAConnection() call.
releaseXAEnvironment()	Releases 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()	Specifies whether to sort cache in table order before flushing.
setLDAPAdminContext()	Specifies the administrative context for the LDAP client.
setLDAPAuthentication()	Specifies the LDAP authentication mode.
setLDAPHostAndPort()	Specifies the LDAP server host and port.
setLDAPLoginNameAndPassword()	Specifies the login name and password when connecting to an LDAP server.
terminateConnection()	Closes the connection pool and free all related resources.
terminateConnectionPool()	Closes the connection pool and free all related resources.
terminateEnvironment()	Destroys the environment.
terminateStatelessConnectionPool()	Closes the stateless connection pool and free all related resources.

LNCPP20945

createConnection()

This method establishes a connection to the database specified.

Syntax	Description
Connection * createConnection( const string &userName, const string &password, const string &connectString="")=0;	Creates a default connection; if the `userName` and `password` are `NULL`, the connection may be authenticated externally.
Connection * createConnection( const UString &userName, const UString &password, const UString &connectString)=0;	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, const string &connectionClass, const Connection::Purity &purity)=0;	Creates a connection for database resident connection pooling.
Connection * createConnection( const UString &userName, const UString &password, const UString &connectString, const UString &connectionClass const Connection::Purity &purity)=0;	Creates a connection for database resident connection pooling (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.
purity	The purity of the connection used for database resident connection pooling; either `SELF` or `NEW`.
connectionClass	The connection class used for database resident connection pooling.

LNCPP20946

createConnectionPool()

Creates 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)=0;	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)=0;	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)=0;

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)=0;

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.

LNCPP20947

createEnvironment()

Creates 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 is specified is either THREADED_MUTEXED or THREADED_UNMUTEXED as defined in Table 13-17, 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( const string &charset, const string &ncharset, 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 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(
   const string &charset,
   const string &ncharset,
   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 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	Values are defined as part of `Mode` in Table 13-17: `DEFAULT`, `THREADED_MUTEXED`, `THREADED_UNMUTEXED`, `OBJECT`.
ctxp	Context pointer for user-defined memory management function.
size	The size of the memory allocated by user-defined memory allocation function.
newsize	The new size of the memory to be reallocated.
memptr	The existing memory that must 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 replaces the one specified in `NLS_LANG`.
ncharset	Character set id that replaces the one specified in `NLS_NCHAR`.

LNCPP20948

createStatelessConnectionPool()

Creates a StatelessConnectionPool object with specified pool attributes.

Syntax Description

Syntax	Description
StatelessConnectionPool* createStatelessConnectionPool( const string &poolUserName, const string &poolPassword, const string connectString="", unsigned int maxConn=1, unsigned int minConn=0, unsigned int incrConn=1, StatelessConnectionPool::PoolType pType=StatelessConnectionPool::HETEROGENEOUS);	Support for `string`.
StatelessConnectionPool* createStatelessConnectionPool( const UString &poolUserName, const UString &poolPassword, const UString &connectString, unsigned int maxConn = 1, unsigned int minConn = 0, unsigned int incrConn = 1, StatelessConnectionPool::PoolType pType=StatelessConnectionPool::HETEROGENEOUS);	Support for `UString`.

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

Support for string.

StatelessConnectionPool* createStatelessConnectionPool(
   const UString &poolUserName,
   const UString &poolPassword,
   const UString &connectString,
   unsigned int maxConn = 1,
   unsigned int minConn = 0,
   unsigned int incrConn = 1,
   StatelessConnectionPool::PoolType 
   pType=StatelessConnectionPool::HETEROGENEOUS);

Support for UString.

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 the pool; additional sessions cannot be open.
minConn	The number of connections initially created in a pool. This parameter is considered only if the `PoolType` is set to `HOMOGENEOUS`, as defined in Table 13-41 .
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 `PoolType` is set to `HOMOGENEOUS`, as defined in Table 13-41 .
pType	The `PoolType` of the connection pool, defined in Table 13-41 .

LNCPP20949

enableSubscription()

Enables subscription notification.

LNCPP20950Syntax

void enableSubscription(
   const aq::Subscription &sub);

Parameter	Description
sub	The Subscription.

LNCPP20951

disableSubscription()

Disables subscription notification.

LNCPP20952Syntax

void disableSubscription(
   Subscription &subscr);

Parameter	Description
subscr	The Subscription.

LNCPP20953

getCacheMaxSize()

Retrieves the maximum size of the cache.

LNCPP20954Syntax

unsigned int getCacheMaxSize() const;

LNCPP20955

getCacheOptSize()

Retrieves the Cache optimal heap size.

LNCPP20956Syntax

unsigned int getCacheOptSize() const;

LNCPP20957

getCacheSortedFlush()

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

LNCPP20958Syntax

bool getCacheSortedFlush() const;

LNCPP20959

getCurrentHeapSize()

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

LNCPP20960Syntax

unsigned int getCurrentHeapSize() const;

LNCPP20961

getLDAPAdminContext()

Returns the administrative context when using LDAP open notification registration.

LNCPP20962Syntax

string getLDAPAdminContext() const;

LNCPP20963

getLDAPAuthentication()

Returns the authentication mode when using LDAP open notification registration.

LNCPP20964Syntax

unsigned int getLDAPAuthentication() const;

LNCPP20965

getLDAPHost()

Returns the host on which the LDAP server runs.

LNCPP20966Syntax

string getLDAPHost() const;

LNCPP20967

getLDAPPort()

Returns the port on which the LDAP server is listening.

LNCPP20968Syntax

unsigned int getLDAPPort() const;

LNCPP20969

getMap()

Returns a pointer to the map for this environment.

LNCPP20970Syntax

Map *getMap() const;

LNCPP20971

getOCIEnvironment()

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

LNCPP20972Syntax

OCIEnv *getOCIEnvironment() const;

LNCPP20973

getXAConnection()

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

LNCPP20974Syntax

Connection* getXAConnection(
   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).

LNCPP20975

getXAEnvironment()

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

LNCPP20976Syntax

Environment *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).

LNCPP20977

releaseXAConnection()

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

LNCPP20978Syntax

void releaseXAConnection(
   Connection* conn);

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

LNCPP20979

releaseXAEnvironment()

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

LNCPP20980Syntax

void releaseXAEnvironment(
   Environment* env);

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

LNCPP20981

setCacheMaxSize()

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

LNCPP20982Syntax

void setCacheMaxSize(
   unsigned int maxSize);

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

LNCPP20983

setCacheOptSize()

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

LNCPP20984Syntax

void setCacheOptSize(
   unsigned int optSize);

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

LNCPP20985

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 before flushing from client cache.

LNCPP20986Syntax

void setCacheSortedFlush(
   bool flag);

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

LNCPP20987

setLDAPAdminContext()

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

LNCPP20988Syntax

void setLDAPAdminContext(
   const string &ctx);

Parameter	Description
ctx	The client context

LNCPP20989

setLDAPAuthentication()

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

LNCPP20990Syntax

void setLDAPAuthentication(
   unsigned int mode);

Parameter	Description
mode	The authentication mode

LNCPP20991

setLDAPHostAndPort()

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

LNCPP20992Syntax

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

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

LNCPP20993

setLDAPLoginNameAndPassword()

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

LNCPP20994Syntax

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

Parameter	Description
login	The login name
passwd	The login password

LNCPP20995

terminateConnection()

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

LNCPP20996Syntax

void terminateConnection(
   Connection *connection);

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

LNCPP20997

terminateConnectionPool()

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

LNCPP20998Syntax

void terminateConnectionPool(
   ConnectionPool *poolPointer);

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

LNCPP20999

terminateEnvironment()

Closes the environment, and frees all related system resources.

LNCPP21000Syntax

void terminateEnvironment(
   Environment *env);

Parameter	Description
env	Environment to be closed.

LNCPP21001

terminateStatelessConnectionPool()

Destroys the specified StatelessConnectionPool.

LNCPP21002Syntax

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

Parameter	Description
poolPointer	The `StatelessConnectionPool` to be destroyed.
mode	`DestroyMode` as defined Table 13-41: `DEFAULT` or `SPF_FORCE`.