A カスタマイズおよび専用カスタマイザ
プロファイルとプロファイルのカスタマイズについては、「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ファイルのロードに手間が必要なためです。ただし、いったん自動変換したプロファイルは、カスタマイズの対象にならなくなります。
「コードの生成」で説明したように、アプリケーション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構文(疑問符)に置き換えられることに注意してください。
SQLJ実行文
次のような宣言があるとします。
#sql iterator Iter (double sal, String ename);
また、次のような実行文があるとします。
String empname = 'Smith'; Iter it; ... #sql it = { SELECT first_name, salary FROM employees WHERE first_name = :empname };
対応するSQLJプロファイル・エントリ
================================================================= ... #sql { SELECT first_name, salary FROM employees WHERE first_name = ? }; ... 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カスタマイザを使用すると、Oracle Database 12c リリース2 (12.2)固有の拡張型およびパフォーマンス強化機能を使用するように、プロファイルが最適化されます。
sqlj
スクリプトを実行して、既存のプロファイルをカスタマイズすることも可能です。SQLJコマンドラインで、個々の.ser
ファイル、.ser
ファイルを含むJARファイル、またはその両方を指定できます。
注意:
-
デフォルトのOracleカスタマイザをトランスレータ実行時に使用する場合は、その実行時にOracle SQLJランタイムおよびOracle JDBCドライバがアプリケーションで必要になります。これらは、Oracleの拡張型をコード中に使用しない場合にも必要です。
-
アプリケーションでカスタマイズ(接続のための処理)を行わない場合には、汎用SQLJランタイムが使用されます。
-
SQLJで一度に実行できるのは、
.sqlj
ファイルや.java
ファイルに対する処理(変換、コンパイルおよびカスタマイズの場合)、または.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
ファイルを生成します。 - カスタマイズのみを行うために、コマンドラインで1つ以上のJARファイルを指定してSQLJを実行した場合、カスタマイザ・ハーネスは、カスタマイズされた各
.ser
ファイルで、カスタマイズ前の元の.ser
ファイルを上書きし、JARの内容を再度生成します。
注意:
-
プロファイルのカスタマイズ時にエラーが発生した場合、元の
.ser
ファイルは上書きされません。 -
JARファイル内のプロファイルのカスタマイズ時にエラーが発生した場合、元のJARファイルは上書きされません。
-
SQLJでは、一度に複数のカスタマイザを実行することは不可能です。1つのプロファイルに対して複数回カスタマイズを行うには、SQLJを複数回実行する必要があります。追加でカスタマイズを行う場合は、SQLJのコマンドラインでプロファイル名を直接入力します。
プロファイルのカスタマイズと登録
カスタマイザ・ハーネスは、customize()
メソッドをコールして、プロファイルをカスタマイズします。その場合、このメソッドにプロファイル・オブジェクト、SQLJ接続コンテキスト・オブジェクト(接続が必要なカスタマイザを使用している場合)およびエラー・ログ・オブジェクト(カスタマイズ時に出力されたエラー・メッセージのログに使用)を渡します。
1回のSQLJの実行では、すべてのカスタマイズに同じエラー・ログ・オブジェクトが透過的に使用されます。カスタマイザ・ハーネスは、エラー・ログ・オブジェクトに書き込まれたメッセージを読み込み、標準出力(通常はディスプレイ)にリアルタイムで出力します。
各プロファイルには複数のエントリが含まれており、それぞれSQL操作に対応しています。(これらはアプリケーション内のSQL操作であり、そのプロファイルに対応付けられている接続コンテキスト・クラスのインスタンスが使用されます。)
customize()
は、これらのエントリに対して特別な処理を行います。各エントリの構文の妥当性チェックのような簡単な処理の場合もあれば、元のエントリに特定のデータベースの機能を使用するための変更を加えて、新しいエントリを生成するような複雑な処理の場合もあります。
注意:
-
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
カスタマイザ・ハーネスでサポートされているオプション
カスタマイザ・ハーネスには、次の一般オプションを使用できます。
-
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)
backup
フラグを使用すると、元のファイルに上書きする前に、各.jar
ファイルとスタンドアロンの.ser
ファイルのバックアップ・コピーをハーネスで保存できます。(.jar
内の.ser
ファイル用のバックアップを別に作成する必要はありません。)
バックアップ・ファイル名には、拡張子として.bak
n
が付加されます。n
は、似た名前のファイルが存在する場合に、必要に応じて使用される数字です。バックアップ・ファイルが作成されるたびに、情報メッセージが出力されます。
スタンドアロンの.ser
ファイルのカスタマイズ時にエラーが発生した場合は、元の.ser
ファイルは上書きされず、バックアップも作成されません。同様に、JARファイル内の.ser
ファイルのカスタマイズ時にエラーが発生した場合も、元のJARファイルは上書きされず、バックアップも作成されません。
このオプションのコマンドライン構文は、次のとおりです。
-P-backup<=true|false>
次にコマンドラインの例を示します。
-P-backup
プロパティ・ファイルの構文は、次のとおりです。
profile.backup<=true|false>
デフォルト値は、次のとおりです。
false
カスタマイズ接続コンテキスト・オプション(context)
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)
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ファイルのダイジェスト・オプション(digests)
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社のサイトを参照してください。
JARファイルおよびJARユーティリティの詳細は、次のWebサイトのいずれかを参照してください。
http://www.javasoft.com/products/jdk/1.2/docs/guide/jar/index.html
コマンドライン構文は、次のとおりです。
-P-digests=algo1<,algo2,...>
次にコマンドラインの例を示します。
-P-digests=SHA,MD5
プロパティ・ファイルの構文は、次のとおりです。
profile.digests=algo1<,algo2,...>
次にプロパティ・ファイルの例を示します。
profile.digests=SHA,MD5
デフォルト値は次のとおりです。
SHA,MD5
カスタマイズ用ヘルプ・オプション(help)
help
オプションを使用すると、カスタマイザ・ハーネスと、デフォルトのカスタマイザまたは指定されているカスタマイザのオプションを表示できます。ハーネスおよびOracleカスタマイザに関しては、各オプションの簡単な説明と現行の設定も表示されます。
ハーネスとデフォルトのカスタマイザ(Oracleカスタマイザ、またはSQLJの-default-customizer
オプションで指定されているカスタマイザ)のオプションを表示するには、次のように指定します。
-P-help
次のように、help
オプションにcustomizer
オプションを指定すると、特定のカスタマイザのオプションを表示できます。
-P-help -P-customizer=sqlj.runtime.profile.util.AuditorInstaller
注意:
-
-P-help
オプションは、SQLJコマンドラインでのみ指定できます。SQLJプロパティ・ファイルでは使用できません。 -
-P-help
フラグが有効になっている場合は、カスタマイズするプロファイルをコマンドラインで指定しても、カスタマイズは行われません。
コマンドライン構文は、次のとおりです。
-P-help <-P-customizer=customizer_class>
次にコマンドラインの例を示します。
-P-help
プロパティ・ファイルの構文は、次のとおりです。
NA
次にプロパティ・ファイルの例を示します。
NA
デフォルト値は次のとおりです。
None
カスタマイザ・ハーネスの接続用オプション
ここでは、カスタマイザ・ハーネスでサポートされている接続オプションについて説明します。次のように使用されます。
-
Oracleカスタマイザでは、列定義にのみデータベース接続を使用します。Oracleカスタマイザの
optcols
オプションを有効にしない場合は、カスタマイザ・ハーネスのuser
、password
、url
およびdriver
オプションを設定する必要はありません。 -
SQLCheckerCustomizer
と呼ばれる、プロファイルに対してセマンティクス・チェックを実行する特別なカスタマイザでは、オンライン・チェックの際にカスタマイザ・ハーネスのuser
、password
、url
およびdriver
設定が使用されます。SQLJコマンドラインで
-P-verify
を使用して、カスタマイザを起動します。
注意:
カスタマイザ・ハーネスのuser
、password
、url
およびdriver
オプションと、トランスレータの同名のオプションを、混同しないようにしてください。トランスレータのオプションは、変換処理でのセマンティクス・チェックに使用されるオプションです。ただし、変換と同じ接続を使用するようにカスタマイズする場合は、便宜上トランスレータの設定がカスタマイザに渡されて、利用されます。必要に応じて、カスタマイザ・ハーネス・オプションを使用してこれらの初期設定をオーバーライドしてください。
カスタマイズ用ユーザー・オプション(user)
user
オプションを設定すると、カスタマイザでデータベース接続を使用する場合のデータベース・スキーマを指定できます。
user
オプション設定には、ユーザー・スキーマの他にも、必要に応じてパスワードまたはURL、あるいはその両方を指定できます。次のように、パスワードの先頭にスラッシュ(/)を付け、URLの先頭にアットマーク(@)を付けます。
-P-user=HR/hr -P-user=HR@jdbc:oracle:oci:@ -P-user=HR/hr@jdbc:oracle:oci:@
注意:
列定義(optcols
オプション)を使用するときに、SQLJトランスレータのユーザー設定もプロファイル・カスタマイザに転送されます。カスタマイザのuser
オプションを使用すると、トランスレータの設定を上書きできます。
コマンドライン構文は、次のとおりです。
-P-user=username</password><@url>
次にコマンドラインの例を示します。
-P-user=HR -P-user=HR/password -P-user=HR/password@jdbc:oracle:oci:@
プロパティ・ファイルの構文は、次のとおりです。
profile.user=username</password><@url>
次にプロパティ・ファイルの例を示します。
profile.user=HR profile.user=HR/hr profile.user=HR/hr@jdbc:oracle:oci:@
デフォルト値は次のとおりです。
null
カスタマイズ用パスワード・オプション(password)
password
オプションは、カスタマイザでデータベース接続を使用する場合に使用します。
パスワードは、user
オプションでも設定できます。「カスタマイズ用ユーザー・オプション(user)」を参照してください。
注意:
列定義(optcols
オプション)を使用するときに、SQLJトランスレータのパスワード設定もプロファイル・カスタマイザに転送されます。カスタマイザのpassword
オプションを使用すると、トランスレータの設定を上書きできます。
コマンドライン構文は、次のとおりです。
-P-password=password
次にコマンドラインの例を示します。
-P-password=password
プロパティ・ファイルの構文は、次のとおりです。
profile.password=password
次にプロパティ・ファイルの例を示します。
profile.password=password
デフォルト値は次のとおりです。
null
カスタマイズ用URL・オプション(url)
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:@
カスタマイズ用JDBCドライバ・オプション(driver)
カスタマイザでデータベース接続を使用する場合は、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つのみに限られています。そのため、このオプションを使用した場合は、他のカスタマイズを実行できなくなります。
print
、debug
およびverify
のうち、同時に使用できるのは1つのみです。
専用カスタマイザ: プロファイル・デバッグ・オプション(debug)
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)
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)
verify
オプションを指定すると、プロファイルに対してセマンティクス・チェックを実行するSQLCheckerCustomizer
という特殊なカスタマイザが起動されます。これは、変換時にソース・コードに対して実行されるセマンティクス・チェックに相当します。このプロファイルは、前のSQLJトランスレータ実行時にすでに作成されています。
このオプションは、デプロイメント後やソース・コードが使用されなくなった後の、ランタイム・データベースに対するセマンティクス・チェックに役立ちます。
このカスタマイザでサポートされている他のオプションなどの詳細は、「プロファイルのセマンティクス・チェック用のSQLCheckerCustomizer」を参照してください。
注意:
プロファイルのオンライン・セマンティクス・チェックの際にも、カスタマイザ・ハーネスのuser
、password
およびurl
オプションを使用する必要があります。
たとえば、次のようにverify
オプションを指定します。次の2つの例では、どちらもSQLCheckerCustomizer
のデフォルトのセマンティクス・チェッカを使用し、特定のデータベース接続によるオンライン・チェックを行います。(最初の例ではコマンドラインが折り返されて表示されていますが、全体が1行で入力されています。)
% sqlj -P-verify -P-user=HR -P-url=jdbc:oracle:oci:@ Foo_SJProfile0.ser Bar_SJProfile0.ser Password: password % sqlj -P-verify -P-user=HR -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
この項のこれ以降では、Oracleカスタマイザの機能について説明します。Oracleカスタマイザでは、いくつかのオプションがサポートされています。これらのオプションの大半はブール値であり、有効にするには次のようにします。
-P-Coption
または
-P-Coption=true
ブール値のオプションは、デフォルトでは無効になっています。明示的に無効にするには、次のように指定します。
-P-Coption=false
数値オプションや文字列オプションの設定は、ほとんど同じです。
-P-Coption=value
Oracleカスタマイザのオプション
ここでは、Oracleカスタマイザ固有のオプションについて説明します。まず、サポートされているオプションの概要を示します。
Oracleカスタマイザでサポートされているオプション
Oracleカスタマイザでは、次のオプションを使用できます。
-
compat
: バージョンの互換性に関する情報を表示するためのオプション -
force
: すでに有効なカスタマイズが行われている場合でも、カスタマイズを実行するためのオプション -
optcols
: パフォーマンスが最適化されるようにイテレータ列型およびサイズ定義を有効化するためのオプション。 -
optparams
: パラメータ・サイズを、JDBCリソース割当て量が最適化されるように定義するためのオプション(optparamdefaults
と併用します)。 -
optparamdefaults
: 特定のデータ型に対してパラメータ・サイズのデフォルトを設定するためのオプション(optparams
と併用します)。 -
fixedchar
:WHERE
句に関して、空白埋めを考慮したCHAR
比較を有効にするためのオプション。 -
showSQL
: SQL文の変換情報を表示するためのオプション。 -
stmtcache
: 文のキャッシュ・サイズ(実行時に各接続でキャッシングできる文の数)を設定するためのオプション。パフォーマンスの最適化に必要なサイズを設定する場合と、文のキャッシングを無効化するために0(ゼロ)が設定される場合があります。 -
summary
: アプリケーションで使用されているOracleの機能の概要を表示するためのオプション。
これらのオプションによって出力された内容は、SQLJの他のメッセージと同じように、標準出力に書き込まれます。
Oracleカスタマイザのバージョン互換性オプション(compat)
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
オプションを指定したときに出力される内容です。最初に、アプリケーションが、すべてのバージョンの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
Oracleカスタマイザの強制オプション(force)
force
フラグを有効にすると、Oracleカスタマイザによって特定の(コマンドラインで指定された)プロファイルのカスタマイズが強制的に実行されます。そのプロファイルに、すでに有効なカスタマイズが認識される場合でも、実行されます。次に例を示します。
% sqlj -P-Cforce MyApp_SJProfile*.ser
これを実行すると、カスタマイズ済かどうかにかかわらず、MyApp
のプロファイルがすべてカスタマイズされます。デフォルトでは、Oracleカスタマイザは既存のカスタマイズを上書きして再インストールすることはありません(ただし、既存のカスタマイズが古いバージョンのカスタマイザでインストールされている場合を除きます)。
コマンドライン構文は、次のとおりです。
-P-Cforce<=true|false>
次にコマンドラインの例を示します。
-P-Cforce
プロパティ・ファイルの構文は、次のとおりです。
profile.Cforce<=true|false>
次にプロパティ・ファイルの例を示します。
profile.Cforce
デフォルト値は次のとおりです。
false
Oracleカスタマイザの列定義オプション(optcols)
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
フラグの有効化/無効化は、SQLJのコマンドラインまたはプロパティ・ファイルで設定します。
このフラグをコマンドラインで有効にするには、次のようにします。
-P-Coptcols
または
-P-Coptcols=true
このフラグは、デフォルトでは無効になっていますが、明示的に無効化することも可能です。このフラグをコマンドラインで無効化するには、次のようにします。
-P-Coptcols=false
列を定義するには、カスタマイザでデータベース接続を行って、問合せの対象とする表の列を調べる必要があります。そのために、カスタマイザ・ハーネスのuser
、password
およびurl
オプションを適切に設定する必要があります(デフォルトのOracleDriver
クラスを使用しない場合は、カスタマイザ・ハーネスのdriver
オプションも)。次に例を示します。
% sqlj <...SQLJ options...> -P-user=HR@jdbc:oracle:oci:@ -P-Coptcols MyApp.sqlj Password: password
SQLJトランスレータの場合と同様に、必要に応じて、パスワードとURLをpassword
オプションとurl
オプションでそれぞれ設定するかわりに、user
オプションで設定できます。
または、次のようにして、列定義を既存のプロファイルに挿入することも可能です。この場合は、Oracleカスタマイザのforce
オプションを使用して、カスタマイズを再実行する必要があります。
% sqlj -P-user=HR@jdbc:oracle:oci:@ -P-Cforce -P-Coptcols MyApp_SJProfile*.ser
Password: password
また、次のようにして、列定義をJARファイル中の既存のプロファイルに挿入することも可能です。
% sqlj -P-user=HR@jdbc:oracle:oci:@ -P-Cforce -P-Coptcols MyAppProfiles.jar
Password: password
Oracleカスタマイザ実行時(新規のプロファイルの変換時や生成時、または既存プロファイルのカスタマイズ時)にoptcols
フラグを有効化すると、カスタマイザ・ハーネスのverbose
フラグも有効化できます。このフラグを有効化すると、処理対象のイテレータおよび結果セット、列型およびサイズ定義の情報がOracleカスタマイザに表示されます。次に例を示します。
% sqlj -P-user=HR@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
Oracleカスタマイザのパラメータ定義オプション(optparams)
パラメータ・サイズの定義を有効化するには、optparams
フラグを使用します。SQLJではこのフラグを有効にすると、入出力パラメータ(ホスト変数)が登録され、JDBCリソース割当て量が指定したサイズに基づいて最適化されます。
パラメータ・サイズ定義の概要とソース・コード・ヒントの詳細は、「パラメータ・サイズの定義」を参照してください。
注意:
このオプションのかわりに、SQLJトランスレータの-optparams
オプションを使用できます。これは、カスタマイザのオプションを自動的に設定するオプションです。(また、プロファイルを使用しないOracle固有コード生成の場合は、トランスレータのオプションを使用する必要があります。)
参照先の項では、さらに概念についても説明されています。
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
Oracleカスタマイザ用パラメータのデフォルト・サイズ・オプション(optparamdefaults)
optparams
オプションを有効にしてパラメータ・サイズを設定した場合は、必要に応じてoptparamdefaults
オプションを使用してデータ型のデフォルト・サイズを設定します。optparams
を有効にしないと、optparamdefaults
が設定されていても無視されるので注意してください。
パラメータ・サイズ定義の概要とソース・コード・ヒントの詳細は、「パラメータ・サイズの定義」を参照してください。
注意:
このオプションのかわりに、SQLJトランスレータの-optparamdefaults
オプションを使用できます。これは、カスタマイザのオプションを自動的に設定するオプションです。(また、プロファイルを使用しないOracle固有コード生成の場合は、トランスレータのオプションを使用する必要があります。)
参照先の項では、さらに概念と構文についても説明されています。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
既存のプロファイルに対してパラメータ・サイズのデフォルトを指定することも可能です。ただし、この場合は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
Oracleカスタマイザによる空白埋めを考慮したCHAR比較(fixedchar)
WHERE
句の比較で文字列をバインドするときにCHAR
型のデータベース列の空白埋めを考慮するには、このフラグをtrue
に設定します。この比較方法では、たとえば、"mystring"と"mystring "は同等であるとみなされます。
次に、Oracleカスタマイザのfixedchar
の使用例を示します。
% sqlj -P-Cfixedchar MyProgram.sqlj AnotherProg.java ...
注意:
-
このオプションのかわりに、SQLJトランスレータの
-fixedchar
オプションを使用できます。これは、カスタマイザのオプションを自動的に設定するオプションです。(また、プロファイルを使用しないOracle固有コード生成の場合は、トランスレータのオプションを使用する必要があります。) -
Oracleカスタマイザの
summary
フラグも有効にすると、(fixedchar
機能の背後で使用される)OracleのsetFixedCHAR()
APIの使用数が表示されます。例については、「Oracleカスタマイザのサマリー・オプション(summary)」を参照してください。
コマンドライン構文は、次のとおりです。
-P-Cfixedchar<=true|false>
次にコマンドラインの例を示します。
-P-Cfixedchar
プロパティ・ファイルの構文は、次のとおりです。
profile.Cfixedchar<=true|false>
次にプロパティ・ファイルの例を示します。
profile.Cfixedchar
デフォルト値は次のとおりです。
false
OracleカスタマイザのSQL表示オプション(showSQL)
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)
Oracleカスタマイザのstmtcache
オプションを使用すると、文のキャッシュ・サイズ(アプリケーション実行時にデータベース接続ごとにキャッシングできる文の数)を設定したり、文のキャッシングを無効化することが可能です。
文のキャッシュ・サイズのデフォルトは5です。文のキャッシングの概要は、「文のキャッシング」を参照してください。
注意:
デフォルトのOracle固有のコード生成(-codegen=oracle
)を使用する場合、SQLJではプロファイルが生成されず、カスタマイズが実行されません。この場合、接続コンテキスト・メソッドを使用してSQLJ文キャッシングを制御します。
文のキャッシュ・サイズは、コマンドラインでもプロパティ・ファイルでも設定できます。
コマンドラインを使用して、アプリケーション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
Oracleカスタマイザのサマリー・オプション(summary)
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
オプションを指定したときに出力される内容です。最初に、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オプション」を参照してください。
プロファイルのJARファイル
前述のように、SQLJコマンドラインでJARファイルを指定して、そのJARファイルに含まれるすべてのプロファイルをカスタマイズします。
注意:
-
SQLJコマンドラインでは、
.sqlj
ファイルまたは.java
ファイル、あるいはその両方を指定して標準のSQLJ処理を実行するか、.ser
ファイルまたは.jar
ファイル、あるいはその両方を指定してカスタマイズのみを実行できます。ただし、その両方の処理を同時には実行できません。 -
.jar
ファイルには、プロファイル以外のファイルが含まれている場合があります。マニフェスト・エントリでそのファイルがプロファイルではないことが示されている場合、そのファイルはカスタマイズ時に無視されます。 -
.jar
ファイルは、それに含まれる各プロファイルに対して、クラスをロードするコンテキストとして使用されます。プロファイルで.jar
ファイル内のクラスが参照される場合、そのクラスは.jar
ファイルからロードされます。プロファイルで参照されるクラスが.jar
ファイル内にない場合は、通常の処理と同じように、システム・クラス・ローダーによって、CLASSPATHの指定に従ってクラスが検出されてロードされます。
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
の行を各プロファイルのマニフェスト・エントリに挿入します。この処理は、マニフェスト内のプロファイル名と、テキスト・ファイルに指定されているプロファイル名が合致すると行われます。
JARファイルのロジスティクス
SQLJコマンドラインでJARファイルを指定すると、そのJAR内の各プロファイルはシリアライズ解除され、カスタマイズされます。
JARファイルのカスタマイズは、それに含まれるすべてのプロファイルが正しくカスタマイズされたときに、正常に実行されます。カスタマイズが正常に終了すると、各プロファイルは.ser
ファイルに再びシリアライズされ、元の.ser
ファイルをカスタマイズ後の.ser
で置き換えるようにJARが変更され、新しいプロファイル・エントリを示すようにJARマニフェスト・ファイルが更新されます。
JARファイル内のプロファイルのカスタマイズ時に1度でもエラーが発生すると、JARファイルのカスタマイズは失敗し、元のJARファイルは完全には変更されません。
注意:
認証用にシグネチャ・ファイルを使用している場合、元のJARファイルに含まれているシグネチャ・ファイルは、変更されずに更新後のJARファイルに残ります。プロファイルへのアクセスに署名が必要な場合は、新しいJARファイルの署名を再登録する必要があります。
プロファイルのセマンティクス・チェック用のSQLCheckerCustomizer
OracleにはSQLCheckerCustomizer
と呼ばれる特殊なカスタマイザが用意されており、トランスレータを以前実行した際に生成されたプロファイルに対してセマンティクス・チェックを実行できます。このセマンティクス・チェックは、ソース・コードの変換時に通常実行されるものとほとんど同じです。
これは、実行時に使用するデータベースが変換時のセマンティクス・チェックで使用できない場合に特に有効です。このような場合は、デプロイメント後にランタイム・データベースに対してSQLCheckerCustomizer
を使用できます。通常は、ソース・コードを使用できなくなった場合に行います。
使用するチェッカは、指定可能です。SQLCheckerCustomizer
では、デフォルトのOracleChecker
フロントエンドを受け入れると、適切なオンライン・チェッカを使用したオンライン・セマンティクス・チェックが実行されます。
注意:
プロファイルのオンライン・セマンティクス・チェックでは、カスタマイザ・ハーネスの接続オプションを使用して、接続パラメータを指定することも可能です。
カスタマイザ・ハーネスのverifyオプションによるSQLCheckerCustomizerの起動
次に、Oracleカスタマイザ・ハーネスのverify
オプションを指定して、SQLCheckerCustomizer
をデフォルト・モードで実行する例を示します。デフォルトではオンライン・チェッカが使用されるので、カスタマイザ・ハーネスのuser
、password
およびurl
オプションを使用して、接続パラメータを指定する必要があります。(最初の例ではコマンドラインが折り返されて表示されていますが、全体が1行で入力されています。)
% sqlj -P-verify -P-user=HR -P-url=jdbc:oracle:oci:@ Foo_SJProfile0.ser Bar_SJProfile0.ser Password: password % sqlj -P-verify -P-user=HR -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
オプションで指定されたカスタマイザよりも優先されます。
注意:
-
どのOracleカスタマイザでも同様ですが、SQLJコマンドラインで
-P-verify
と-P-help
とを指定すると、ヘルプ出力とオプション・リストを見ることが可能です。 -
verify
オプションを使用するとカスタマイザが起動しますが、SQLJの1回の実行で実行できるカスタマイザは1つのみです。このため、このオプションを指定した場合は、他のカスタマイザを起動できません。 -
-P-print
、-P-debug
および-P-verify
のうち、同時に使用できるのは1つのみです。このうちのどれを使用した場合にも、専用のカスタマイザが起動されるためです。
コマンドライン構文は、次のとおりです。
sqlj -P-verify <conn params> profile_list
次にコマンドラインの例を示します。
sqlj -P-verify <conn params> Foo_SJProfile*.ser
プロパティ・ファイルの構文は、次のとおりです。
profile.verify
(SQLJコマンドラインにはプロファイルを必ず指定してください。通常はカスタマイザ・ハーネスの接続オプションを指定します。)
次にプロパティ・ファイルの例を示します。
profile.verify
デフォルト値は次のとおりです。
NA
SQLCheckerCustomizerのオプション
他のカスタマイザと同様に、SQLCheckerCustomizer
のオプションも、SQLJコマンドラインで接頭辞-P-C
を付けて設定できます。SQLJプロパティ・ファイルでは、接頭辞profile.C
を使用します。
SQLCheckerCustomizer
では、次のオプションがサポートされています。
-
checker
: 使用するセマンティクス・チェッカを指定するためのオプション。デフォルトでは、OracleChecker
フロントエンドが使用されます(SQLJ変換時のチェックに関して)。 -
warn
: プロファイルのセマンティクス・チェック時に出力される警告およびメッセージのカテゴリを指定するためのオプション。これは、SQLJの-warn
フラグ(変換時のセマンティクス・チェックにおける警告カテゴリ用)に相当し、同じ設定をサポートし、同じデフォルトを使用します。
SQLCheckerCustomizerセマンティクス・チェッカのオプション(checker)
checker
オプションを使用すると、プロファイル中のSQL操作のチェックに使用するセマンティクス・チェッカを指定できます。
このオプションは、デフォルトではOracleセマンティクス・チェッカのフロントエンドoracle.sqlj.checker.OracleChecker
を使用します(これは、SQLCheckerCustomizer
に対して環境に適切なオンライン・チェッカを選択します)。
次に完全なコマンドラインの例を挙げて、SQLCheckerCustomizer
のchecker
オプションと、カスタマイザ・ハーネスのverify
オプションおよび接続オプションとを併用する方法を示します。
% sqlj -P-verify -P-user=HR -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
SQLCheckerCustomizerの警告オプション(warn)
warn
オプションでは、SQLJトランスレータの-warn
オプションと同様に、プロファイルのセマンティクス・チェック時に出力される警告やメッセージのカテゴリを選択できます。
このオプションのデフォルトでは、verbose
およびportable
が有効化されていなければ、all,noverbose,noportable
の設定値が使用され、すべての警告カテゴリが出力されます。このときに出力されるのは、継承階層の要件、データの精度、NULL化可能なデータの変換による損失、および名前付きイテレータの厳密な合致に関する警告です。これらのデフォルトは、SQLJ変換時の警告のデフォルトと同じです。
次に完全なコマンドラインの例を挙げて、SQLCheckerCustomizer
のwarn
オプションと、カスタマイザ・ハーネスのverify
オプションおよび接続オプションとを併用する方法を示します。このように指定すると、移植性に関する警告のみが出力されます。
% sqlj -P-verify -P-user=HR -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
デバッグ用のAuditorInstallerカスタマイザ
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)」を参照してください。
カスタマイザ・ハーネスの-debugオプションによるAuditorInstallerの起動
次に、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
でデバッグ文を挿入すると、実行時にコールされたメソッドと戻り値がトレースされます。この処理は、デバッグ文が挿入されたすべてのプロファイル・レイヤーに対して行われます。実行時にはデバッグ出力を限定できません。
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のオプション
他のカスタマイザと同様に、AuditorInstaller
のオプションも、SQLJコマンドラインで接頭辞-P-C
を付けて設定できます(SQLJプロパティ・ファイルでは、profile.C
を使用します)。
AuditorInstaller
では、次のオプションがサポートされています。
-
depth
: プロファイル内のランタイム機能のレイヤーをどこまで下がるのかを指定するためのオプション。 -
log
: 挿入されたオーディタのデバッグ文からのランタイム出力を書き込むファイルを指定するためのオプション。 -
prefix
: 挿入されたデバッグ文からのランタイム出力の各行に付ける接頭辞を指定するためのオプション。 -
showReturns
: ランタイム・コールをトレースした際の戻りの引数を、挿入済のオーディタに書き込むためのオプション。 -
showThreads
: ランタイム・コールをトレースした際のスレッド名を、挿入済のオーディタに書き込むためのオプション(マルチスレッド・アプリケーション専用)。 -
uninstall
: プロファイルに対して、前回AuditorInstaller
が起動したときにプロファイルに挿入されたデバッグ文を削除するためのオプション。
AuditorInstallerのdepthオプション(depth)
「オーディタとコード・レイヤーの概要」で説明したように、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)
AuditorInstallerのlog_fileオプション(log)
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)
AuditorInstallerのprefixオプション(prefix)
prefix
オプションを使用して、ランタイム出力の各行に付ける接頭辞を指定します。この出力は、今回の実行で起動するAuditorInstaller
によって挿入されるデバッグ文からの結果です。
通常、このオプションは、depth
オプションとともに使用されます。AuditorInstaller
を複数回実行して、各レイヤーに異なる接頭辞を指定すると、実行時に出力される情報がどのレイヤーのものか確認できます。
コマンドライン構文は、次のとおりです。
-P-Cprefix="string"
次にコマンドラインの例を示します。
-P-Cprefix="layer 2: "
プロパティ・ファイルの構文は、次のとおりです。
profile.Cprefix="string"
次にプロパティ・ファイルの例を示します。
profile.Cprefix="layer 2: "
デフォルト値は次のとおりです。
Empty
AuditorInstallerの戻り引数オプション(showReturns)
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
AuditorInstallerのスレッド名オプション(showThreads)
showThreads
オプションは、ランタイム・コールのトレース時にスレッド名の出力を有効化/無効化するためのオプションです(マルチスレッド・アプリケーション専用)。デフォルトでは、出力が無効化されます。
このオプションを有効化すると、トレース出力中のメソッド名の先頭にスレッド名が付加されます。
コマンドライン構文は、次のとおりです。
-P-CshowThreads<=true|false>
次にコマンドラインの例を示します。
-P-CshowThreads
プロパティ・ファイルの構文は、次のとおりです。
profile.CshowThreads<=true|false>
次にプロパティ・ファイルの例を示します。
profile.CshowThreads
デフォルト値は次のとおりです。
false
AuditorInstallerのuninstallオプション(uninstall)
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