Environmentクラス

13.14 Environmentクラス

Environmentクラスは、OCCIオブジェクトのメモリーやその他のリソースを管理するためのOCCI環境を提供します。

アプリケーションは複数のOCCI環境を保持できます。各環境ごとに、独自のヒープやスレッド・セーフティmutexを持つことができます。

表13-17 Environmentクラスで使用される列挙値

属性オプション

属性	オプション
Mode	`DEFAULT`は、Environmentオブジェクトの作成に使用されます。スレッド・セーフティやオブジェクトはサポートしません。 `OBJECT`は、Environmentオブジェクトの作成用です。オブジェクト機能を使用します。 `SHARED`は、Environmentオブジェクトの作成用です。 `NO_USERCALLBACKS`は、Environmentオブジェクトの作成用です。ユーザー・コールバックはサポートしません。 `THREADED_MUTEXED`は、Environmentオブジェクト作成用のスレッド・セーフ・モードです。OCCIにより内部的にmutex化されます。 `THREADED_UNMUTEXED`は、Environmentオブジェクト作成用のスレッド・セーフ・モードです。クライアントがmutex化を受け持ちます。 `EVENTS`は、Oracle Streams Advanced Queuingで使用されるイベント通知の登録をサポートします。 `USE_LDAP`は、LDAPによる登録をサポートします。

Mode

DEFAULTは、Environmentオブジェクトの作成に使用されます。スレッド・セーフティやオブジェクトはサポートしません。
OBJECTは、Environmentオブジェクトの作成用です。オブジェクト機能を使用します。
SHAREDは、Environmentオブジェクトの作成用です。
NO_USERCALLBACKSは、Environmentオブジェクトの作成用です。ユーザー・コールバックはサポートしません。
THREADED_MUTEXEDは、Environmentオブジェクト作成用のスレッド・セーフ・モードです。OCCIにより内部的にmutex化されます。
THREADED_UNMUTEXEDは、Environmentオブジェクト作成用のスレッド・セーフ・モードです。クライアントがmutex化を受け持ちます。
EVENTSは、Oracle Streams Advanced Queuingで使用されるイベント通知の登録をサポートします。
USE_LDAPは、LDAPによる登録をサポートします。

表13-18 Environmentメソッドの概要

メソッド	概要
createConnection()	指定したデータベースへの接続を確立します。
createConnectionPool()	接続プールを作成します。
createEnvironment()	`Environment`オブジェクトを作成します。
createStatelessConnectionPool()	ステートレスな接続プールを作成します。
enableSubscription()	サブスクリプション通知を有効化します
disableSubscription()	サブスクリプション通知を無効化します
getCacheMaxSize()	キャッシュの最大ヒープ・サイズを取り出します。
getCacheOptSize()	キャッシュの最適ヒープ・サイズを取り出します。
getCacheSortedFlush()	キャッシュ・ソート・フラグの設定を取り出します。
getClientVersion()	クライアント・ライブラリのバージョンを戻します。
getCurrentHeapSize()	現行の環境にあるすべてのオブジェクトに現在割り当てられているメモリー・サイズを戻します。
getLDAPAdminContext()	LDAPのオープン通知登録を使用する場合の管理コンテキストを戻します。
getLDAPAuthentication()	LDAPのオープン通知登録を使用する場合の認証モードを戻します。
getLDAPHost()	LDAPサーバーが稼働しているホストを戻します。
getLDAPPort()	LDAPサーバーがリスニングしているポートを戻します。
getMap()()	現行の環境のマップを戻します。
getNLSLanguage()	現行の環境のNLS言語を戻します。
getNLSTerritory()	現行の環境のNLS地域を戻します。
getOCIEnvironment()	現行の環境に関連付けられているOCI環境を戻します。
getXAConnection()	データベースへのXA接続を作成します。
getXAEnvironment()	XA `Environment`オブジェクトを作成します。
releaseXAConnection()	getXAConnection()のコールにより割り当てられたリソースをすべて解放します。
releaseXAEnvironment()	getXAEnvironment()のコールにより割り当てられたリソースをすべて解放します。
setCacheMaxSize()	クライアント側オブジェクト・キャッシュの最大サイズを、最適サイズの率として指定します。
setCacheOptSize()	クライアント側オブジェクト・キャッシュの最適サイズをバイト単位で指定します。
setCacheSortedFlush()	フラッシュする前に表の順序でキャッシュをソートするかどうかを指定します。
setLDAPAdminContext()	LDAPクライアントの管理コンテキストを指定します。
setLDAPAuthentication()	LDAPの認証モードを指定します。
setLDAPHostAndPort()	LDAPサーバーのホストとポートを指定します。
setLDAPLoginNameAndPassword()	LDAPサーバーへの接続時のログイン名とパスワードを指定します。
setNLSLanguage()	現行の環境のNLS言語を指定します。
setNLSTerritory()	現行の環境のNLS地域を指定します。
terminateConnection()	接続プールをクローズし、関連しているすべてのリソースを解放します。
terminateConnectionPool()	接続プールをクローズし、関連しているすべてのリソースを解放します。
terminateEnvironment()	環境を破棄します。
terminateStatelessConnectionPool()	ステートレスな接続プールをクローズし、関連しているすべてのリソースを解放します。

13.14.1 createConnection()

このメソッドは、指定したデータベースへの接続を確立します。

構文	説明
Connection * createConnection( const string &userName, const string &password, const string &connectString="")=0;	デフォルト接続を作成します。`userName`と`password`が`NULL`の場合、接続は外部認証できます。
Connection * createConnection( const UString &userName, const UString &password, const UString &connectString)=0;	接続を作成します(Unicodeサポート)。クライアントの`Environment`を`OCCIUTIF16`モードで初期化する必要があります。
Connection * createConnection( const string &userName, const string &password, const string &connectString, const string &connectionClass, const Connection::Purity &purity)=0;	データベース常駐接続プーリングの接続を作成します。
Connection * createConnection( const UString &userName, const UString &password, const UString &connectString, const UString &connectionClass const Connection::Purity &purity)=0;	データベース常駐接続プーリングの接続を作成します(Unicodeサポート)。クライアントの`Environment`を`OCCIUTIF16`モードで初期化する必要があります。

パラメータ	説明
userName	接続に使用するユーザー名を指定します。
password	ユーザーのパスワードを指定します。
connectString	接続先データベースを指定します。
purity	データベース常駐接続プーリングで使用される接続の純正値を指定します。`SELF`または`NEW`のいずれかとなります。
connectionClass	データベース常駐接続プーリングで使用されるConnectionクラスを指定します。

13.14.2 createConnectionPool()

指定したパラメータに基づいて接続プールを作成します。

構文説明

構文	説明
ConnectionPool* createConnectionPool( const string &poolUserName, const string &poolPassword, const string &connectString = "", unsigned int minConn = 0, unsigned int maxConn = 1, unsigned int incrConn = 1)=0;	デフォルト接続プールを作成します。
ConnectionPool* createConnectionPool( const UString &poolUserName, const UString &poolPassword, const UString &connectString, unsigned int minConn = 0, unsigned int maxConn = 1, unsigned int incrConn = 1)=0;	接続プールを作成します(Unicodeサポート)。クライアントの`Environment`を`OCCIUTIF16`モードで初期化する必要があります。

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

デフォルト接続プールを作成します。

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

接続プールを作成します(Unicodeサポート)。クライアントのEnvironmentをOCCIUTIF16モードで初期化する必要があります。

パラメータ	説明
poolUserName	プールのユーザー名を指定します。
poolPassword	プールのパスワードを指定します。
connectString	サーバーの接続文字列を指定します。
minConn	プール内の最小接続数を指定します。このメソッドによって、この最小数の接続がオープンします。追加の接続は、必要な場合のみオープンします。通常、`minConn`は、アプリケーションで予定している同時実行文の数に設定する必要があります。
maxConn	プールの接続の最大数。有効な値は、1以上です。
incrConn	現行の接続数が`maxConn`より少ない場合に、オープンする接続の増分数を指定します。有効な値は、1以上です。

13.14.3 createEnvironment()

Environmentオブジェクトを作成します。このオブジェクトは、setMemMgrFunctions()メソッドに指定されているメモリー管理関数を使用して作成されます。メモリー管理関数が指定されていない場合、OCCIはデフォルトの関数を使用します。最終的には、Environmentオブジェクトをクローズし、取得したシステム・リソースをすべて解放する必要があります。

指定したModeがTHREADED_MUTEXED またはTHREADED_UNMUTEXEDの場合、3種類のメモリー管理関数はすべてスレッド・セーフであることが必要です(表13-17の定義を参照)。

構文説明

構文	説明
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);	デフォルト環境を作成します。
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);	指定したキャラクタ・セットIDと`NCHAR`キャラクタ・セットIDを使用して環境を作成します(Unicodeサポート)。クライアントの`Environment`を`OCCIUTIF16`モードで初期化する必要があります。

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

デフォルト環境を作成します。

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

指定したキャラクタ・セットIDとNCHARキャラクタ・セットIDを使用して環境を作成します(Unicodeサポート)。クライアントのEnvironmentをOCCIUTIF16モードで初期化する必要があります。

パラメータ	説明
mode	値は`Mode`の一部として表13-17に定義されている`DEFAULT`、`THREADED_MUTEXED`、`THREADED_UNMUTEXED`、`OBJECT`です。
ctxp	ユーザー定義のメモリー管理関数のためのコンテキスト・ポインタを指定します。
size	ユーザー定義のメモリー割当て関数によって割り当てられるメモリーのサイズを指定します。
newsize	再割当てされるメモリーの新規サイズを指定します。
memptr	新規サイズに再割当てする必要のある既存のメモリーを指定します。
malocfp	ユーザー定義のメモリー割当て関数です。
ralocfp	ユーザー定義のメモリー再割当て関数です。
`mfreefp`	ユーザー定義のメモリー解放関数です。
`charset`	`NLS_LANG`で指定したIDで置き換えるキャラクタ・セットIDを指定します。
`ncharset`	`NLS_NCHAR`で指定したIDで置き換えるキャラクタ・セットIDを指定します。

13.14.4 createStatelessConnectionPool()

指定したプール属性を使用してStatelessConnectionPoolオブジェクトを作成します。

構文説明

構文	説明
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);	`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);	`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);

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

UStringをサポートする場合です。

パラメータ	説明
poolUserName	プールのユーザー名を指定します。
poolPassword	プールのパスワードを指定します。
connectString	サーバーの接続文字列を指定します。
maxConn	プール内でオープンできる最大接続数を指定します。それ以上はセッションをオープンできません。
minConn	プール内で最初に作成される接続の数を指定します。このパラメータが考慮されるのは、`PoolType`が`HOMOGENEOUS`に設定されている場合のみです(表13-41の定義を参照)。
incrConn	すべてのオープン接続がビジーの場合にプールの増分となる接続数を、`maxConn`パラメータで指定した最大オープン接続数の範囲内で指定します。このパラメータが考慮されるのは、`PoolType`が`HOMOGENEOUS`に設定されている場合のみです(表13-41の定義を参照)。
pType	接続プールの`PoolType`は、表13-41の定義を参照してください。

13.14.5 enableSubscription()

サブスクリプション通知を有効化します。

構文

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

パラメータ	説明
sub	サブスクリプションを指定します。

13.14.6 disableSubscription()

サブスクリプション通知を無効化します。

構文

void disableSubscription(
   Subscription &subscr);

パラメータ	説明
subscr	サブスクリプションを指定します。

13.14.7 getCacheMaxSize()

キャッシュの最大サイズを取得します。

構文

unsigned int getCacheMaxSize() const;

13.14.8 getCacheOptSize()

キャッシュの最適ヒープ・サイズを取り出します。

構文

unsigned int getCacheOptSize() const;

13.14.9 getCacheSortedFlush()

キャッシュ・ソート・フラグの現在の設定(TRUEまたはFALSE)を取り出します。

構文

bool getCacheSortedFlush() const;

13.14.10 getCurrentHeapSize()

この環境のすべてのオブジェクトに現在割り当てられているメモリー・サイズを戻します。

構文

unsigned int getCurrentHeapSize() const;

13.14.11 getLDAPAdminContext()

LDAPのオープン通知登録を使用する場合の管理コンテキストを戻します。

構文

string getLDAPAdminContext() const;

13.14.12 getLDAPAuthentication()

LDAPのオープン通知登録を使用する場合の認証モードを戻します。

構文

unsigned int getLDAPAuthentication() const;

13.14.13 getLDAPHost()

LDAPサーバーが稼働しているホストを戻します。

構文

string getLDAPHost() const;

13.14.14 getLDAPPort()

LDAPサーバーがリスニングしているポートを戻します。

構文

unsigned int getLDAPPort() const;

13.14.15 getMap()

この環境のマップへのポインタを戻します。

構文

Map *getMap() const;

13.14.16 getNLSLanguage()

現行の環境のNLS言語を戻します。

構文

string getNLSLanguage() const;

13.14.17 getNLSTerritory()

現行の環境のNLS地域を戻します。

構文

string getNLSTerritory() const;

13.14.18 getOCIEnvironment()

この環境に関連付けられているOCI環境へのポインタを戻します。

構文

OCIEnv *getOCIEnvironment() const;

13.14.19 getXAConnection()

XAライブラリによりオープンされている、オブジェクトに対応するOCCI Connectionオブジェクトへのポインタを戻します。

構文

Connection* getXAConnection(
   const string &dbname);

パラメータ	説明
dbname	データベース名を指定します。このデータベース名は、Open Stringに指定された(およびリソース・マネージャへの接続に使用される)オプションの`dbname`と同じです。

13.14.20 getXAEnvironment()

XAライブラリによりオープンされているオブジェクトに対応するOCCI Environmentオブジェクトへのポインタを戻します。

構文

Environment *getXAEnvironment(
   const string &dbname);

パラメータ	説明
dbname	データベース名を指定します。このデータベース名は、Open Stringに指定された(およびリソース・マネージャへの接続に使用される)オプションの`dbname`と同じです。

13.14.21 releaseXAConnection()

getXAConnection()メソッドにより割り当てられたリソースをすべて解放/割当て解除します。

構文

void releaseXAConnection(
   Connection* conn);

パラメータ	説明
conn	getXAConnection()メソッドから戻された接続を指定します。

13.14.22 releaseXAEnvironment()

getXAEnvironment()メソッドにより割り当てられたリソースをすべて解放/割当て解除します。

構文

void releaseXAEnvironment(
   Environment* env);

パラメータ	説明
env	getXAEnvironment()メソッドから戻された環境を指定します。

13.14.23 setCacheMaxSize()

クライアント側オブジェクト・キャッシュの最大サイズを、最適サイズの率として設定します。デフォルト値は10%です。

構文

void setCacheMaxSize(
   unsigned int maxSize);

パラメータ	説明
maxSize	最大サイズ値を率として指定します。

13.14.24 setCacheOptSize()

クライアント側のオブジェクト・キャッシュの最適サイズをバイト単位で設定します。デフォルト値は8MBです。

構文

void setCacheOptSize(
   unsigned int optSize);

パラメータ	説明
optSize	最適サイズ値をバイト単位で指定します。

13.14.25 setCacheSortedFlush()

キャッシュ・フラッシング・プロトコルを設定します。デフォルト(flag=FALSE)では、キャッシュ内のオブジェクトは修正順にフラッシュされます。サーバー側の性能を向上するには、flag=TRUEに設定します。それにより、キャッシュ内のオブジェクトはクライアント・キャッシュからフラッシュされる前に表の順にソートされます。

構文

void setCacheSortedFlush(
   bool flag);

パラメータ	説明
flag	`FALSE` (デフォルト): ソートされません。`TRUE`: 表の順にソートされます。

13.14.26 setLDAPAdminContext()

クライアントの管理コンテキストを設定します。通常は、LDAPサーバーのOracle RDBMS LDAPスキーマのルートです。

構文

void setLDAPAdminContext(
   const string &ctx);

パラメータ	説明
ctx	クライアントのコンテキストを指定します。

13.14.27 setLDAPAuthentication()

認証モードを指定します。現在サポートされている値は0x1、つまり簡易認証(ユーザー名/パスワード認証)のみです。

構文

void setLDAPAuthentication(
   unsigned int mode);

パラメータ	説明
mode	認証モードを指定します。

13.14.28 setLDAPHostAndPort()

LDAPサーバーが稼働しているホストと、要求をリスニングしているポートを指定します。

構文

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

パラメータ	説明
host	LDAPのホストを指定します。
port	LDAPのポートを指定します。

13.14.29 setLDAPLoginNameAndPassword()

LDAPサーバーへの接続時に使用するログイン識別名とパスワードを指定します。

構文

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

パラメータ	説明
login	ログイン名を指定します。
passwd	ログイン・パスワードを指定します。

13.14.30 setNLSLanguage()

現行の環境のNLS言語を指定します。この設定は、このメソッドのコール後に作成された接続に対して有効です。この設定は、プロセスの環境変数NLS_LANGを介して設定された値をオーバーライドします。

構文

void setNLSLanguage(
   const string &lang);

パラメータ	説明
lang	現行の環境の言語

13.14.31 setNLSTerritory()

現行の環境のNLS地域を指定します。この設定は、このメソッドのコール後に作成された接続に対して有効です。この設定は、プロセスの環境変数NLS_LANGを介して設定された値をオーバーライドします。

構文

void setNLSTerritory(
   const string &Terr);

パラメータ	説明
Terr	現行の環境の地域

13.14.32 terminateConnection()

環境への接続をクローズし、関連しているすべてのシステム・リソースを解放します。

構文

void terminateConnection(
   Connection *connection);

パラメータ	説明
connection	終了する接続インスタンスへのポインタを指定します。

13.14.33 terminateConnectionPool()

接続プールの接続をクローズし、関連しているすべてのシステム・リソースを解放します。

構文

void terminateConnectionPool(
   ConnectionPool *poolPointer);

パラメータ	説明
poolPointer	終了する接続プール・インスタンスへのポインタを指定します。

13.14.34 terminateEnvironment()

環境をクローズし、関連しているすべてのシステム・リソースを解放します。

構文

void terminateEnvironment(
   Environment *env);

パラメータ	説明
env	クローズする環境を指定します。

13.14.35 terminateStatelessConnectionPool()

指定したStatelessConnectionPoolを破棄します。

構文

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

パラメータ	説明
poolPointer	破棄する`StatelessConnectionPool`を指定します。
mode	表13-41に定義されている`DestroyMode` (`DEFAULT`または`SPF_FORCE`)を指定します。