| Oracle® Database SQLJ開発者ガイド 11g リリース2 (11.2) B56282-02 |
|
 前 |
 次 |
プロファイルとプロファイルのカスタマイズについては、「SQLJプロファイル」を参照してください。この付録では、技術的な詳細を示し、カスタマイザ・オプション、デフォルトのOracleカスタマイザ以外のカスタマイザの使用方法についても説明します。
また、Oracleの専用カスタマイザについても、特にプロファイルのセマンティクス・チェック用のSQLCheckerCustomizer、およびデバッグに使用するオーディタのインストール用のAuditorInstallerを中心に説明します。
内容は次のとおりです。
|
注意: この付録の説明は、デフォルトのOracle固有のコード生成(-codegen=oracle)を使用する場合は適用されません。 |
SQLJプロファイルには、埋込みSQL操作に関する情報が含まれています。プロファイルは、アプリケーションで使用される接続コンテキスト・クラスごとに、個別に作成されます。プロファイルは、SQLJトランスレータのコード生成フェーズで作成され、カスタマイズ・フェーズでカスタマイズされます。カスタマイズすると、アプリケーションでベンダー固有のデータベース機能を使用できるようになります。このようなベンダー固有の操作を別々のプロファイルにまとめると、それ以外の生成コードを汎用として使用できます。
各プロファイルには、関連する接続コンテキスト・クラスを使用するSQLJ文に対する一連のエントリが含まれています。各エントリは、アプリケーション内の1つのSQL操作に対応しています。
プロファイルは、アプリケーションとパッケージ化されるリソース・ファイルに、シリアライズされたオブジェクトとして保存されます。このため、プロファイルをいつでもロード、読取りおよび変更(追加または再カスタマイズ)できます。プロファイルのカスタマイズ時に、情報は追加されますが、削除されることはありません。プロファイルを複数回カスタマイズしても、以前のカスタマイズ内容が失われることはなく、アプリケーションは複数の環境で実行可能なままです。これをバイナリ移植性と呼びます。
プロファイルにバイナリ移植性を持たせるために、Oracle SQLJはSQLJの業界標準に従って実装されています。
トランスレータは、コード生成時に次のようにプロファイルを生成します。
sqlj.runtime.profile.Profileクラスのインスタンスとして、プロファイル・オブジェクトを生成します。
生成されたプロファイル・オブジェクトに、埋込みSQL操作(関連する接続コンテキスト・クラスを使用するSQLJ文)に関する情報を挿入します。
プロファイル・オブジェクトをシリアライズして、Javaリソース・ファイルに保存します。このファイルはプロファイル・ファイルと呼ばれ、ファイル名拡張子として.serが付加されます。
|
注意: Oracle SQLJ実装には、トランスレータに自動的にこれらの.serファイルを.classファイルに変換させるオプションがあります。.serファイルをサポートしていないブラウザがあるため、変換されたアプリケーションをサーバーにロードするときに、_serファイルのロードに手間が必要なためです。ただし、いったん自動変換したプロファイルは、カスタマイズの対象にならなくなります。詳細は、「.serファイルから.classファイルへの変換(-ser2class)」を参照してください。 |
「コードの生成」で説明したように、アプリケーションFooのプロファイル・ファイル名は、次のようになります。
Foo_SJProfilen.ser
SQLJでは、Foo_SJProfile0.ser、Foo_SJProfile1.serなどのファイルが、コード中に使用した接続コンテキスト・クラスの数に応じて生成されます。-ser2classオプションが設定されている場合は、Foo_SJProfile0.class、Foo_SJProfile1.classなどのファイルが生成されます。
各プロファイルには、SQLJの実行時にコールされるgetConnectedProfile()メソッドが含まれています。このメソッドは、JDBCのConnectionオブジェクトと同等のものを戻しますが、これには追加の機能が付いています。詳細は、「カスタマイズされたプロファイルの実行時の機能」を参照してください。
|
注意: プロファイル・オブジェクトとは、シリアライズされる前の元の状態のプロファイルを示します。プロファイル・ファイルとは、シリアライズされた状態(.serファイル)を示します。 |
ここでは、SQLJ実行文と、生成されるプロファイル・エントリの例を示します。ここに示すプロファイル・エントリは、わかりやすいように関係のない部分は省略して、テキストで表記してあります。
プロファイル・エントリでは、ホスト変数がJDBC構文(疑問符)に置き換えられることに注意してください。
次のような宣言があるとします。
#sql iterator Iter (double sal, String ename);
また、次のような実行文があるとします。
String empname = 'Smith';
Iter it;
...
#sql it = { SELECT ename, sal FROM emp WHERE ename = :empname };
=================================================================
...
#sql { SELECT ename, sal FROM emp WHERE ename = ? };
...
PREPARED_STATEMENT executed through EXECUTE_QUERY
role is QUERY
descriptor is null
contains one parameter
1. mode: IN, java type: java.lang.String (java.lang.String),
sql type: VARCHAR, name: ename, ...
result set type is NAMED_RESULT
result set name is Iter
contains 2 result columns
1. mode: OUT, java type: double (double),
sql type: DOUBLE, name: sal, ...
2. mode: OUT, java type: java.lang.String (java.lang.String),
sql type: VARCHAR, name: ename, ...
=================================================================
|
注意: ここに示すプロファイル・エントリは、便宜上テキストで表記してありますが、実際のプロファイルはテキスト形式ではありません。ただし、SQLJ-P-printオプションを使用するとテキストとして出力することができます(「カスタマイザ・ハーネスのオプションの概要」を参照)。 |
ISO SQLJコードを使用している場合、SQLJソース・ファイルに対してsqljスクリプトを実行すると、自動的にカスタマイズが行われます。その際、コード生成段階に作成された各プロファイルが、使用する特定のデータベース用にカスタマイズされます。デフォルトのoracle.sqlj.runtime.OraCustomizerというOracleカスタマイザを使用すると、Oracle11g固有の型拡張およびパフォーマンス強化機能を使用するように、プロファイルが最適化されます。
sqljスクリプトを実行して、既存のプロファイルをカスタマイズすることも可能です。SQLJコマンドラインで、個々の.serファイル、.serファイルを含むJARファイル、またはその両方を指定できます。
|
注意:
|
Oracleカスタマイザを使用する場合も、その他のカスタマイザを使用する場合も、SQLJでのカスタマイズには、カスタマイザ・ハーネスと呼ばれるフロントエンドのカスタマイズ・ユーティリティが使用されます。
SQLJの実行時に指定できるカスタマイズ・オプションとしては、カスタマイザ・ハーネス用(あらゆるカスタマイザに適用できる一般的なカスタマイザ設定)およびカスタマイザ用(カスタマイザ固有の設定)があります。これらのオプションは、コマンドラインまたはプロパティ・ファイルで指定します。詳細は、「カスタマイズ・オプションとカスタマイザの選択」を参照してください。
カスタマイザは、プロパティを公開するために、標準のJavaBeans APIに適合するJavaBeansコンポーネントであることが必要です。また、customize()メソッドを指定しているsqlj.runtime.profile.util.ProfileCustomizerインタフェースを実装する必要があります。カスタマイザ・ハーネスは、カスタマイズするプロファイルごとに、カスタマイザ・オブジェクトのcustomize()メソッドをコールします。
Oracleカスタマイザは前述の要件を満たしています。このカスタマイザはoracle.sqlj.runtime.OraCustomizerクラスに定義されています。
変換時のカスタマイズ処理は、次のように行われます。これは、SQLJの全体的な実行におけるカスタマイズ・フェーズの場合も、既存のプロファイルのみをカスタマイズする場合も同じです。
SQLJは、カスタマイザ・ハーネスを起動して、指定されているカスタマイズの一般オプションをそのカスタマイザ・ハーネスに渡します。
カスタマイザ・ハーネスは、使用するカスタマイザを起動して、指定されているカスタマイザ固有のオプションをそのカスタマイザに渡します。
カスタマイズのみを行うために、コマンドラインでJARファイルを指定してSQLJを実行した場合、カスタマイザ・ハーネスは、これらのJARファイル内のプロファイル・ファイルを検出して抽出します。
カスタマイザ・ハーネスは、各プロファイル・ファイルをプロファイル・オブジェクトにシリアライズ解除します(対象は、SQLJの全体的な実行で自動的に生成される.serファイル、カスタマイズのみを行うためにコマンドラインで指定した.serファイル、またはカスタマイズのみを行うために、コマンドラインで指定したJARから抽出された.serファイルです)。
データベース接続が必要なカスタマイザを使用している場合、カスタマイザ・ハーネスが接続を確立します。
カスタマイザ・ハーネスは、プロファイルごとに手順2でインスタンス化されたカスタマイザ・オブジェクトのcustomize()メソッドをコールします(カスタマイザをSQLJで使用するには、customize()メソッドが必要です)。
通常、customize()メソッドは、各プロファイルの内容をカスタマイズして、そのカスタマイズ内容を同じプロファイルに登録します。ただし、これはカスタマイザで処理する内容に依存します。カスタマイザによっては、特別な処理を行うために、このようなカスタマイズと登録を必要としない場合があります。
カスタマイザ・ハーネスは、各プロファイルを再度シリアライズして.serファイルを生成します。
カスタマイズのみを行うために、コマンドラインでJARファイルを指定してSQLJを実行した場合、カスタマイザ・ハーネスは、カスタマイズされた各.serファイルで、カスタマイズ前の元の.serファイルを上書きし、JARの内容を再度生成します。
|
注意:
|
カスタマイザ・ハーネスは、customize()メソッドをコールして、プロファイルをカスタマイズします。その場合、このメソッドにプロファイル・オブジェクト、SQLJ接続コンテキスト・オブジェクト(接続が必要なカスタマイザを使用している場合)およびエラー・ログ・オブジェクト(カスタマイズ時に出力されたエラー・メッセージのログに使用)を渡します。
1回のSQLJの実行では、すべてのカスタマイズに同じエラー・ログ・オブジェクトが透過的に使用されます。カスタマイザ・ハーネスは、エラー・ログ・オブジェクトに書き込まれたメッセージを読み込み、標準出力(通常はディスプレイ)にリアルタイムで出力します。
各プロファイルには複数のエントリが含まれており、それぞれSQL操作に対応しています。(これらはアプリケーション内のSQL操作であり、そのプロファイルに対応付けられている接続コンテキスト・クラスのインスタンスが使用されます。)
customize()は、これらのエントリに対して特別な処理を行います。各エントリの構文の妥当性チェックのような簡単な処理の場合もあれば、元のエントリに特定のデータベースの機能を使用するための変更を加えて、新しいエントリを生成するような複雑な処理の場合もあります。
|
注意:
|
カスタマイザ・ハーネスでのエラー・メッセージとステータス・メッセージは、SQLJトランスレータと同じ出力デバイスに出力されます。ただし、カスタマイズに関する警告メッセージは、非表示にはできません。
カスタマイザ・ハーネスによって生成されるエラー・メッセージは、次の4つのカテゴリに分類できます。
認識できないオプションまたは不正なオプション
接続のインスタンス化エラー
プロファイルのインスタンス化エラー
カスタマイザのインスタンス化エラー
カスタマイズ時に、カスタマイザ・ハーネスからステータス・メッセージが報告されます。これらのメッセージを参照して、プロファイルが正しくカスタマイズされたかどうかを確認できます。次の3つのカテゴリに分類できます。
プロファイルの変更状態
JARファイルの変更状態
作成されたバックアップ・ファイル名(カスタマイザ・ハーネスのbackupオプションが設定されている場合)
この他にも、特定のカスタマイザのcustomize()のメソッドによって、カスタマイザ固有のエラーや警告が出力される場合があります。
カスタマイズ時には、プロファイル・カスタマイザがメッセージがエラー・ログに書き込み、カスタマイザ・ハーネスがログの内容をリアルタイムに読み取って、これらのメッセージと、ハーネスからの他の出力とあわせてSQLJの出力デバイスに出力します。ユーザーがエラー・ログの内容に直接アクセスする必要はありません。
ここでは、プロファイルのカスタマイズ時のオプションについて説明します。これらのオプションは、次の3つのカテゴリに分類できます。
カスタマイザ・ハーネスに対して指定するオプション。使用するカスタマイザに関係なく適用されます。
このオプションの例としては、一般オプション、接続オプション、専用カスタマイザを起動するオプションなどがあります。
カスタマイザ固有のオプション。これらのオプションはカスタマイザ・ハーネスを介して、使用するカスタマイザに対して指定します。
SQLJオプション。これらのオプションは、カスタマイズを行うかどうか、どのカスタマイザを使用するかなど、カスタマイズの基本事項を指定します。
どのカテゴリのオプションも、すべてSQLJコマンドラインまたはプロパティ・ファイルを使用して指定します。
ここでは、次の内容を取り上げます。
デフォルトのOracleカスタマイザ以外のカスタマイザを選択するには、カスタマイザ・ハーネスのcustomizerオプション(「カスタマイザ・ハーネスのオプションの概要」を参照)またはSQLJの-default-customizerオプション(「プロファイルのカスタマイズ用のSQLJトランスレータのオプション」を参照)を使用します。
Oracle SQLJ実装のカスタマイザ・ハーネスには、特定のカスタマイザ以外にも使用できるオプションがいくつか用意されています。このハーネスの各オプションは、カスタマイズ処理をフロントエンドで調整する際に使用されます。
SQLJコマンドラインでカスタマイザ・ハーネス・オプションを設定する場合は、次の構文を使用します。
-P-option=value
または、SQLJプロパティ・ファイルで、次の構文を使用します。
profile.option=value
ブール値のオプション(フラグ)を有効にするには、次のように指定します。
-P-option
または
-P-option=true
ブール値のオプションは、デフォルトでは無効になっています。明示的に無効にするには、次のように指定します。
-P-option=false
このオプションの構文の詳細は、「プロファイル・カスタマイザに渡すオプション(-P)」および「プロパティ・ファイルの構文」を参照してください。
カスタマイザ・ハーネスには、次の一般オプションを使用できます。
backup: カスタマイズ前にプロファイルのバックアップ・コピーを作成するためのオプション
context: リストされた接続コンテキスト・クラスに対応付けられているプロファイルのみをカスタマイズするためのオプション
customizer: 使用するカスタマイザを指定するためのオプション
digests: JARマニフェスト・ファイルのダイジェスト値を指定するためのオプション(JARファイルのカスタマイズを指定した場合のみ)
help: カスタマイザ・オプションを表示するためのオプション(SQLJコマンドラインを使用した場合のみ)
verbose: カスタマイズ時にステータス・メッセージを表示するためのオプション
カスタマイザ・ハーネスでは、次のカスタマイザ・データベース接続用オプションを使用できます。現在、Oracleカスタマイザでは、列定義(パフォーマンスの最適化)用のoptcolsオプションを有効化した場合にこれらのオプションが使用されます。また、SQLCheckerCustomizerと呼ばれる、プロファイルに対してセマンティクス・チェックを実行する特別なカスタマイザを使用した場合にも、これらのオプションが使用されます。
user: このカスタマイズで使用する接続用ユーザー名を指定するためのオプション
password: このカスタマイズで使用する接続用パスワードを指定するためのオプション
url: このカスタマイズで使用する接続用URLを指定するためのオプション
driver: このカスタマイズで使用する接続用JDBCドライバを指定するためのオプション
Oracleカスタマイザoptcolsフラグの詳細は、「Oracleカスタマイザの列定義オプション(optcols)」を参照してください。SQLCheckerCustomizerの詳細は、「プロファイルのセマンティクス・チェック用のSQLCheckerCustomizer」を参照してください。
次のコマンドは、カスタマイザ・ハーネス・オプションとして機能しますが、Oracle SQLJ実装で提供される特別なカスタマイザを介して実装されます。
debug: デバッグ情報を指定したプロファイルに挿入し、実行時に出力するためのオプション。これはOracle SQLJのAuditorInstallerを起動する簡単な方法です。「デバッグ用のAuditorInstallerカスタマイザ」を参照してください。
print: プロファイルの内容をテキスト・フォーマットで出力するためのオプション
verify: 前のSQLJトランスレータ実行時に生成されているプロファイルに対してセマンティクス・チェック(変換時にソース・コードに行われるセマンティクス・チェックに相当)を行うためのオプション。これはOracle SQLJのSQLCheckerCustomizerを起動する簡単な方法です。「プロファイルのセマンティクス・チェック用のSQLCheckerCustomizer」を参照してください。
この項では、カスタマイザ・ハーネスでサポートされている一般オプションについて説明します。
backupフラグを使用すると、元のファイルに上書きする前に、各.jarファイルとスタンドアロンの.serファイルのバックアップ・コピーをハーネスで保存できます。(.jar内の.serファイル用のバックアップを別に作成する必要はありません。)
バックアップ・ファイル名には、拡張子として.baknが付加されます。nは、似た名前のファイルが存在する場合に、必要に応じて使用される数字です。バックアップ・ファイルが作成されるたびに、情報メッセージが出力されます。
スタンドアロンの.serファイルのカスタマイズ時にエラーが発生した場合は、元の.serファイルは上書きされず、バックアップも作成されません。同様に、JARファイル内の.serファイルのカスタマイズ時にエラーが発生した場合も、元のJARファイルは上書きされず、バックアップも作成されません。
このオプションのコマンドライン構文は、次のとおりです。
-P-backup<=true|false>
次にコマンドラインの例を示します。
-P-backup
プロパティ・ファイルの構文は、次のとおりです。
profile.backup<=true|false>
デフォルト値は、次のとおりです。
false
contextオプションを使用すると、指定された接続コンテキスト・クラスに対応するプロファイルのみに、カスタマイズの対象を限定できます。クラスの完全修飾名を指定し、複数のクラスを指定する場合は各クラスをカンマで区切ります。次に例を示します。
-P-context=sqlj.runtime.ref.DefaultContext,foo.bar.MyCtxtClass
カンマの前後には、スペースは不要です。
このオプションが指定されていない場合は、対応付けられている接続コンテキスト・クラスに関係なく、すべてのプロファイルがカスタマイズされます。
コマンドライン構文は、次のとおりです。
-P-context=ctx_class1<,ctx_class2,...>
次にコマンドラインの例を示します。
-P-context=foo.bar.MyCtxtClass
プロパティ・ファイルの構文は、次のとおりです。
profile.context=ctx_class1<,ctx_class2,...>
次にプロパティ・ファイルの例を示します。
profile.context=foo.bar.MyCtxtClass
customizerオプションを使用すると、使用するカスタマイザを指定できます。次に示すように、クラスの完全修飾名を指定します。
-P-customizer=oracle.sqlj.runtime.util.OraCustomizer
このオプションが設定されていない場合は、SQLJの-default-customizerオプションで指定されているカスタマイザが使用されます。このオプションでの設定を行わない場合、デフォルトの設定は次のようになります。
oracle.sqlj.runtime.util.OraCustomizer
コマンドライン構文は、次のとおりです。
-P-customizer=customizer_class
次にコマンドラインの例を示します。
-P-customizer=a.b.c.MyCustomizer
プロパティ・ファイルの構文は、次のとおりです。
profile.customizer=customizer_class
次にプロパティ・ファイルの例を示します。
profile.customizer=a.b.c.MyCustomizer
デフォルト値は、次のとおりです。
None
JARファイルの生成時に、JARユーティリティでは、指定した1つ以上のアルゴリズムに基づいて、エントリごとに1つ以上のダイジェストを含めることが可能であり、後でJARファイル・エントリの整合性を検証することができます。ダイジェストは、概念的にはチェックサムと似ています。
JARファイルの更新時に、JARファイルに含まれているプロファイルをカスタマイズし、JARユーティリティを使用して新しいダイジェストを追加(または、既存のダイジェストを更新)する場合は、digestsオプションを使用して、1つ以上のアルゴリズムをカンマで区切って指定します。JARユーティリティは、これらのアルゴリズムを使用して、各エントリのダイジェストを生成します。JARユーティリティは、JARマニフェスト・ファイル内の各JARファイル・エントリに対して、アルゴリズムごとに1つのダイジェストを生成します。次のように、アルゴリズムを指定します。
-P-digests=SHA,MD5
カンマの前後には、スペースは不要です。
この例では、JARマニフェスト・ファイル内の各エントリについて、SHAおよびMD5の2つのダイジェストが生成されます。
|
注意: JARマニフェスト・ファイルの詳細は、Sun社のサイトを参照してください。 |
コマンドライン構文は、次のとおりです。
-P-digests=algo1<,algo2,...>
次にコマンドラインの例を示します。
-P-digests=SHA,MD5
プロパティ・ファイルの構文は、次のとおりです。
profile.digests=algo1<,algo2,...>
次にプロパティ・ファイルの例を示します。
profile.digests=SHA,MD5
デフォルト値は、次のとおりです。
SHA,MD5
helpオプションを使用すると、カスタマイザ・ハーネスと、デフォルトのカスタマイザまたは指定されているカスタマイザのオプションを表示できます。ハーネスおよびOracleカスタマイザに関しては、各オプションの簡単な説明と現行の設定も表示されます。
ハーネスとデフォルトのカスタマイザ(Oracleカスタマイザ、またはSQLJの-default-customizerオプションで指定されているカスタマイザ)のオプションを表示するには、次のように指定します。
-P-help
次のように、helpオプションにcustomizerオプションを指定すると、特定のカスタマイザのオプションを表示できます。
-P-help -P-customizer=sqlj.runtime.profile.util.AuditorInstaller
|
注意:
|
コマンドライン構文は、次のとおりです。
-P-help <-P-customizer=customizer_class>
次にコマンドラインの例を示します。
-P-help
プロパティ・ファイルの構文は、次のとおりです。
NA
次にプロパティ・ファイルの例を示します。
NA
デフォルト値は、次のとおりです。
None
verboseフラグを使用すると、カスタマイズ時にハーネスからステータス・メッセージを表示できます。これらのメッセージは、SQLJの他のメッセージと同じように、標準出力に書き込まれます。
コマンドライン構文は、次のとおりです。
-P-verbose<=true|false>
次にコマンドラインの例を示します。
-P-verbose
プロパティ・ファイルの構文は、次のとおりです。
profile.verbose<=true|false>
次にプロパティ・ファイルの例を示します。
profile.verbose
デフォルト値は、次のとおりです。
false
ここでは、カスタマイザ・ハーネスでサポートされている接続オプションについて説明します。次のように使用されます。
Oracleカスタマイザでは、列定義にのみデータベース接続を使用します。Oracleカスタマイザのoptcolsオプションを有効にしない場合は、カスタマイザ・ハーネスのuser、password、urlおよびdriverオプションを設定する必要はありません。
SQLCheckerCustomizerと呼ばれる、プロファイルに対してセマンティクス・チェックを実行する特別なカスタマイザでは、オンライン・チェックの際にカスタマイザ・ハーネスのuser、password、urlおよびdriver設定が使用されます。
SQLJコマンドラインで-P-verifyを使用して、カスタマイザを起動します。
|
注意: カスタマイザ・ハーネスのuser、password、urlおよびdriverオプションと、トランスレータの同名のオプションを、混同しないようにしてください。トランスレータのオプションは、変換処理でのセマンティクス・チェックに使用されるオプションです。ただし、変換と同じ接続を使用するようにカスタマイズする場合は、便宜上トランスレータの設定がカスタマイザに渡されて、利用されます。必要に応じて、カスタマイザ・ハーネス・オプションを使用してこれらの初期設定をオーバーライドしてください。 |
userオプションを設定すると、カスタマイザでデータベース接続を使用する場合のデータベース・スキーマを指定できます。
userオプション設定には、ユーザー・スキーマの他にも、必要に応じてパスワードまたはURL、あるいはその両方を指定できます。次のように、パスワードの先頭にスラッシュ(/)を付け、URLの先頭にアットマーク(@)を付けます。
-P-user=scott/tiger -P-user=scott@jdbc:oracle:oci:@ -P-user=scott/tiger@jdbc:oracle:oci:@
|
注意: 列定義(optcolsオプション)を使用するときに、SQLJトランスレータのユーザー設定もプロファイル・カスタマイザに転送されます。カスタマイザのuserオプションを使用すると、トランスレータの設定を上書きできます。 |
コマンドライン構文は、次のとおりです。
-P-user=username</password><@url>
次にコマンドラインの例を示します。
-P-user=scott -P-user=scott/password -P-user=scott/password@jdbc:oracle:oci:@
プロパティ・ファイルの構文は、次のとおりです。
profile.user=username</password><@url>
次にプロパティ・ファイルの例を示します。
profile.user=scott profile.user=scott/tiger profile.user=scott/tiger@jdbc:oracle:oci:@
デフォルト値は、次のとおりです。
null
passwordオプションは、カスタマイザでデータベース接続を使用する場合に使用します。
パスワードは、userオプションでも設定できます。「カスタマイズ用ユーザー・オプション(user)」を参照してください。
|
注意: 列定義(optcolsオプション)を使用するときに、SQLJトランスレータのパスワード設定もプロファイル・カスタマイザに転送されます。カスタマイザのpasswordオプションを使用すると、トランスレータの設定を上書きできます。 |
コマンドライン構文は、次のとおりです。
-P-password=password
次にコマンドラインの例を示します。
-P-password=password
プロパティ・ファイルの構文は、次のとおりです。
profile.password=password
次にプロパティ・ファイルの例を示します。
profile.password=password
デフォルト値は、次のとおりです。
null
urlオプションは、カスタマイザでデータベース接続を使用する場合に使用します。
URLは、userオプションでも設定できます。「カスタマイズ用ユーザー・オプション(user)」を参照してください。
|
注意: 列定義(optcolsオプション)を使用するときに、SQLJトランスレータのURL設定もプロファイル・カスタマイザに転送されます。カスタマイザのurlオプションを使用すると、トランスレータの設定を上書きできます。 |
コマンドライン構文は、次のとおりです。
-P-url=url
次にコマンドラインの例を示します。
-P-url=jdbc:oracle:oci:@
プロパティ・ファイルの構文は、次のとおりです。
profile.url=url
次にプロパティ・ファイルの例を示します。
profile.url=jdbc:oracle:oci:@
デフォルト値は、次のとおりです。
jdbc:oracle:oci:@
カスタマイザでデータベース接続を使用する場合は、driverオプションを使用し、複数のJDBCドライバ・クラスをカンマで区切って登録します。次に例を示します。
-P-driver=sun.jdbc.odbc.JdbcOdbcDriver,oracle.jdbc.OracleDriver
カンマの前後には、スペースは不要です。
コマンドライン構文は、次のとおりです。
-P-driver=dvr_class1<,dvr_class2,...>
次にコマンドラインの例を示します。
-P-driver=sun.jdbc.odbc.JdbcOdbcDriver
プロパティ・ファイルの構文は、次のとおりです。
profile.driver=dvr_class1<,dvr_class2,...>
次にプロパティ・ファイルの例を示します。
profile.driver=sun.jdbc.odbc.JdbcOdbcDriver
デフォルト値は、次のとおりです。
oracle.jdbc.OracleDriver
特別なカスタマイザの起動には、次に示したカスタマイザ・ハーネスのオプションを使用できます。
debug: デバッグに使用するAuditorInstallerカスタマイザを起動するためのオプション
print: プロファイルをテキスト形式で出力するカスタマイザを起動するためのオプション
verify: プロファイルに対してセマンティクス・チェックを実行するSQLCheckerCustomizerカスタマイザを起動するためのオプション
|
重要: これらの各オプションを使用すると特定のカスタマイザを起動できますが、SQLJの1回の実行で実行できるカスタマイザは1つのみに限られています。そのため、このオプションを使用した場合は、他のカスタマイズを実行できなくなります。
|
debugオプションを使用すると、AuditorInstallerと呼ばれる、デバッグ文をプロファイルに挿入する専用のカスタマイザを起動できます。このオプションに、SQLJコマンドラインでファイルを指定すると、指定されたプロファイルにデバッグ文が出力されます。これらのプロファイルは、あらかじめSQLJを実行してカスタマイズしておく必要があります。
このカスタマイザでサポートされている他のオプションなどの詳細は、「デバッグ用のAuditorInstallerカスタマイザ」を参照してください。
アプリケーションを実行すると、SQLJランタイムでデバッグ文が実行され、メソッド・コールと戻り値のトレース情報が表示されます。
たとえば、次のようにdebugオプションを指定します。
% sqlj -P-debug Foo_SJProfile0.ser Bar_SJProfile0.ser % sqlj -P-debug *.ser
コマンドライン構文は、次のとおりです。
sqlj -P-debug profile_list
次にコマンドラインの例を示します。
sqlj -P-debug Foo_SJProfile*.ser
プロパティ・ファイルの構文は、次のとおりです。
profile.debug
(SQLJファイル・リストのプロファイルにも指定します。)
次にプロパティ・ファイルの例を示します。
profile.debug
デフォルト値は、次のとおりです。
NA
printオプションを使用すると、プロファイルをテキスト・フォーマットで表示するためのカスタマイザを実行できます。このオプションに、SQLJコマンドラインでファイルを指定すると、指定された1つ以上のプロファイルの内容が出力されます。これは、SQLJの標準出力(通常はディスプレイ)に出力されます。次に例を示します。
% sqlj -P-print Foo_SJProfile0.ser Bar_SJProfile0.ser
すべてのカスタマイザ・オプションを参照するには、次のコマンドを使用します。
% sqlj -P-print *.ser
前述のコマンドによる出力は、次のとおりです。
printing contents of profile Sample_SJProfile0
created 1154609279331 (8/3/06 5:47 AM)
associated context is Mycontext1
profile loader is sqlj.runtime.profile.DefaultLoader@12a3793
contains one customization
OracleCustomization Options :
Version is :2300
Cstmtcache :5
Ccompat :false
Cforce :false
Coptcols :false
Coptparams :false
Coptparamdefaults:null
CshowSQL :false
Csummary :false
CuserSQL :true
#sql { SELECT a FROM test WHERE name= ? }
setFixedchar is enabled
Ncharconv is disabled
#sql { commit }
setFixedchar is disabled
Ncharconv is disabled
………
コマンドライン構文は、次のとおりです。
sqlj -P-print profile_list
次にコマンドラインの例を示します。
sqlj -P-print Foo_SJProfile*.ser
プロパティ・ファイルの構文は、次のとおりです。
profile.print
(SQLJファイル・リストのプロファイルにも指定します。)
次にプロパティ・ファイルの例を示します。
profile.print
デフォルト値は、次のとおりです。
なし
verifyオプションを指定すると、プロファイルに対してセマンティクス・チェックを実行するSQLCheckerCustomizerという特殊なカスタマイザが起動されます。これは、変換時にソース・コードに対して実行されるセマンティクス・チェックに相当します。このプロファイルは、前のSQLJトランスレータ実行時にすでに作成されています。
このオプションは、デプロイメント後やソース・コードが使用されなくなった後の、ランタイム・データベースに対するセマンティクス・チェックに役立ちます。
このカスタマイザでサポートされている他のオプションなどの詳細は、「プロファイルのセマンティクス・チェック用のSQLCheckerCustomizer」を参照してください。
|
注意: プロファイルのオンライン・セマンティクス・チェックの際にも、カスタマイザ・ハーネスのuser、passwordおよびurlオプションを使用する必要があります。 |
たとえば、次のようにverifyオプションを指定します。次の2つの例では、どちらもSQLCheckerCustomizerのデフォルトのセマンティクス・チェッカを使用し、特定のデータベース接続によるオンライン・チェックを行います。(最初の例ではコマンドラインが折り返されて表示されていますが、全体が1行で入力されています。)
% sqlj -P-verify -P-user=scott -P-url=jdbc:oracle:oci:@ Foo_SJProfile0.ser Bar_SJProfile0.ser Password: password % sqlj -P-verify -P-user=scott -P-url=jdbc:oracle:oci:@ *.ser Password: password
コマンドライン構文は、次のとおりです。
sqlj -P-verify <conn params> profile_list
次にコマンドラインの例を示します。
sqlj -P-verify <conn params> Foo_SJProfile*.ser
プロパティ・ファイルの構文は、次のとおりです。
profile.verify
(SQLJコマンドラインにはプロファイルを必ず指定してください。通常はカスタマイザ・ハーネスの接続オプションを指定します。)
次にプロパティ・ファイルの例を示します。
profile.verify
デフォルト値は、次のとおりです。
NA
カスタマイザ固有のオプション(Oracleカスタマイザ用のオプションなど)は、SQLJコマンドラインまたはSQLJプロパティ・ファイルに設定できます。この構文は、カスタマイザ・ハーネスのオプション設定に使用する構文とほとんど同じです。
SQLJコマンドラインでカスタマイザ・オプションを設定する場合は、先頭に次の文字列を付けます。
-P-C
SQLJプロパティ・ファイルで設定するときは、先頭に次の文字列を付けます。
profile.C
このオプションの構文の詳細は、「プロファイル・カスタマイザに渡すオプション(-P)」および「プロパティ・ファイルの構文」を参照してください。
この項のこれ以降では、Oracleカスタマイザの機能について説明します。Oracleカスタマイザでは、いくつかのオプションがサポートされています。これらのオプションの大半はブール値であり、有効にするには次のようにします。
-P-Coption
または
-P-Coption=true
ブール値のオプションは、デフォルトでは無効になっています。明示的に無効にするには、次のように指定します。
-P-Coption=false
数値オプションや文字列オプションの設定は、ほとんど同じです。
-P-Coption=value
ここでは、Oracleカスタマイザ固有のオプションについて説明します。まず、サポートされているオプションの概要を示します。
Oracleカスタマイザでは、次のオプションを使用できます。
compat: バージョンの互換性に関する情報を表示するためのオプション
force: すでに有効なカスタマイズが行われている場合でも、カスタマイズを実行するためのオプション
optcols: パフォーマンスが最適化されるようにイテレータ列型およびサイズ定義を有効化するためのオプション。
optparams: パラメータ・サイズを、JDBCリソース割当て量が最適化されるように定義するためのオプション(optparamdefaultsと併用します)。
optparamdefaults: 特定のデータ型に対してパラメータ・サイズのデフォルトを設定するためのオプション(optparamsと併用します)。
fixedchar: WHERE句に関して、空白埋めを考慮したCHAR比較を有効にするためのオプション。
showSQL: SQL文の変換情報を表示するためのオプション。
stmtcache: 文のキャッシュ・サイズ(実行時に各接続でキャッシングできる文の数)を設定するためのオプション。パフォーマンスの最適化に必要なサイズを設定する場合と、文のキャッシングを無効化するために0(ゼロ)が設定される場合があります。
summary: アプリケーションで使用されているOracleの機能の概要を表示するためのオプション。
これらのオプションによって出力された内容は、SQLJの他のメッセージと同じように、標準出力に書き込まれます。
compatフラグを使用すると、アプリケーションと、Oracle DatabaseおよびOracle JDBCドライバの各バージョンとの互換性に関する情報が、Oracleカスタマイザによって表示されます。これは、SQLJ変換を全体的に実行した場合でも、以前に生成されたプロファイルに対して実行した場合でも、実行できます。
たとえば、次のように指定すると、MyAppというアプリケーションを変換してカスタマイズする際に、互換性の情報が出力されます。
% sqlj <...SQLJ options...> -P-Ccompat MyApp.sqlj
この例では、MyAppのプロファイルの生成、カスタマイズおよび互換性チェックが、SQLJの1回の実行で行われます。
次のように指定すると、以前に生成されたMyAppのプロファイルに関する互換性情報が出力されます。
% sqlj <...SQLJ options...> -P-Ccompat MyApp_SJProfile*.ser
この例のように指定してSQLJを実行すると、以前にSQLJを実行したときに生成された(場合によってはカスタマイズもされた)MyAppのプロファイルに対して、カスタマイズ(必要な場合)と互換性チェックが行われます。
次の2つの例は、デフォルトのOracleカスタマイザを使用している場合に、-P-Ccompatオプションを指定してSQLJを実行したときに出力される内容です。最初に、アプリケーションが、すべてのバージョンのOracle JDBCドライバで使用できる例を示します。
MyApp_SJProfile0.ser: Info: compatible with all Oracle JDBC drivers
2番目の例では、アプリケーションが、Oracle8i リリース8.1以上のJDBC実装でのみ使用できる場合を示します。
MyApp_SJProfile0.ser: Info: compatible with Oracle 8.1 or later JDBC driver
|
注意: 以前の有効なカスタマイズが検出されてカスタマイズが実行されなかった場合でも、compatオプションが指定されていると、互換性の情報が出力されます。 |
コマンドライン構文は、次のとおりです。
-P-Ccompat<=true|false>
次にコマンドラインの例を示します。
-P-Ccompat
プロパティ・ファイルの構文は、次のとおりです。
profile.Ccompat<=true|false>
次にプロパティ・ファイルの例を示します。
profile.Ccompat
デフォルト値は、次のとおりです。
false
forceフラグを有効にすると、Oracleカスタマイザによって特定の(コマンドラインで指定された)プロファイルのカスタマイズが強制的に実行されます。そのプロファイルに、すでに有効なカスタマイズが認識される場合でも、実行されます。次に例を示します。
% sqlj -P-Cforce MyApp_SJProfile*.ser
これを実行すると、カスタマイズ済かどうかにかかわらず、MyAppのプロファイルがすべてカスタマイズされます。デフォルトでは、Oracleカスタマイザは既存のカスタマイズを上書きして再インストールすることはありません(ただし、既存のカスタマイズが古いバージョンのカスタマイザでインストールされている場合を除きます)。
コマンドライン構文は、次のとおりです。
-P-Cforce<=true|false>
次にコマンドラインの例を示します。
-P-Cforce
プロパティ・ファイルの構文は、次のとおりです。
profile.Cforce<=true|false>
次にプロパティ・ファイルの例を示します。
profile.Cforce
デフォルト値は、次のとおりです。
false
optcolsフラグを使用すると、Oracleカスタマイザに、イテレータまたは結果セットの列型およびサイズを判断し、この情報をプロファイルに追加するように指示できます。このようにすると、SQLJランタイムは、アプリケーション実行時にこの列をOracle JDBCドライバに自動的に登録可能になり、特定のドライバの実装にもよりますが、Oracleへのラウンドトリップが減ります。この方法は、Thinドライバと位置イテレータには特に効果的です。
列定義の概要は、「列の定義」を参照してください。
データベース接続用のユーザー名、パスワードおよびURLを指定せずに、Oracleカスタマイザのoptcolsオプションを有効にすると、エラーが発生します。この指定を行うには、ISO標準のコード生成時にカスタマイザに転送される、トランスレータのオプション-user、-passwordおよび-urlを使用するか、またはカスタマイザのオプションuser、passwordおよびurlを直接使用します。
実行時にはデータベースの接続先と同じスキーマまたはデータベースに、カスタマイザから接続する必要はありません。ただし、実行時のエラーを回避するために、関連のある列と、型およびサイズが同じ列は同じ順序で並べる必要があります。
カスタマイザ・ハーネスの接続オプションについては、「カスタマイザ・ハーネスのオプションの概要」のuser、password、urlおよびdriverの項を参照してください。
|
注意: このオプションのかわりに、SQLJトランスレータの-optcolsオプションを使用できます。これは、カスタマイザのオプションを自動的に設定するオプションです。(また、プロファイルを使用しないOracle固有コード生成の場合は、トランスレータのオプションを使用する必要があります。)「列の定義(-optcols)」を参照してください。
参照先の項では、さらに概念についても説明されています。 |
カスタマイザのoptcolsフラグの有効化/無効化は、SQLJのコマンドラインまたはプロパティ・ファイルで設定します。
このフラグをコマンドラインで有効にするには、次のようにします。
-P-Coptcols
または
-P-Coptcols=true
このフラグは、デフォルトでは無効になっていますが、明示的に無効化することも可能です。このフラグをコマンドラインで無効化するには、次のようにします。
-P-Coptcols=false
列を定義するには、カスタマイザでデータベース接続を行って、問合せの対象とする表の列を調べる必要があります。そのために、カスタマイザ・ハーネスのuser、passwordおよびurlオプションを適切に設定する必要があります(デフォルトのOracleDriverクラスを使用しない場合は、カスタマイザ・ハーネスのdriverオプションも)。次に例を示します。
% sqlj <...SQLJ options...> -P-user=scott@jdbc:oracle:oci:@ -P-Coptcols MyApp.sqlj Password: password
SQLJトランスレータの場合と同様に、必要に応じて、パスワードとURLをpasswordオプションとurlオプションでそれぞれ設定するかわりに、userオプションで設定できます。
または、次のようにして、列定義を既存のプロファイルに挿入することも可能です。この場合は、Oracleカスタマイザのforceオプションを使用して、カスタマイズを再実行する必要があります。
% sqlj -P-user=scott@jdbc:oracle:oci:@ -P-Cforce -P-Coptcols MyApp_SJProfile*.ser
Password: password
また、次のようにして、列定義をJARファイル中の既存のプロファイルに挿入することも可能です。
% sqlj -P-user=scott@jdbc:oracle:oci:@ -P-Cforce -P-Coptcols MyAppProfiles.jar
Password: password
Oracleカスタマイザ実行時(新規のプロファイルの変換時や生成時、または既存プロファイルのカスタマイズ時)にoptcolsフラグを有効化すると、カスタマイザ・ハーネスのverboseフラグも有効化できます。このフラグを有効化すると、処理対象のイテレータおよび結果セット、列型およびサイズ定義の情報がOracleカスタマイザに表示されます。次に例を示します。
% sqlj -P-user=scott@jdbc:oracle:oci:@ -P-verbose -P-Cforce -P-Coptcols MyApp_SJProfile*.ser
Password: password
verboseのフラグの概要は、「カスタマイザ・ハーネスのオプションの概要」の該当する項を参照してください。
Oracleカスタマイザのsummaryフラグを有効にして、既存のプロファイルの処理を実行すると、列定義がそのプロファイルに追加されたかどうかを確認できます。次のようにします。
% sqlj -P-Csummary MyApp_SJProfile*.ser
summaryフラグの概要は、「カスタマイザ固有のオプションの概要」を参照してください。
コマンドライン構文は、次のとおりです。
-P-Coptcols<=true|false>
次にコマンドラインの例を示します。
-P-Coptcols
プロパティ・ファイルの構文は、次のとおりです。
profile.Coptcols<=true|false>
次にプロパティ・ファイルの例を示します。
profile.Coptcols
デフォルト値は、次のとおりです。
false
パラメータ・サイズの定義を有効化するには、optparamsフラグを使用します。SQLJではこのフラグを有効にすると、入出力パラメータ(ホスト変数)が登録され、JDBCリソース割当て量が指定したサイズに基づいて最適化されます。
パラメータ・サイズ定義の概要とソース・コード・ヒントの詳細は、「パラメータ・サイズの定義」を参照してください。
|
注意: このオプションのかわりに、SQLJトランスレータの-optparamsオプションを使用できます。これは、カスタマイザのオプションを自動的に設定するオプションです。(また、プロファイルを使用しないOracle固有コード生成の場合は、トランスレータのオプションを使用する必要があります。)「パラメータの定義(-optparams)」を参照してください。
参照先の項では、さらに概念についても説明されています。 |
optparamsフラグの有効化/無効化は、コマンドラインまたはSQLJプロパティ・ファイルで設定します。
このフラグをコマンドラインで有効にするには、次のようにします。
-P-Coptparams
または
-P-Coptparams=true
このフラグは、デフォルトでは無効になっていますが、明示的に無効化することも可能です。このフラグをコマンドラインで無効化するには、次のようにします。
-P-Coptparams=false
|
注意: optcolsオプションとは異なり、optparamsオプションではサイズを自分で指定できるので、カスタマイザでのデータベース接続は不要です。 |
コマンドライン(optparamdefaultsオプションの設定はここでは省略し、次の項で説明します)の例を次に示します。
% sqlj <...SQLJ options...> -P-Coptparams -P-Coptparamdefaults=defaults_string MyApp.sqlj
次の例のようにすると、既存プロファイルのパラメータ・サイズ定義が有効になります。
% sqlj -P-Coptparams -P-Coptparamdefaults=defaults_string MyApp_SJProfile*.ser
また、JARファイル中の既存のプロファイルも使用できます。
% sqlj -P-Coptparams -P-Coptparamdefaults=defaults_string MyAppProfiles.jar
コマンドライン構文は、次のとおりです。
-P-Coptparams<=true|false>
次にコマンドラインの例を示します。
-P-Coptparams
プロパティ・ファイルの構文は、次のとおりです。
profile.Coptparams<=true|false>
次にプロパティ・ファイルの例を示します。
profile.Coptparams
デフォルト値は、次のとおりです。
false
optparamsオプションを有効にしてパラメータ・サイズを設定した場合は、必要に応じてoptparamdefaultsオプションを使用してデータ型のデフォルト・サイズを設定します。optparamsを有効にしないと、optparamdefaultsが設定されていても無視されるので注意してください。
パラメータ・サイズ定義の概要とソース・コード・ヒントの詳細は、「パラメータ・サイズの定義」を参照してください。
|
注意: このオプションのかわりに、SQLJトランスレータの-optparamdefaultsオプションを使用できます。これは、カスタマイザのオプションを自動的に設定するオプションです。(また、プロファイルを使用しないOracle固有コード生成の場合は、トランスレータのオプションを使用する必要があります。)「パラメータのデフォルト・サイズ(-optparamdefaults)」を参照してください。
参照先の項では、さらに概念と構文についても説明されています。2つのオプションの機能は同じです。 |
optparamdefaultsフラグは、コマンドラインでもSQLJプロパティ・ファイルでも設定できます。
このフラグをコマンドラインで設定するには、次のようにします。
-P-Coptparamdefaults=datatype1(size1),datatype2(size2),...
次にコマンドラインの例を示します。この例では、optparamsも設定します。
% sqlj <..SQLJ options..> -P-Coptparams -P-Coptparamdefaults=CHAR_TYPE(50),RAW_TYPE(500),CHAR(10) MyApp.sqlj
構文は、「パラメータのデフォルト・サイズ(-optparamdefaults)」を参照してください。
既存のプロファイルに対してパラメータ・サイズのデフォルトを指定することも可能です。ただし、この場合はOracleカスタマイザのforceオプションを使用して、カスタマイズを再実行する必要があります。
% sqlj -P-Cforce -P-Coptparams -P-Coptparamdefaults=CHAR_TYPE(50),RAW_TYPE(500),CHAR(10) MyApp_SJProfile*.ser
また、次のようにして、JARファイル中の既存のプロファイルに対してパラメータ・サイズのデフォルトを指定することも可能です。
% sqlj -P-Cforce -P-Coptparams -P-Coptparamdefaults=CHAR_TYPE(50),RAW_TYPE(500),CHAR(10) MyAppProfiles.jar
|
注意: 実行時に、実際のサイズが登録されているパラメータのサイズを超えた場合は、ランタイム・エラーが発生します。 |
コマンドライン構文は、次のとおりです。
-P-Coptparamdefaults=defaults_string
次にコマンドラインの例を示します。
-P-Coptparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()
プロパティ・ファイルの構文は、次のとおりです。
profile.Coptparamdefaults=defaults_string
次にプロパティ・ファイルの例を示します。
profile.Coptparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()
デフォルト値は、次のとおりです。
null
WHERE句の比較で文字列をバインドするときにCHAR型のデータベース列の空白埋めを考慮するには、このフラグをtrueに設定します。この比較方法では、たとえば、"mystring"と"mystring "は同等であるとみなされます。
次に、Oracleカスタマイザのfixedcharの使用例を示します。
% sqlj -P-Cfixedchar MyProgram.sqlj AnotherProg.java ...
|
注意:
|
コマンドライン構文は、次のとおりです。
-P-Cfixedchar<=true|false>
次にコマンドラインの例を示します。
-P-Cfixedchar
プロパティ・ファイルの構文は、次のとおりです。
profile.Cfixedchar<=true|false>
次にプロパティ・ファイルの例を示します。
profile.Cfixedchar
デフォルト値は、次のとおりです。
false
showSQLフラグを有効にすると、OracleカスタマイザによってSQL文に実行されたすべての変換が表示されます。このような変換は、データベースが直接サポートしていない構文をSQLJがサポートしている場合に必要です。
次のように指定すると、MyAppというアプリケーションを変換してカスタマイズする際に、SQL変換情報が表示されます。
% sqlj <...SQLJ options...> -P-CshowSQL MyApp.sqlj
この例では、MyAppのプロファイルの生成、カスタマイズおよびSQL変換情報の表示が、SQLJの1回の実行で行われます。
次のように指定すると、以前に生成されたMyAppのプロファイルのカスタマイズ時に、SQL変換情報が表示されます。
% sqlj <...SQLJ options...> -P-CshowSQL MyApp_SJProfile*.ser
この例のように指定してSQLJを実行すると、以前にSQLJを実行したときに生成された(場合によってはカスタマイズもされた)MyAppのプロファイルに対して、カスタマイズ(必要な場合)が行われ、SQL変換情報が表示されます。
次の例は、showSQLによって出力される内容です。
MyApp.sqlj:14: Info: <<<NEW SQL>>> #sql {BEGIN ? := VALUES(tkjsSET_f1); END};
in file MyApp, line 14, we had:
#sql {set :v1= VALUES(tkjsSET_f1) };
SET文は、カスタマイズ時にOracleカスタマイザによって、それに相当するPL/SQLブロックに置き換えられます。
|
注意: 以前の有効なカスタマイズが検出されてカスタマイズが実行されなかった場合でも、showSQLオプションが指定されているとSQL変換情報が出力されます。 |
コマンドライン構文は、次のとおりです。
-P-CshowSQL<=true|false>
次にコマンドラインの例を示します。
-P-CshowSQL
プロパティ・ファイルの構文は、次のとおりです。
profile.CshowSQL<=true|false>
次にプロパティ・ファイルの例を示します。
profile.CshowSQL
デフォルト値は、次のとおりです。
false
Oracleカスタマイザのstmtcacheオプションを使用すると、文のキャッシュ・サイズ(アプリケーション実行時にデータベース接続ごとにキャッシングできる文の数)を設定したり、文のキャッシングを無効化することが可能です。
文のキャッシュ・サイズのデフォルトは5です。文のキャッシングの概要は、「文のキャッシング」を参照してください。
|
重要: デフォルトのOracle固有のコード生成(-codegen=oracle)を使用する場合、SQLJではプロファイルが生成されず、カスタマイズが実行されません。この場合、接続コンテキスト・メソッドを使用してSQLJ文キャッシングを制御します。「文キャッシングのための接続コンテキスト・メソッド(Oracle固有コードの場合)」を参照してください。 |
文のキャッシュ・サイズは、コマンドラインでもプロパティ・ファイルでも設定できます。
コマンドラインを使用して、アプリケーションMyAppでの文のキャッシュ・サイズを15に設定するには、次のようにします。
% sqlj <...SQLJ options...> -P-Cstmtcache=15 MyApp.sqlj
文のキャッシングを無効化するには、キャッシュ・サイズを0(ゼロ)に設定します。
% sqlj <...SQLJ options...> -P-Cstmtcache=0 MyApp.sqlj
アプリケーションを再変換せずに、既存プロファイル中の文のキャッシュ・サイズを変更することも可能です。ただし、この場合は、Oracleカスタマイザのforceオプションを使用して、カスタマイズを再実行する必要があります。
% sqlj -P-Cforce -P-Cstmtcache=15 MyApp_SJProfile0.ser
プロファイルが複数ある場合、各プロファイルに対して文のキャッシュ・サイズを個別に設定できます。この個別設定を行うには、アプリケーションの変換が完了した後で、各プロファイルに対してSQLJを個別に実行します。
% sqlj -P-Cforce -P-Cstmtcache=10 MyApp_SJProfile0.ser % sqlj -P-Cforce -P-Cstmtcache=15 MyApp_SJProfile1.ser % sqlj -P-Cforce -P-Cstmtcache=0 MyApp_SJProfile2.ser
各接続コンテキスト・クラスに対応するプロファイルを決定決することも必要です。次のように決定します。プロファイル0(ゼロ)は、アプリケーションにおける最初の実行文で使用する接続コンテキスト・クラスに対応し、プロファイル1は、最初の実行文(ただし、最初の接続コンテキスト・クラスを使用しない)で使用する接続コンテキスト・クラスに対応し、プロファイル2以降についても同様の対応になります。相関関係を検証するには、各プロファイルを調べるカスタマイザ・ハーネスのprintオプションを使用します。
コマンドライン構文は、次のとおりです。
-P-Cstmtcache=value
次にコマンドラインの例を示します。
-P-Cstmtcache=10
プロパティ・ファイルの構文は、次のとおりです。
profile.Cstmtcache=value
次にプロパティ・ファイルの例を示します。
profile.Cstmtcache=10
デフォルト値は、次のとおりです。
5
summaryフラグを使用すると、変換するアプリケーション、または指定されたプロファイル・ファイルで使用されているOracleの機能のサマリーを表示するように、Oracleカスタマイザに指示できます。これは、別のプラットフォームへの移植を妨げる機能を特定する場合に便利で、SQLJ変換を全体的に実行する場合でも、以前に生成されたプロファイルに対して実行する場合でも実施できます。
次のように指定すると、MyAppというアプリケーションを変換してカスタマイズする際に、サマリーが表示されます。
% sqlj <...SQLJ options...> -P-Csummary MyApp.sqlj
この例では、MyAppのプロファイルの生成、カスタマイズおよびサマリーの表示が、SQLJの1回の実行で行われます。
次のように指定すると、以前に生成されたMyAppのプロファイルに関するサマリーが表示されます。
% sqlj <...SQLJ options...> -P-Csummary MyApp_SJProfile*.ser
この例のように指定してSQLJを実行すると、以前にSQLJを実行したときに生成された(場合によってはカスタマイズもされた)MyAppのプロファイルに対して、カスタマイズ(必要な場合)が行われ、サマリーが表示されます。
次の2つの例は、デフォルトのOracleカスタマイザを使用している場合に、-P-Csummaryオプションを指定してSQLJを実行したときに出力される内容です。最初に、Oracleの機能を使用しない例を示します。
MyApp_SJProfile0.ser: Info: Oracle features used: MyApp_SJProfile0.ser: Info: * none
2番目の例では、Oracleの機能が複数使用されていることを示し、oracle.sqlパッケージの複数のOracle拡張データ型の一覧を出力しています。
MyApp_SJProfile0.ser: Info: Oracle features used: MyApp_SJProfile0.ser: Info: * oracle.sql.NUMBER: 2 MyApp_SJProfile0.ser: Info: * oracle.sql.DATE: 2 MyApp_SJProfile0.ser: Info: * oracle.sql.CHAR: 2 MyApp_SJProfile0.ser: Info: * oracle.sql.RAW: 2
次の例では、OracleのsetFixedCHAR() APIの使用数が出力されます(このAPIは、Oracleカスタマイザのfixedcharオプションによって有効化され、CHARデータと比較するために、WHERE句に文字列をバインドするときに空白埋めが考慮されます)。
% sqlj -P-Cfixedchar -P-Csummary -P-Cforce *.ser FC_SJProfile0.ser: Info: re-installing Oracle customization FC_SJProfile0.ser: Info: Oracle features used: FC_SJProfile0.ser: Info: * setFixedCHAR(): 4
|
注意: 以前の有効なカスタマイズが検出されてカスタマイズが実行されなかった場合でも、summaryオプションが指定されていると、サマリーが出力されます。 |
コマンドライン構文は、次のとおりです。
-P-Csummary<=true|false>
次にコマンドラインの例を示します。
-P-Csummary
プロパティ・ファイルの構文は、次のとおりです。
profile.Csummary<=true|false>
次にプロパティ・ファイルの例を示します。
profile.Csummary
デフォルト値は、次のとおりです。
false
Oracle SQLJ実装では、この章で後述する特別なカスタマイザも提供されています。これらのカスタマイザにも、コマンドラインのオプションがあります。
SQLCheckerCustomizer(プロファイルのセマンティクス・チェック用): 概要は、「プロファイルのセマンティクス・チェック用のSQLCheckerCustomizer」を参照してください。また、オプションについては、「SQLCheckerCustomizerオプション」を参照してください。
AuditorInstaller(デバッグ用): 概要は、「デバッグ用のAuditorInstallerカスタマイザ」を参照してください。また、オプションについては、「AuditorInstallerオプション」を参照してください。
次のオプションは、プロファイルのカスタマイズに関連するSQLJトランスレータのオプションです。これらのオプションの詳細は、このマニュアルの各項を参照してください。
-default-customizer: 使用するデフォルトのカスタマイザを指定します。このオプションは、カスタマイザ・ハーネスの-customizerに、プロファイル・カスタマイザが指定されていない場合に使用します。
-profile: 今回のSQLJの実行でカスタマイズを行うかどうかを指定します。
「プロファイル・カスタマイズ・フラグ(-profile)」を参照してください。
前述のように、SQLJコマンドラインでJARファイルを指定して、そのJARファイルに含まれるすべてのプロファイルをカスタマイズします。
|
注意:
|
各プロファイルのマニフェスト・エントリには要件があります。
JARファイルに含めるプロファイルごとに2行でテキスト・ファイルを作成します。「Name:」で始まる1行の後にPATHまたはパッケージと名前を記述します。もう1つの行を次に示します。
SQLJProfile: TRUE
この2行は連続していることが必要です(間に空白行を挿入しないでください)。ただし、プロファイルを追加する場合は、追加する2行の前に空白行を挿入する必要があります。
JARユーティリティの-mオプションを使用して、このファイルを入力します。
たとえば、foo/barディレクトリに、3つのプロファイルを持つMyAppというアプリケーションがあり、これらのプロファイルを含むJARファイルを作成するとします。次の手順を実行します。
次のように、セパレータとして使用する空白行を含めて8行で構成されたテキスト・ファイルを作成します。
Name: foo/bar/MyApp_SJProfile0.ser SQLJProfile: TRUE Name: foo/bar/MyApp_SJProfile1.ser SQLJProfile: TRUE Name: foo/bar/MyApp_SJProfile2.ser SQLJProfile: TRUE
ここでは、ファイルの名前をMyAppJarEntries.txtとします。
jarを実行してJARファイルを作成する際に、次のように-mオプションを指定して、作成したテキストを入力します(ここではJARファイルの名前をmyjarfile.jarとします)。
% jar -cvfm myjarfile.jar MyAppJarEntries.txt foo/bar/MyApp_SJProfile*.ser foo/bar/*.class
JARファイルの作成時に、JARユーティリティがマニフェストを生成する場合、このユーティリティは指定されたテキスト・ファイルを読み込み、SQLJProfile: TRUEの行を各プロファイルのマニフェスト・エントリに挿入します。この処理は、マニフェスト内のプロファイル名と、テキスト・ファイルに指定されているプロファイル名が合致すると行われます。
SQLJコマンドラインでJARファイルを指定すると、そのJAR内の各プロファイルはシリアライズ解除され、カスタマイズされます。
JARファイルのカスタマイズは、それに含まれるすべてのプロファイルが正しくカスタマイズされたときに、正常に実行されます。カスタマイズが正常に終了すると、各プロファイルは.serファイルに再びシリアライズされ、元の.serファイルをカスタマイズ後の.serで置き換えるようにJARが変更され、新しいプロファイル・エントリを示すようにJARマニフェスト・ファイルが更新されます。
JARファイル内のプロファイルのカスタマイズ時に1度でもエラーが発生すると、JARファイルのカスタマイズは失敗し、元のJARファイルは完全には変更されません。
|
注意: 認証用にシグネチャ・ファイルを使用している場合、元のJARファイルに含まれているシグネチャ・ファイルは、変更されずに更新後のJARファイルに残ります。プロファイルへのアクセスに署名が必要な場合は、新しいJARファイルの署名を再登録する必要があります。 |
OracleにはSQLCheckerCustomizerと呼ばれる特殊なカスタマイザが用意されており、トランスレータを以前実行した際に生成されたプロファイルに対してセマンティクス・チェックを実行できます。このセマンティクス・チェックは、ソース・コードの変換時に通常実行されるものとほとんど同じです。
これは、実行時に使用するデータベースが変換時のセマンティクス・チェックで使用できない場合に特に有効です。このような場合は、デプロイメント後にランタイム・データベースに対してSQLCheckerCustomizerを使用できます。通常は、ソース・コードを使用できなくなった場合に行います。
使用するチェッカは、指定可能です。SQLCheckerCustomizerでは、デフォルトのOracleCheckerフロントエンドを受け入れると、適切なオンライン・チェッカを使用したオンライン・セマンティクス・チェックが実行されます。
|
注意: プロファイルのオンライン・セマンティクス・チェックでは、カスタマイザ・ハーネスの接続オプションを使用して、接続パラメータを指定することも可能です。 |
次に、Oracleカスタマイザ・ハーネスのverifyオプションを指定して、SQLCheckerCustomizerをデフォルト・モードで実行する例を示します。デフォルトではオンライン・チェッカが使用されるので、カスタマイザ・ハーネスのuser、passwordおよびurlオプションを使用して、接続パラメータを指定する必要があります。(最初の例ではコマンドラインが折り返されて表示されていますが、全体が1行で入力されています。)
% sqlj -P-verify -P-user=scott -P-url=jdbc:oracle:oci:@ Foo_SJProfile0.ser Bar_SJProfile0.ser Password: password % sqlj -P-verify -P-user=scott -P-url=jdbc:oracle:oci:@ *.ser Password: password
verifyオプションを指定すると、カスタマイザ・ハーネスのインスタンスが生成され、次のクラスが起動されます。
sqlj.runtime.profile.util.SQLCheckerCustomizer
プロファイル中のSQL操作に対するセマンティクス・チェックは、このクラスによって調整されます。セマンティクス・チェッカを指定することも、デフォルトのOracleCheckerセマンティクス・チェッカのフロントエンドを受け入れることも可能です。
次のオプションを使用すると、-P-verifyオプションを使用した場合と同じ結果になります。
-P-customizer=sqlj.runtime.profile.util.SQLCheckerCustomizer
このオプションで指定したカスタマイザは、SQLJの-default-customizerオプションで指定されたカスタマイザよりも優先されます。
|
注意:
|
コマンドライン構文は、次のとおりです。
sqlj -P-verify <conn params> profile_list
次にコマンドラインの例を示します。
sqlj -P-verify <conn params> Foo_SJProfile*.ser
プロパティ・ファイルの構文は、次のとおりです。
profile.verify
(SQLJコマンドラインにはプロファイルを必ず指定してください。通常はカスタマイザ・ハーネスの接続オプションを指定します。)
次にプロパティ・ファイルの例を示します。
profile.verify
デフォルト値は、次のとおりです。
NA
他のカスタマイザと同様に、SQLCheckerCustomizerのオプションも、SQLJコマンドラインで接頭辞-P-Cを付けて設定できます。SQLJプロパティ・ファイルでは、接頭辞profile.Cを使用します。
SQLCheckerCustomizerでは、次のオプションがサポートされています。
checker: 使用するセマンティクス・チェッカを指定するためのオプション。デフォルトでは、OracleCheckerフロントエンドが使用されます(SQLJ変換時のチェックに関して)。
warn: プロファイルのセマンティクス・チェック時に出力される警告およびメッセージのカテゴリを指定するためのオプション。これは、SQLJの-warnフラグ(変換時のセマンティクス・チェックにおける警告カテゴリ用)に相当し、同じ設定をサポートし、同じデフォルトを使用します。「トランスレータからの警告(-warn)」を参照してください。
checkerオプションを使用すると、プロファイル中のSQL操作のチェックに使用するセマンティクス・チェッカを指定できます。
このオプションは、デフォルトではOracleセマンティクス・チェッカのフロントエンドoracle.sqlj.checker.OracleCheckerを使用します(これは、SQLCheckerCustomizerに対して環境に適切なオンライン・チェッカを選択します)。OracleCheckerの詳細は、「セマンティクス・チェッカおよびOracleCheckerフロントエンド(デフォルトのチェッカ)」を参照してください。
次に完全なコマンドラインの例を挙げて、SQLCheckerCustomizerのcheckerオプションと、カスタマイザ・ハーネスのverifyオプションおよび接続オプションとを併用する方法を示します。
% sqlj -P-verify -P-user=scott -P-url=jdbc:oracle:oci:@ -P-Cchecker=abc.def.MyChecker *.ser
Password: password
(折り返されて表示されていますが、全体が1行で入力されています。)
コマンドライン構文は、次のとおりです。
-P-Cchecker=checker_class
次にコマンドラインの例を示します。
-P-Cchecker=a.b.c.MyChecker
プロパティ・ファイルの構文は、次のとおりです。
profile.Cchecker=checker_class
次にプロパティ・ファイルの例を示します。
profile.Cchecker=a.b.c.MyChecker
デフォルト値は、次のとおりです。
oracle.sqlj.checker.OracleChecker
warnオプションでは、SQLJトランスレータの-warnオプションと同様に、プロファイルのセマンティクス・チェック時に出力される警告やメッセージのカテゴリを選択できます。
これらのオプションの機能と使用可能な設定の詳細は、「トランスレータからの警告(-warn)」を参照してください。
このオプションのデフォルトでは、verboseおよびportableが有効化されていなければ、all,noverbose,noportableの設定値が使用され、すべての警告カテゴリが出力されます。このときに出力されるのは、継承階層の要件、データの精度、NULL化可能なデータの変換による損失、および名前付きイテレータの厳密な合致に関する警告です。これらのデフォルトは、SQLJ変換時の警告のデフォルトと同じです。
次に完全なコマンドラインの例を挙げて、SQLCheckerCustomizerのwarnオプションと、カスタマイザ・ハーネスのverifyオプションおよび接続オプションとを併用する方法を示します。このように指定すると、移植性に関する警告のみが出力されます。
% sqlj -P-verify -P-user=scott -P-url=jdbc:oracle:oci:@ -P-Cwarn=none,portable *.ser
Password: password
(折り返されて表示されていますが、全体が1行で入力されています。)
コマンドライン構文は、次のとおりです。
-P-Cwarn=comma-delimited_list_of_flags
次にコマンドラインの例を示します。
-P-Cwarn=none,verbose
プロパティ・ファイルの構文は、次のとおりです。
profile.Cwarn=comma-delimited_list_of_flags
次にプロパティ・ファイルの例を示します。
profile.Cwarn=none,verbose
デフォルト値は、次のとおりです。
all,noverbose,noportable
ISOコード生成の場合、SQLJでは、AuditorInstallerという特別なカスタマイザが提供されます。このカスタマイザは、SQLJコマンドラインで指定したプロファイルに、オーディタと呼ばれるデバッグ文のセットを挿入します。これらのプロファイルは、前回のカスタマイズによって生成済であることが必要です。
アプリケーションを実行すると、SQLJランタイムでデバッグ文が実行され、メソッド・コールと戻り値のトレース情報が表示されます。
デバッグ文を挿入するには、カスタマイズの一般オプションの場合と同じように、先頭に-P-を付けて、カスタマイザ・ハーネスのdebugオプションを使用します。(このオプションの構文の詳細は、「カスタマイザ・ハーネスの-debugオプションによるAuditorInstallerの起動」を参照してください。)
アプリケーションのカスタマイズ時に、Oracleカスタマイザは、ランタイム機能の様々なレベルのコードのレイヤー(通常のレイヤー数は4以下)に、プロファイルを実装します。一番下のレイヤーは純粋なOracle JDBCコールを使用し、JDBCの機能を通じて実行できるSQLJ文を実装します。上位の各レイヤーは、JDBCではサポートされていないSQLJ機能用のレイヤーで、SQLJランタイムによってのみ処理されます。たとえば、JDBC結果セットをSQLJイテレータに変換するイテレータ変換文(CAST)用のレイヤーがあります。他には、代入文(SET)用のレイヤーがあります。
コード・レイヤーでは、実行時に各SQLJ実行文が、まず一番上のレイヤーに渡されます。次に、その文を処理できるレイヤー(通常は、すべてのJDBCコールを実行できるレイヤー)まで、1レベルずつレイヤーを経過します。
AuditorInstallerの1回の実行でデバッグ文を挿入できるレイヤーは1つです。特定のコード・レイヤーに挿入されたデバッグ文のセットを総称して、オーディタと呼びます。実行時には、レイヤーにコールが渡されるたびに、そのレイヤーに挿入されているオーディタが起動されます。
通常、JDBCレイヤーより上にある特殊なコード・レイヤーはいずれも、本来のデバッグ対象ではないため、オーディタは一番下か一番上のレイヤーに挿入します。一番上のレイヤーにオーディタを挿入すると、ランタイム・デバッグでは、すべてのSQLJ実行文からのメソッド・コールのトレースが出力されます。一番下のレイヤーにオーディタを挿入すると、ランタイム・デバッグでは、JDBCコールを戻すすべてのSQLJ実行文からのメソッド・コールのトレースが出力されます。
複数のレベルにオーディタを挿入するには、AuditorInstallerを複数回実行します。これは、一番下のレイヤーと一番上のレイヤーにオーディタを挿入する場合などに行います。
オーディタを挿入するレイヤーの指定方法の詳細は、「AuditorInstallerのdepthオプション(depth)」を参照してください。
次に、Oracleカスタマイザ・ハーネスの-debugオプションを指定して、AuditorInstallerをデフォルト・モードで実行する例を示します。
% sqlj -P-debug Foo_SJProfile0.ser Bar_SJProfile0.ser % sqlj -P-debug *.ser % sqlj -P-debug myappjar.jar
debugオプションを指定すると、カスタマイザ・ハーネスのインスタンスが生成され、次のクラスが起動されます。
% sqlj.runtime.profile.util.AuditorInstaller
上に示したクラスは、デバッグ文の挿入作業を実行するクラスです。
次のオプションを使用すると、-P-debugオプションを使用した場合と同じ結果になります。
-P-customizer=sqlj.runtime.profile.util.AuditorInstaller
このオプションで指定したカスタマイザは、SQLJの-default-customizerオプションで指定されたカスタマイザよりも優先されます。
次の点に注意してください。
オーディタをインストールしてアプリケーションを実行するには、CLASSPATHにSQLJファイルtranslator.jarがあることが必要です。(通常、変換済のSQLJアプリケーションを実行するには、ランタイム・ライブラリのみが必要です。)
どのOracleカスタマイザの場合も、SQLJコマンドラインで-P-debugと-P-helpとを指定すると、ヘルプ出力とオプション・リストを見ることが可能です。
debugオプションを使用するとカスタマイザが起動しますが、SQLJの1回の実行で実行できるカスタマイザは1つのみです。このため、このオプションを指定した場合は、他のカスタマイザを起動できません。
-P-print、-P-debugおよび-P-verifyのうち、同時に使用できるのは1つのみです。このうちのどれを使用した場合にも、専用のカスタマイザが起動されるためです。
コマンドライン構文は、次のとおりです。
sqlj -P-debug profile_list
次にコマンドラインの例を示します。
sqlj -P-debug Foo_SJProfile*.ser
プロパティ・ファイルの構文は、次のとおりです。
profile.debug
(ファイル・リストのプロファイルにも指定します。)
次にプロパティ・ファイルの例を示します。
profile.debug
デフォルト値は、次のとおりです。
NA
AuditorInstallerでデバッグ文を挿入すると、実行時にコールされたメソッドと戻り値がトレースされます。この処理は、デバッグ文が挿入されたすべてのプロファイル・レイヤーに対して行われます。実行時にはデバッグ出力を限定できません。
AuditorInstallerの出力は、プロファイルのみに対応付けられています。元の.sqljソース・ファイル内の行とのマッピングは、現行の時点ではサポートされていません。
次は、AuditorInstallerのランタイム出力の例の抜粋です。この出力は、SQLJのSELECT INTO文の出力と似ています。
oracle.sqlj.runtime.OraProfile@1 . getProfileData ( ) oracle.sqlj.runtime.OraProfile@1 . getProfileData returned sqlj.runtime.profile.ref.ProfileDataImpl@2 oracle.sqlj.runtime.OraProfile@1 . getStatement ( 0 ) oracle.sqlj.runtime.OraProfile@1 . getStatement returned oracle.sqlj.runtime.OraRTStatement@3 oracle.sqlj.runtime.OraRTStatement@3 . setMaxRows ( 1000 ) oracle.sqlj.runtime.OraRTStatement@3 . setMaxRows returned oracle.sqlj.runtime.OraRTStatement@3 . setMaxFieldSize ( 3000 ) oracle.sqlj.runtime.OraRTStatement@3 . setMaxFieldSize returned oracle.sqlj.runtime.OraRTStatement@3 . setQueryTimeout ( 1000 ) oracle.sqlj.runtime.OraRTStatement@3 . setQueryTimeout returned oracle.sqlj.runtime.OraRTStatement@3 . setBigDecimal ( 1 , 5 ) oracle.sqlj.runtime.OraRTStatement@3 . setBigDecimal returned oracle.sqlj.runtime.OraRTStatement@3 . setBoolean ( 2 , false ) oracle.sqlj.runtime.OraRTStatement@3 . setBoolean returned oracle.sqlj.runtime.OraRTStatement@3 . executeRTQuery ( ) oracle.sqlj.runtime.OraRTStatement@3 . executeRTQuery returned oracle.sqlj.runtime.OraRTResultSet@6 oracle.sqlj.runtime.OraRTStatement@3 . getWarnings ( ) oracle.sqlj.runtime.OraRTStatement@3 . getWarnings returned null oracle.sqlj.runtime.OraRTStatement@3 . executeComplete ( ) oracle.sqlj.runtime.OraRTStatement@3 . executeComplete returned oracle.sqlj.runtime.OraRTResultSet@6 . next ( ) oracle.sqlj.runtime.OraRTResultSet@6 . next returned true oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal ( 1 ) oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal returned 5 oracle.sqlj.runtime.OraRTResultSet@6 . getDate ( 7 ) oracle.sqlj.runtime.OraRTResultSet@6 . getDate returned 1998-03-28
メソッド・コールごとに、2行出力されます。1行目はそのコールと入力パラメータ、2行目は戻り値を示します。
|
注意: oracle.sqlj.runtimeパッケージ内に含まれるクラスは、SQLJランタイム・クラスで、同様の名前を持つJDBCのクラスと同等の機能を持ちます。たとえば、OraRTResultSetは、JDBC ResultSetインタフェースによるSQLJランタイム実装であり、同等の属性およびメソッドが含まれています。 |
他のカスタマイザと同様に、AuditorInstallerのオプションも、SQLJコマンドラインで接頭辞-P-Cを付けて設定できます(SQLJプロパティ・ファイルでは、profile.Cを使用します)。
AuditorInstallerでは、次のオプションがサポートされています。
depth: プロファイル内のランタイム機能のレイヤーをどこまで下がるのかを指定するためのオプション。
log: 挿入されたオーディタのデバッグ文からのランタイム出力を書き込むファイルを指定するためのオプション。
prefix: 挿入されたデバッグ文からのランタイム出力の各行に付ける接頭辞を指定するためのオプション。
showReturns: ランタイム・コールをトレースした際の戻りの引数を、挿入済のオーディタに書き込むためのオプション。
showThreads: ランタイム・コールをトレースした際のスレッド名を、挿入済のオーディタに書き込むためのオプション(マルチスレッド・アプリケーション専用)。
uninstall: プロファイルに対して、前回AuditorInstallerが起動したときにプロファイルに挿入されたデバッグ文を削除するためのオプション。
「オーディタとコード・レイヤーの概要」で説明したように、AuditorInstallerでは、オーディタと呼ばれるデバッグ文のセットを1回の実行で1つのコード・レイヤーにのみ挿入します。AuditorInstallerのdepthオプションを使用すると、挿入先のレイヤーを指定できます。複数のレベルにオーディタを挿入するには、AuditorInstallerを複数回実行します。
レイヤーには、整数で番号が付けられます。一番上がレイヤー0(ゼロ)になり、レイヤーの階層は通常最大で2つまたは3つになります。通常、一番上のレイヤーには0(ゼロ)、一番下のレイヤーには-1を設定します。実際には、これ以外の特定のレイヤーにオーディタを挿入するのは困難です。これは、各種のSQLJ実行文に使用されるレイヤー番号が、公開されていないためです。
depthオプションは、prefixオプションとともに設定できます。AuditorInstallerを複数回実行して、異なるレイヤーに異なる接頭辞を指定すると、実行時に出力される情報がどのレイヤーのものか確認できます。
depthオプションが設定されていない場合や、プロファイルに指定されているレイヤー数を超えた値が指定された場合、オーディタは一番下のレイヤーに挿入されます。
コマンドライン構文は、次のとおりです。
-P-Cdepth=n
次にコマンドラインの例を示します。
-P-Cdepth=0
プロパティ・ファイルの構文は、次のとおりです。
profile.Cdepth=n
次にプロパティ・ファイルの例を示します。
profile.Cdepth=0
デフォルト値は、次のとおりです。
-1 (deepest layer)
logオプションを使用すると、現行の実行で挿入しているオーディタからのランタイム出力を書き込むファイルを指定できます。そうしない場合は、標準出力が使用されて、デバッグ結果がSQLJメッセージと同じ出力先に出力されるようになります。
オーディタが出力ファイルに書き込むメッセージは、以前の内容を上書きするのではなく、追加されます。そのため、複数のオーディタに対して同じログ・ファイルを指定しても、競合は起こりません。通常、アプリケーション内のすべてのレイヤーからのデバッグ情報は、同じログ・ファイルに書き込まれます。
コマンドライン構文は、次のとおりです。
-P-Clog=log_file
次にコマンドラインの例を示します。
-P-Clog=foo/bar/mylog.txt
プロパティ・ファイルの構文は、次のとおりです。
profile.Clog=log_file
次にプロパティ・ファイルの例を示します。
profile.Clog=foo/bar/mylog.txt
デフォルト値は、次のとおりです。
Empty (for standard output)
prefixオプションを使用して、ランタイム出力の各行に付ける接頭辞を指定します。この出力は、今回の実行で起動するAuditorInstallerによって挿入されるデバッグ文からの結果です。
通常、このオプションは、depthオプションとともに使用されます。AuditorInstallerを複数回実行して、各レイヤーに異なる接頭辞を指定すると、実行時に出力される情報がどのレイヤーのものか確認できます。
コマンドライン構文は、次のとおりです。
-P-Cprefix="string"
次にコマンドラインの例を示します。
-P-Cprefix="layer 2: "
プロパティ・ファイルの構文は、次のとおりです。
profile.Cprefix="string"
次にプロパティ・ファイルの例を示します。
profile.Cprefix="layer 2: "
デフォルト値は、次のとおりです。
Empty
showReturnsオプションは、ランタイム・コールのトレース時に戻り引数の出力を有効化/無効化するためのオプションです。デフォルトでは、出力が有効化されます。
showReturnsを有効にした場合(デフォルト)のサンプル出力を数行のみ次に示します。
oracle.sqlj.runtime.OraRTStatement@3 . executeComplete ( ) oracle.sqlj.runtime.OraRTStatement@3 . executeComplete returned oracle.sqlj.runtime.OraRTResultSet@6 . next ( ) oracle.sqlj.runtime.OraRTResultSet@6 . next returned true oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal ( 1 ) oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal returned 5 oracle.sqlj.runtime.OraRTResultSet@6 . getDate ( 7 ) oracle.sqlj.runtime.OraRTResultSet@6 . getDate returned 1998-03-28
showReturnsを無効にした場合の出力は、次のようになります。
oracle.sqlj.runtime.OraRTStatement@3 . executeComplete ( ) oracle.sqlj.runtime.OraRTResultSet@6 . next ( ) oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal ( 1 ) oracle.sqlj.runtime.OraRTResultSet@6 . getDate ( 7 )
各メソッドのコールに必要なのはコール行のみであって、コール行と戻り行の両方を使用する必要はありません。
コマンドライン構文は、次のとおりです。
-P-CshowReturns<=true|false>
次にコマンドラインの例を示します。
-P-CshowReturns=false
プロパティ・ファイルの構文は、次のとおりです。
profile.CshowReturns<=true|false>
次にプロパティ・ファイルの例を示します。
profile.CshowReturns=false
デフォルト値は、次のとおりです。
true
showThreadsオプションは、ランタイム・コールのトレース時にスレッド名の出力を有効化/無効化するためのオプションです(マルチスレッド・アプリケーション専用)。デフォルトでは、出力が無効化されます。
このオプションを有効化すると、トレース出力中のメソッド名の先頭にスレッド名が付加されます。
コマンドライン構文は、次のとおりです。
-P-CshowThreads<=true|false>
次にコマンドラインの例を示します。
-P-CshowThreads
プロパティ・ファイルの構文は、次のとおりです。
profile.CshowThreads<=true|false>
次にプロパティ・ファイルの例を示します。
profile.CshowThreads
デフォルト値は、次のとおりです。
false
uninstallオプションを使用すると、前回AuditorInstallerを起動したときに挿入されたデバッグ文が削除されます。uninstallオプションを使用するたびに、最後に挿入されたオーディタが削除されます。
プロファイル内のすべてのオーディタを削除するには、プロファイルが変更されなかったことを示すメッセージが表示されるまで、AuditorInstallerを繰り返し実行します。
コマンドライン構文は、次のとおりです。
-P-Cuninstall
次にコマンドラインの例を示します。
-P-Cuninstall
プロパティ・ファイルの構文は、次のとおりです。
profile.Cuninstall
次にプロパティ・ファイルの例を示します。
profile.Cuninstall
デフォルト値は、次のとおりです。
Disabled
ここでは、AuditorInstallerの各種オプションを指定した完全なSQLJコマンドラインの例を示します。
次のコマンドラインはデバッグ文のセット、つまりオーディタを一番下のレイヤー(デフォルトのレイヤー)に挿入し、ランタイム出力を標準出力に出力します。
% sqlj -P-debug MyApp_SJProfile*.ser
次のコマンドラインは、オーディタを一番下のレイヤーに挿入し、ランタイム出力をlog.txtに出力します。
% sqlj -P-debug -P-Clog=foo/bar/log.txt MyApp_SJProfile*.ser
次のコマンドラインは、オーディタを一番下のレイヤーに挿入し、ランタイム出力を標準出力に出力します。この指定では、スレッド名は表示されますが、戻り引数は表示されません。
% sqlj -P-debug -P-CshowThreads=true -P-CshowReturns=false MyApp_SJProfile*.ser
オーディタをレイヤー0(一番上のレイヤー)に挿入します。ランタイム出力をlog.txtに送信し、ランタイム出力の各行に「Layer 0: 」という接頭辞を付けます(次のコマンドラインは折り返されて表示されていますが、全体が1行で入力されています)。
% sqlj -P-debug -P-Clog=foo/bar/log.txt -P-Cdepth=0 -P-Cprefix="Layer 0: " MyApp_SJProfile*.ser
次のコマンドラインは、オーディタを削除します。(このコマンドを実行すると、最後に挿入されたオーディタが削除されます。すべてのオーディタを削除するには、このコマンドを繰り返し実行します。)
% sqlj -P-debug -P-Cuninstall MyApp_SJProfile*.ser
