UCPからの接続の流用について

3.1.1 UCPからの接続の流用の概要

UCP APIは、2つのプール対応のデータソースを備えています。1つは標準接続を流用するためのものであり、もう1つはXA接続を流用するためのものです。これらのデータソースは、UCP JDBC接続プール機能にアクセスでき、接続の流用に使用される一連のgetConnectionメソッドを備えています。XAと非XAのどちらのUCP JDBC接続プールにも同じプール機能があります。

UCP JDBC接続プールは、使用可能な接続と流用された接続の両方を保持します。アプリケーションが使用可能な接続と一致する接続の流用をリクエストすると、プールの接続が再利用されます。プール内の使用可能な接続がリクエストされた接続と一致しない場合は、新しい接続が作成されます。使用可能な接続と流用された接続の数は、プール・サイズ、タイムアウト間隔および検証ルールなどのプールのプロパティによって異なります。

3.1.2 プール対応のデータソースの使用方法

UCPは、データベースに接続するために使用されるプール対応のデータソース(oracle.ucp.jdbc.PoolDataSource)を提供します。oracle.ucp.jdbc.PoolDataSourceFactoryファクトリ・クラスは、プール対応のデータソース・インスタンスを作成するgetPoolDataSource()メソッドを備えています。次に例を示します。

PoolDataSource  pds = PoolDataSourceFactory.getPoolDataSource();

プール対応のデータソースには、実際の物理的な接続を取得するためにコネクション・ファクトリ・クラスが必要です。通常、コネクション・ファクトリはJDBCドライバの一部として提供され、データソースそのものにすることができます。UCP JDBC接続プールでは任意のJDBCドライバを使用して物理接続を作成することができ、作成した接続はプールで管理されます。setConnectionFactoryClassName(String)メソッドは、プール対応のデータソース・インスタンスにコネクション・ファクトリを定義するために使用されます。次の例では、JDBCドライバに付属するOracleのoracle.jdbc.pool.OracleDataSourceコネクション・ファクトリ・クラスを使用しています。他のベンダーのJDBCドライバを使用している場合は、該当するコネクション・ファクトリ・クラスについてベンダーのドキュメントを参照してください。

pds.setConnectionFactoryClassName("oracle.jdbc.pool.OracleDataSource");

コネクション・ファクトリ・クラスに加えて、プール対応のデータソースには、データベースへの接続に使用されるURL、ユーザー名およびパスワードが必要です。プール対応のデータソース・インスタンスは、これらの各プロパティを設定するメソッドを備えています。次の例では、Oracle JDBC Thinドライバの構文を使用しています。他のベンダーのJDBCドライバを使用している場合は、使用する適切なURL構文についてベンダーのドキュメントを参照してください。

pds.setURL("jdbc:oracle:thin:@//localhost:1521/XE");
pds.setUser("user");
pds.setPassword("password");

3.1.3 プール対応のXAデータソースの使用方法

UCPは、分散トランザクションに参加できるXA接続に使用されるプール対応のXAデータソース(oracle.ucp.jdbc.PoolXADataSource)を提供します。UCP JDBC XAプールには、非XAのUCP JDBCプールと同じ機能があります。oracle.ucp.jdbc.PoolDataSourceFactoryファクトリ・クラスは、プール対応のXAデータソース・インスタンスを作成するgetPoolXADataSource()メソッドを備えています。次に例を示します。

PoolXADataSource  pds = PoolDataSourceFactory.getPoolXADataSource();

プール対応のXAデータソース・インスタンスには、非XAデータソース・インスタンスと同様、実際の物理的な接続を取得するためにコネクション・ファクトリ、URL、ユーザー名およびパスワードが必要です。これらのプロパティは、非XAデータソース・インスタンスと同様の方法(前述参照)で設定されます。しかし、XA接続を取得するには、XA固有のコネクション・ファクトリ・クラスが必要です。通常、XAコネクション・ファクトリはJDBCドライバの一部として提供され、データソースそのものにすることができます。次の例では、JDBCドライバに付属するOracleのoracle.jdbc.xa.client.OracleXADataSource XAコネクション・ファクトリ・クラスを使用しています。他のベンダーのJDBCドライバを使用している場合は、該当するXAコネクション・ファクトリ・クラスについてベンダーのドキュメントを参照してください。

pds.setConnectionFactoryClassName("oracle.jdbc.xa.client.OracleXADataSource");
pds.setURL("jdbc:oracle:thin:@//localhost:1521/XE");
pds.setUser("user");
pds.setPassword("password");

最後に、プール対応のXAデータソースは、一連のgetXAConnectionメソッドを備えています。これらのメソッドは、javax.sql.XAConnectionタイプの接続ハンドルをプールから流用するために使用されます。getXAConnectionメソッドは、前述のgetConnectionメソッドと同じです。次の例では、XA接続の流用を示します。

PoolXADataSource  pds = PoolDataSourceFactory.getPoolXADataSource();

pds.setConnectionFactoryClassName("oracle.jdbc.xa.client.OracleXADataSource");
pds.setURL("jdbc:oracle:thin:@//localhost:1521/XE");
pds.setUser("<user>");
pds.setPassword("<password>");

XAConnection conn = pds.getXAConnection();

関連トピック

UCPでの接続のラベル付け

3.1.4 接続プロパティの設定

Oracleのコネクション・ファクトリでは、特定の機能を使用して接続を構成するプロパティがサポートされます。UCPプール対応のデータソースは、setConnectionProperties(Properties)メソッドを備えています。このメソッドは、指定されたコネクション・ファクトリにプロパティを設定するために使用されます。次の例では、OracleのJDBCドライバの接続プロパティの設定を示します。他のベンダーのJDBCドライバを使用している場合は、ベンダー固有のドキュメントを参照して、この方法でのプロパティの設定がサポートされているかどうか、またどのプロパティが使用できるかを確認してください。

Properties connProps = new Properties();
connProps.put("fixedString", false);
connProps.put("remarksReporting", false);
connProps.put("restrictGetTables", false);
connProps.put("includeSynonyms", false);
connProps.put("defaultNChar", false);
connProps.put("AccumulateBatchResult", false);

pds.setConnectionProperties(connProps);

UCP JDBC接続プールは、プールの作成後および使用中にsetConnectionPropertiesがコールされた場合、作成済の接続を削除しません。

3.1.5 JNDIを使用した接続の流用

接続は、プール対応のデータソースのJNDIルックアップを実行し、戻されたオブジェクトでgetConnection()をコールすることで、接続プールから流用できます。まず、プール対応のデータソースをJNDIコンテキストおよび論理名にバインドする必要があります。これは、オブジェクト参照の登録および検索が可能な、ネーミングおよびディレクトリ・サービス用のサービス・プロバイダ・インタフェース(SPI)をアプリケーションが実装していることを前提とします。

次の例では、Sun社のファイル・システムJNDIサービス・プロバイダを使用しています。このサービス・プロバイダは、次のJNDIソフトウェア・ダウンロード・ページからダウンロードできます。

http://www.oracle.com/technetwork/java/index.html

この例では、初期コンテキストを作成した後、MyPooledDataSourceという名前にバインドされているプール対応のデータソースのルックアップを実行しています。その後、戻されたオブジェクトを使用して接続プールから接続を流用しています。

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,   
   "com.sun.jndi.fscontext.RefFSContextFactory");
env.put(Context.PROVIDER_URL, "file:/tmp");

ctx = new InitialContext(env);

PoolDataSource jpds = (PoolDataSource)ctx.lookup(MyPooledDataSource);
Connection conn = jpds.getConnection();

この例では、MyPoolDataSourceをコンテキストにバインドする必要があります。次に例を示します。

PoolDataSource  pds = PoolDataSourceFactory.getPoolDataSource();

pds.setConnectionFactoryClassName("oracle.jdbc.pool.OracleDataSource");
pds.setURL("jdbc:oracle:thin:@//localhost:1521/XE");
pds.setUser("<user>");
pds.setPassword("<password>");

ctx.bind(MyPooledDataSource, pds);

3.1.6 接続初期化コールバックについて

接続初期化コールバックにより、アプリケーションおよびフレームワークはユニバーサル接続プールから取得される接続を初期化できます。プールからの接続のチェックアウトのたびに、またファイルオーバー中に再接続が成功するたびに、初期化コールバックが実行されます。

次の項で、初期化コールバックについて説明します。

3.1.6.1 接続初期化コールバックの概要

変更できないため、アプリケーションで接続ラベリングを使用しない場合、このようなアプリケーションには接続初期化コールバックが提供されます。

登録されると、接続がプールから流用されるたびに、またリカバリ可能なエラー後に再接続が成功するたびに、初期化コールバックは実行されます。実行時とリプレイ時の両方に同じコールバックを使用すると、元のセッションの確立時に使用されたのとまったく同じ初期化が実行時に確実に再設定されます。コールバックの起動が失敗した場合、リプレイはその接続で無効になります。

3.1.6.2 初期化コールバックの作成

UCP接続初期化コールバックを作成するために、アプリケーションはoracle.ucp.jdbc.ConnectionInitializationCallbackインタフェースを実装しています。このインタフェースには、次のメソッドがあります。

void initialize(java.sql.Connection connection) throws SQLException;

注意:

コールバックは、接続プールごとに1つ作成されます。
このコールバックは、ラベリング・コールバックが接続プール用に登録されている場合、使用されません。

例

次の例では、単純な初期化コールバックの作成方法を示します。

import oracle.ucp.jdbc.ConnectionInitializationCallback;
class MyConnectionInitializationCallback implements ConnectionInitializationCallback
{
  public MyConnectionInitializationCallback()
  {
    ...
  }
  public void initialize(java.sql.Connection connection) throws SQLException
  {
     // Reset the state for the connection, if necessary (like ALTER SESSION)
  }
}

3.1.6.3 初期化コールバックの登録

UCPには、接続初期化コールバックを登録するために、oracle.ucp.jdbc.PoolDataSourceインタフェースにregisterConnectionInitializationCallbackメソッドが用意されています。

public void registerConnectionInitializationCallback (ConnectionInitializationCallback cbk) throws SQLException;

コールバックは、各接続プール・インスタンスに1つ登録できます。

3.1.6.4 初期化コールバックの削除または登録解除

UCPには、接続初期化コールバックを登録解除するために、oracle.ucp.jdbc.PoolDataSourceインタフェースにunregisterConnectionInitializationCallbackメソッドが用意されています。

public void unregisterConnectionInitializationCallback (ConnectionInitializationCallback cbk) throws SQLException;