| Oracle® Fusion Middleware Oracle WebLogic Server JDBCデータ・ソースの管理 12c (12.2.1.3.0) E90329-05 |
|
 前 |
 次 |
この章では、WebLogic JDBCでラベル接続を使用する方法について説明します。この章の内容は以下のとおりです。
多くの場合、アプリケーションは、接続プールから取得した接続を使用する前に初期化します。初期化は一様ではなく、アプリケーション・コード内でメソッド・コールを必要とする単純な状態の再初期化や、ネットワーク上でのラウンドトリップを必要とするデータベース操作などがあります。このような初期化のコストは非常に高い場合があります。接続のラベル付けを使用すると、アプリケーションが接続に任意の名前/値のペアを付けることができます。
アプリケーションは、必要なラベルが付いた接続を接続プールにリクエストできます。接続ラベリング機能は、ユーザー定義キーまたは値に意味を与えません。ユーザー定義キーおよび値の意味は、アプリケーションでのみ定義されます。
接続ラベリングの例には、ロール、NLS言語設定、トランザクション分離レベル、ストアド・プロシージャ・コール、またはリソースによる処理の実行の前に接続上で必要となるその他のコストのかかる状態の初期化があります。
接続ラベリングは、アプリケーション・ドリブンであり、次を必要とします。
oracle.ucp.jdbc.LabelableConnectionインタフェースは、接続ラベルの適用および削除と、接続に設定されているラベルの取得に使用されます。
oracle.ucp.ConnectionLabelingCallbackインタフェースは、リクエストされたラベルが付いた接続がすでに存在するかどうかを判断するラベリング・コールバックの作成に使用されます。接続が存在しない場合、このインタフェースを使用して、現行の接続を必要に応じて構成できます。
接続ラベリング・コールバックの詳細は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのJDBCデータ・ソース: 接続: 接続プールを参照してください。
ラベリング・コールバックは、接続プールでラベル付けされた接続を選択する方法を定義するために使用され、アプリケーションに戻す前に、選択された接続の構成ができます。接続ラベリング機能を使用するアプリケーションは、コールバックを実装する必要があります。
ラベリング・コールバックは、ラベル付けされた接続がリクエストされていながら、リクエストされたラベルと一致する接続がプールにない場合に使用されます。コールバックは、リクエストされたラベルと一致するように再構成するために必要となる作業量が最も少ない接続を特定した後、アプリケーションに戻す前に接続のラベルを更新できるようにします。
ノート:
接続ラベリングは、RMIを使用するクライアント・アプリケーションではサポートされません。Oracle WebLogic Server JDBCアプリケーションの開発のWebLogic RMIドライバ(非推奨)を参照してください。
ラベリング・コールバックは、接続プールでラベル付けされた接続を選択する方法を定義するために使用され、アプリケーションに戻す前に、選択された接続の構成ができます。oracle.ucp.ConnectionLabelingCallbackインタフェースを実装して、ラベリング・コールバックを作成する方法を学習します。
ラベリング・コールバックを作成するには、アプリケーションにoracle.ucp.ConnectionLabelingCallbackインタフェースを実装します。コールバックは、接続プールごとに1つ作成されます。このインタフェースは、次に示す2つのメソッドを備えています。
public int cost(Properties requestedLabels, Properties currentLabels);
public boolean configure(Properties requestedLabels, Connection conn);
接続プール内で使用可能な各接続に対して繰り返します。接続ごとにcostメソッドをコールします。costメソッドの結果は、接続を必要な状態に再構成するために必要なコストの見積りを表す整数値です。値が大きいほど、接続の再構成にはコストがかかります。接続プールは、常に最も低いコスト値の接続を戻します。アルゴリズムは次のとおりです。
costメソッドがある接続について0を戻した場合、その接続が適合となります(これは、requestedLabelsとcurrentLabelsが同等ということを示しません)。接続プールは、検出された接続に対してconfigureをコールせず、単に接続を戻します。
costメソッドが0以外の値(負または正の整数)を戻した場合、コスト値が0の接続を検出するか、使用可能な接続がなくなるまで繰り返します。
すべての使用可能な接続に対して繰り返して、接続の最低コストがInteger.MAX_VALUE(デフォルトでは2147483647)となった場合、プール内に接続リクエストを満たす接続はありません。新しい接続を作成し、それに対しconfigureメソッドをコールし、この新しい接続を戻します。プールが最大プール・サイズに達している(新しい接続を作成できない)場合は、SQL例外をスローするか、接続待機タイムアウト属性が指定されていれば待機するかのいずれかです。
すべての使用可能な接続に対して繰り返して、接続の最低コストがInteger.MAX_VALUEよりも低い場合、その接続に対してconfigureメソッドをコールし、その接続を戻します。複数の接続がInteger.MAX_VALUEを下回る場合は、最低コストの接続を戻します。
追加のgetRequestedLabels()メソッドを含む拡張コールバック・インタフェースoracle.ucp.jdbc.ConnectionLabelingCallbackもあります。リクエストしたラベルが提供されておらず、登録されているインスタンスがある場合、getConnection()時にgetRequestedLabelsが呼び出されます。これは、標準のjava.sql.Datasource getConnection()メソッドが使用され、そのgetConnection()コールでラベル情報が指定されていない場合に実行されます。
次のコード例では、costとconfigureの両メソッドを実装する単純なラベリング・コールバックの実装を示します。このコールバックは、特定のトランザクション分離レベルで初期化されるラベル付けされた接続の検出に使用されます。
例13-1 ラベリング・コールバック
import oracle.ucp.jdbc.ConnectionLabelingCallback;
import oracle.ucp.jdbc.LabelableConnection;
import java.util.Properties;
import java.util.Map;
import java.util.Set;
import weblogic.jdbc.extensions.WLDataSource;
class MyConnectionLabelingCallback implements ConnectionLabelingCallback {
public MyConnectionLabelingCallback() {
}
public int cost(Properties reqLabels, Properties currentLabels) {
// Case 1: exact match
if (reqLabels.equals(currentLabels)) {
System.out.println("## Exact match found!! ##");
return 0;
}
// Case 2: some labels match with no unmatched labels
String iso1 = (String) reqLabels.get("TRANSACTION_ISOLATION");
String iso2 = (String) currentLabels.get("TRANSACTION_ISOLATION");
boolean match =
(iso1 != null && iso2 != null && iso1.equalsIgnoreCase(iso2));
Set rKeys = reqLabels.keySet();
Set cKeys = currentLabels.keySet();
if (match && rKeys.containsAll(cKeys)) {
System.out.println("## Partial match found!! ##");
return 10;
}
// No label matches to application's preference.
// Do not choose this connection.
System.out.println("## No match found!! ##");
return Integer.MAX_VALUE;
}
public boolean configure(Properties reqLabels, Object conn) {
try {
String isoStr = (String) reqLabels.get("TRANSACTION_ISOLATION");
((Connection)conn).setTransactionIsolation(Integer.valueOf(isoStr));
LabelableConnection lconn = (LabelableConnection) conn;
// Find the unmatched labels on this connection
Properties unmatchedLabels =
lconn.getUnmatchedConnectionLabels(reqLabels);
// Apply each label <key,value> in unmatchedLabels to conn
for (Map.Entry<Object, Object> label : unmatchedLabels.entrySet()) {
String key = (String) label.getKey();
String value = (String) label.getValue();
lconn.applyConnectionLabel(key, value);
}
} catch (Exception exc) {
return false;
}
return true;
}
public java.util.Properties getRequestedLabels() {
Properties props = new Properties();
// Set based on some application state that might be on a thread-local, http session info, etc.
String value = "value";
props.put("TRANSACTION_ISOLATION", value);
return props;
}
}
WebLogic Serverデータ・ソースは、ラベリング・コールバックを登録するためのregisterConnectionLabelingCallback(ConnectionLabelingCallback callback)メソッドを備えています。1つの接続プールに登録できるコールバックは1つのみです。
ラベリング・コールバックの登録については、registerConnectionLabelingCallback(ConnectionLabelingCallback callback)メソッドを参照してください。次のコード例では、MyConnectionLabelingCallbackクラスに実装されているラベリング・コールバックの登録を示します。
. . . import weblogic.jdbc.extensions.WLDataSource; . . . MyConnectionLabelingCallback callback = new MyConnectionLabelingCallback(); ((WLDataSource)ds).registerConnectionLabelingCallback( callback ); . . .
WebLogic Server管理コンソールを使用してコールバックを登録することもできます。Oracle WebLogic Server管理コンソール・オンライン・ヘルプの接続ラベリング・コールバック・クラスの構成を参照してください。
次のいずれかの方法を使用して、ラベリング・コールバックを削除できます。
プログラムでコールバックを設定した場合、次の例に示されているようにremoveConnectionLabelingCallback()メソッドを使用します。
. . . import weblogic.jdbc.extensions.WLDataSource; . . . ((WLDataSource)ds).removeConnectionLabelingCallback( callback ); . . .
管理者としてコールバックを設定した場合、データ・ソース構成からコールバックを削除します。Oracle WebLogic Server管理コンソール・オンライン・ヘルプの接続ラベリング・コールバック・クラスの構成を参照してください。
ノート:
アプリケーションでは、コールバックを登録するメソッドとコールバックを削除するメソッドのうちの一方(両方ではない)を使用する必要があります。たとえば、registerConnectionLabelingCallback(callback)を使用して接続にコールバックを登録する場合、removeConnectionLabelingCallback()を使用してそれを削除する必要があります。
ラベルは、LabelableConnectionインタフェースのapplyConnectionLabelメソッドを使用して、予約された接続に適用されます。任意の数の接続ラベルを予約された接続に累積的に適用できます。ラベルが接続に適用されるたびに、指定されたキー/値のペアが、ラベルの既存コレクションに追加されます。最後に適用された値のみがどのキーに対しても保持されます。
ノート:
予約された接続にラベルを適用するには、ラベリング・コールバックを接続プールに登録する必要があります。登録しないと、ラベリングは無視されます。「ラベリング・コールバックの作成」を参照してください
次の例では、トランザクション分離レベルで接続を初期化した後、ラベルを接続に適用しています。
. . . String pname = "property1"; String pvalue = "value"; Connection conn = ds.getConnection(); // initialize the connection as required. conn.setTransactionIsolation(Connection.TRANSACTION_SERIALIZABLE); ((LabelableConnection) conn).applyConnectionLabel(pname, pvalue); . . .
WebLogic JDBCデータ・ソースには、プールからラベリングされた接続を予約するために使用される2つのgetConnectionメソッドが用意されています。
public Connection getConnection(java.util.Properties labels)
public Connection getConnection(String user, String password, java.util.Properties labels)
これらのメソッドには、getConnectionメソッドにPropertiesオブジェクトとして渡すラベルが必要です。次の例では、property1 valueというラベルが付いた接続の取得を示します。
. . . import weblogic.jdbc.extensions.WLDataSource; . . . String pname = "property1"; String pvalue = "value"; Properties label = new Properties(); label.setProperty(pname, pvalue); . . . Connection conn = ((WLDataSource)ds).getConnection(label); . . .
標準のjava.sql.Datasource getConnection()メソッドを使用することもできます。この場合、getConnection()コールでラベル情報は指定しません。oracle.ucp.jdbc.ConnectionLabelingCallbackインタフェースを使用します。
java.util.Properties getRequestedLabels();
リクエストしたラベルが提供されておらず、登録されているインスタンスがある場合、getConnection()時にgetRequestedLabelsが呼び出されます。
接続には、指定された基準に基づいて接続を一意に識別する複数のラベルがあります。getUnmatchedConnectionLabelsメソッドを使用して、リクエストされたラベルと一致しない接続を検証します。
このメソッドは、複数のラベルを持つ接続が接続プールから予約された後に使用され、通常、ラベリング・コールバックで使用されます。getUnmatchedConnectionLabelsメソッドを参照してください。
次のコード例では、不一致ラベルのチェックを示します。
. . . String pname = "property1"; String pvalue = "value"; Properties label = new Properties(); label.setProperty(pname, pvalue); . . . Connecion conn = ((WLDataSource)ds).getConnection(label); Properties unmatched = ((LabelableConnection)connection).getUnmatchedConnectionLabels (label); . . .
接続ラベルを削除するには、removeConnectionLabelメソッドを使用します。
このメソッドは、ラベル付けされた接続が接続プールから予約された後に使用されます。removeConnectionLabelメソッドを参照してください。
次のコード例では、接続ラベルの削除を示します。
. . . String pname = "property1"; String pvalue = "value"; Properties label = new Properties(); label.setProperty(pname, pvalue); Connection conn = ((WLDataSource)ds).getConnection(label); . . . ((LabelableConnection) conn).removeConnectionLabel(pname); . . .
WebLogic Serverでは、高コストの接続を識別するために、次の接続プロパティを用意しています。
ConnectionLabelingHighCost—0よりも大きい値の場合、コスト値がこのプロパティ値以上である接続は高コストの接続と見なされます。デフォルト値はInteger.MAX_VALUEです。
たとえば、プロパティの値を5に設定した場合、ラベリング・コールバックから計算されたコスト値が5以上の接続はすべて高コストの接続と見なされます。
HighCostConnectionReuseThreshold—0より大きい値の場合、プール内の接続数合計のしきい値を指定し、この値より大きい場合、接続ラべリングはリクエストを処理するためにプール内で高コストの接続を再利用できます。このしきい値を下回れば、接続ラべリングは使用可能な低コストの接続を使用するか、まったく新しい物理接続を作成してリクエストを処理します。デフォルト値は0です。
たとえば、20に設定した場合、使用可能な低コストの接続が存在せず、接続の合計数が20に到達すると、接続ラべリングは高コストの接続を再利用します。
汎用データ・ソースの詳細は、「汎用の接続プール機能の構成」を参照してください。
AGLデータ・ソースの詳細は、「AGL接続プール機能の構成」を参照してください。
この項では、接続コストに基づいて接続を選択する場合の追加の考慮事項について説明します。
有効なコールバック登録によって接続ラべリングがアクティブ化されます。登録後、接続プールは定期的に新しいしきい値をチェックして、次のことを判断します。
ConnectionLabelingHighCost以上のコストが接続に発生しているかどうか。
接続数の合計が、MinCapacityおよびMaxCapacityの制限を含む、アクティブな接続作成リクエストの数を表しているかどうか。
新しいしきい値に達しても、コスト値がInteger.MAX_VALUEのラベル付けされた接続は再利用されません。
ラベル付けされた接続リクエストを処理するために、プール内のラベル付されていない(ステートレスな)接続を再利用してはならないという要件はありません。HighCostConnectionReuseThresholdに達して、接続ラべリングがアクティブ化されると、新しい物理接続を作成するより、プールでは引き続きラベル付されていない(ステートレスな)接続が優先されます。
WebLogic Serverでは、EARまたはWARファイル内の接続ラべリングや接続初期化などのコールバックをパッケージ・アプリケーションで使用できます。
データ・ソース構成でアプリケーションでパッケージ化されたコールバック・クラスを定義するには:
アプリケーションの一部としてデータ・ソースを定義します。
たとえば、コールバックの実装クラスがWARにパッケージ化されているか、アプリケーションから参照される共有ライブラリの一部として定義されている場合、EARファイルには、モジュール・ディスクリプタ内でコールバック・クラス名を参照する、アプリケーションでパッケージ化されたデータ・ソース構成が含まれます。
weblogic-application.xmlファイルのアプリケーション・クラス・ローダー階層の一部として、(コールバックの実装を含む)アプリケーションWARファイルを指定します。
たとえば:
. . . <classloader-structure> <module-ref> <module-uri>appcallbacks.war</module-uri> </module-ref> </classloader-structure>
WebLogic Serverでは、コールバック・クラスをアプリケーションにパッケージ化するときに、グローバル・スコープのデータ・ソース・システム・リソースに対して、モジュール・ディスクリプタ内に接続ラべリング・コールバックまたは接続初期化コールバックを指定することはできません。グローバル・データ・ソースでは、コールバックの実装クラスがWebLogicクラスパス上に存在する必要があります。ただし、WARまたはEARにパッケージ化されるアプリケーション・コールバックに対するこの制限は、Oracle WebLogic Server Java APIリファレンスのWLDataSourceインタフェースに従って、アプリケーションが実行時にコールバックを登録するようにすることで回避できます。
