カスタマイズおよび専用カスタマイザ

A カスタマイズおよび専用カスタマイザ

プロファイルとプロファイルのカスタマイズについては、「SQLJプロファイル」を参照してください。この付録では、技術的な詳細を示し、カスタマイザ・オプション、デフォルトのOracleカスタマイザ以外のカスタマイザの使用方法についても説明します。

また、Oracleの専用カスタマイザについても、特にプロファイルのセマンティクス・チェック用のSQLCheckerCustomizer、およびデバッグに使用するオーディタのインストール用のAuditorInstallerを中心に説明します。

内容は次のとおりです。

注意:

この付録の説明は、デフォルトのOracle固有のコード生成(-codegen=oracle)を使用する場合は適用されません。

A.1 プロファイルについて

SQLJプロファイルには、埋込みSQL操作に関する情報が含まれています。プロファイルは、アプリケーションで使用される接続コンテキスト・クラスごとに、個別に作成されます。プロファイルは、SQLJトランスレータのコード生成フェーズで作成され、カスタマイズ・フェーズでカスタマイズされます。カスタマイズすると、アプリケーションでベンダー固有のデータベース機能を使用できるようになります。このようなベンダー固有の操作を別々のプロファイルにまとめると、それ以外の生成コードを汎用として使用できます。

各プロファイルには、関連する接続コンテキスト・クラスを使用するSQLJ文に対する一連のエントリが含まれています。各エントリは、アプリケーション内の1つのSQL操作に対応しています。

プロファイルは、アプリケーションとパッケージ化されるリソース・ファイルに、シリアライズされたオブジェクトとして保存されます。このため、プロファイルをいつでもロード、読取りおよび変更(追加または再カスタマイズ)できます。プロファイルのカスタマイズ時に、情報は追加されますが、削除されることはありません。プロファイルを複数回カスタマイズしても、以前のカスタマイズ内容が失われることはなく、アプリケーションは複数の環境で実行可能なままです。これをバイナリ移植性と呼びます。

プロファイルにバイナリ移植性を持たせるために、Oracle SQLJはSQLJの業界標準に従って実装されています。

A.1.1 コード生成時のプロファイルの生成

トランスレータは、コード生成時に次のようにプロファイルを生成します。

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ファイル)を示します。

A.1.2 プロファイル・エントリの例

ここでは、SQLJ実行文と、生成されるプロファイル・エントリの例を示します。ここに示すプロファイル・エントリは、わかりやすいように関係のない部分は省略して、テキストで表記してあります。

プロファイル・エントリでは、ホスト変数がJDBC構文(疑問符)に置き換えられることに注意してください。

A.1.2.1 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 };

A.1.2.2 対応する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オプションを使用するとテキストとして出力することができます(「カスタマイザ・ハーネスのオプションの概要」を参照)。

A.2 プロファイルのカスタマイズについて

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ファイルに対する処理(カスタマイズのみの場合)のいずれか一方です。

A.2.1 カスタマイザ・ハーネスおよびカスタマイザの概要

Oracleカスタマイザを使用する場合も、その他のカスタマイザを使用する場合も、SQLJでのカスタマイズには、カスタマイザ・ハーネスと呼ばれるフロントエンドのカスタマイズ・ユーティリティが使用されます。

SQLJの実行時に指定できるカスタマイズ・オプションとしては、カスタマイザ・ハーネス用(あらゆるカスタマイザに適用できる一般的なカスタマイザ設定)およびカスタマイザ用(カスタマイザ固有の設定)があります。これらのオプションは、コマンドラインまたはプロパティ・ファイルで指定します。詳細は、「カスタマイズ・オプションとカスタマイザの選択」を参照してください。

カスタマイザは、プロパティを公開するために、標準のJavaBeans APIに適合するJavaBeansコンポーネントであることが必要です。また、customize()メソッドを指定しているsqlj.runtime.profile.util.ProfileCustomizerインタフェースを実装する必要があります。カスタマイザ・ハーネスは、カスタマイズするプロファイルごとに、カスタマイザ・オブジェクトのcustomize()メソッドをコールします。

Oracleカスタマイザは前述の要件を満たしています。このカスタマイザはoracle.sqlj.runtime.OraCustomizerクラスに定義されています。

A.2.2 カスタマイズ処理の手順

変換時のカスタマイズ処理は、次のように行われます。これは、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のコマンドラインでプロファイル名を直接入力します。

A.2.3 プロファイルのカスタマイズと登録

カスタマイザ・ハーネスは、customize()メソッドをコールして、プロファイルをカスタマイズします。その場合、このメソッドにプロファイル・オブジェクト、SQLJ接続コンテキスト・オブジェクト(接続が必要なカスタマイザを使用している場合)およびエラー・ログ・オブジェクト(カスタマイズ時に出力されたエラー・メッセージのログに使用)を渡します。

1回のSQLJの実行では、すべてのカスタマイズに同じエラー・ログ・オブジェクトが透過的に使用されます。カスタマイザ・ハーネスは、エラー・ログ・オブジェクトに書き込まれたメッセージを読み込み、標準出力(通常はディスプレイ)にリアルタイムで出力します。

各プロファイルには複数のエントリが含まれており、それぞれSQL操作に対応しています。(これらはアプリケーション内のSQL操作であり、そのプロファイルに対応付けられている接続コンテキスト・クラスのインスタンスが使用されます。)

customize()は、これらのエントリに対して特別な処理を行います。各エントリの構文の妥当性チェックのような簡単な処理の場合もあれば、元のエントリに特定のデータベースの機能を使用するための変更を加えて、新しいエントリを生成するような複雑な処理の場合もあります。

注意:

customize()でプロファイル・エントリを処理しても、元のエントリが変更されることはありません。
特定の環境で使用できるようにプロファイルをカスタマイズしても、アプリケーションを他の環境で実行できなくなることはありません。プロファイルは、複数の環境で使用できるように、複数回カスタマイズすることが可能であり、これらのカスタマイズ間で互いに干渉することはありません。

A.2.4 カスタマイズ時のエラー・メッセージとステータス・メッセージ

カスタマイザ・ハーネスでのエラー・メッセージとステータス・メッセージは、SQLJトランスレータと同じ出力デバイスに出力されます。ただし、カスタマイズに関する警告メッセージは、非表示にはできません。

カスタマイザ・ハーネスによって生成されるエラー・メッセージは、次の4つのカテゴリに分類できます。

認識できないオプションまたは不正なオプション
接続のインスタンス化エラー
プロファイルのインスタンス化エラー
カスタマイザのインスタンス化エラー

カスタマイズ時に、カスタマイザ・ハーネスからステータス・メッセージが報告されます。これらのメッセージを参照して、プロファイルが正しくカスタマイズされたかどうかを確認できます。次の3つのカテゴリに分類できます。

プロファイルの変更状態
JARファイルの変更状態
作成されたバックアップ・ファイル名(カスタマイザ・ハーネスのbackupオプションが設定されている場合)

この他にも、特定のカスタマイザのcustomize()のメソッドによって、カスタマイザ固有のエラーや警告が出力される場合があります。

カスタマイズ時には、プロファイル・カスタマイザがメッセージがエラー・ログに書き込み、カスタマイザ・ハーネスがログの内容をリアルタイムに読み取って、これらのメッセージと、ハーネスからの他の出力とあわせてSQLJの出力デバイスに出力します。ユーザーがエラー・ログの内容に直接アクセスする必要はありません。

A.2.5 カスタマイズされたプロファイルの実行時の機能

カスタマイズされたプロファイルは、それが対応付けられている接続コンテキスト・クラスの静的なメンバーです。アプリケーション内のSQLJ文ごとに、SQLJランタイムは、その文に関連付けられている接続コンテキスト・クラスとインスタンスを確認し、その接続コンテキスト・クラスのカスタマイズされたプロファイルと、特定の接続コンテキスト・インスタンスの基になるJDBC接続を使用して、接続プロファイルを作成します。この接続プロファイルをSQLJランタイムで使用すると、SQLJアプリケーションの実行時にベンダー固有の機能を利用できるようになります。

A.3 カスタマイズ・オプションとカスタマイザの選択

ここでは、プロファイルのカスタマイズ時のオプションについて説明します。これらのオプションは、次の3つのカテゴリに分類できます。

カスタマイザ・ハーネスに対して指定するオプション。使用するカスタマイザに関係なく適用されます。

このオプションの例としては、一般オプション、接続オプション、専用カスタマイザを起動するオプションなどがあります。
カスタマイザ固有のオプション。これらのオプションはカスタマイザ・ハーネスを介して、使用するカスタマイザに対して指定します。
SQLJオプション。これらのオプションは、カスタマイズを行うかどうか、どのカスタマイザを使用するかなど、カスタマイズの基本事項を指定します。

どのカテゴリのオプションも、すべてSQLJコマンドラインまたはプロパティ・ファイルを使用して指定します。

この項の内容は、次のとおりです。

デフォルトのOracleカスタマイザ以外のカスタマイザを選択するには、カスタマイザ・ハーネスのcustomizerオプション(「カスタマイザ・ハーネスのオプションの概要」を参照)またはSQLJの-default-customizerオプション(「プロファイルのカスタマイズ用のSQLJトランスレータのオプション」を参照)を使用します。

A.3.1 カスタマイザ・ハーネスのオプションの概要

Oracle SQLJ実装のカスタマイザ・ハーネスには、特定のカスタマイザ以外にも使用できるオプションがいくつか用意されています。このハーネスの各オプションは、カスタマイズ処理をフロントエンドで調整する際に使用されます。

A.3.1.1 カスタマイザ・ハーネスのオプションの構文

SQLJコマンドラインでカスタマイザ・ハーネス・オプションを設定する場合は、次の構文を使用します。

-P-option=value

または、SQLJプロパティ・ファイルで、次の構文を使用します。

profile.option=value

ブール値のオプション(フラグ)を有効にするには、次のように指定します。

-P-option

または

-P-option=true

ブール値のオプションは、デフォルトでは無効になっています。明示的に無効にするには、次のように指定します。

-P-option=false

A.3.1.2 カスタマイザ・ハーネスでサポートされているオプション

カスタマイザ・ハーネスには、次の一般オプションを使用できます。

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」を参照してください。

A.3.2 カスタマイザ・ハーネスの一般オプション

この項では、カスタマイザ・ハーネスでサポートされている一般オプションについて説明します。

A.3.2.1 プロファイル・バックアップ・オプション(backup)

backupフラグを使用すると、元のファイルに上書きする前に、各.jarファイルとスタンドアロンの.serファイルのバックアップ・コピーをハーネスで保存できます。(.jar内の.serファイル用のバックアップを別に作成する必要はありません。)

バックアップ・ファイル名には、拡張子として.baknが付加されます。nは、似た名前のファイルが存在する場合に、必要に応じて使用される数字です。バックアップ・ファイルが作成されるたびに、情報メッセージが出力されます。

スタンドアロンの.serファイルのカスタマイズ時にエラーが発生した場合は、元の.serファイルは上書きされず、バックアップも作成されません。同様に、JARファイル内の.serファイルのカスタマイズ時にエラーが発生した場合も、元のJARファイルは上書きされず、バックアップも作成されません。

このオプションのコマンドライン構文は、次のとおりです。

-P-backup<=true|false>

次にコマンドラインの例を示します。

-P-backup

プロパティ・ファイルの構文は、次のとおりです。

profile.backup<=true|false>

デフォルト値は、次のとおりです。

false

A.3.2.2 カスタマイズ接続コンテキスト・オプション(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

A.3.2.3 カスタマイザ・オプション(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

A.3.2.4 カスタマイズ用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

A.3.2.5 カスタマイズ用ヘルプ・オプション(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

A.3.2.6 カスタマイズ用の詳細オプション(verbose)

verboseフラグを使用すると、カスタマイズ時にハーネスからステータス・メッセージを表示できます。これらのメッセージは、SQLJの他のメッセージと同じように、標準出力に書き込まれます。

コマンドライン構文は、次のとおりです。

-P-verbose<=true|false>

次にコマンドラインの例を示します。

-P-verbose

プロパティ・ファイルの構文は、次のとおりです。

profile.verbose<=true|false>

次にプロパティ・ファイルの例を示します。

profile.verbose

デフォルト値は次のとおりです。

false

A.3.3 カスタマイザ・ハーネスの接続用オプション

ここでは、カスタマイザ・ハーネスでサポートされている接続オプションについて説明します。次のように使用されます。

Oracleカスタマイザでは、列定義にのみデータベース接続を使用します。Oracleカスタマイザのoptcolsオプションを有効にしない場合は、カスタマイザ・ハーネスのuser、password、urlおよびdriverオプションを設定する必要はありません。
SQLCheckerCustomizerと呼ばれる、プロファイルに対してセマンティクス・チェックを実行する特別なカスタマイザでは、オンライン・チェックの際にカスタマイザ・ハーネスのuser、password、urlおよびdriver設定が使用されます。

SQLJコマンドラインで-P-verifyを使用して、カスタマイザを起動します。

注意:

カスタマイザ・ハーネスのuser、password、urlおよびdriverオプションと、トランスレータの同名のオプションを、混同しないようにしてください。トランスレータのオプションは、変換処理でのセマンティクス・チェックに使用されるオプションです。ただし、変換と同じ接続を使用するようにカスタマイズする場合は、便宜上トランスレータの設定がカスタマイザに渡されて、利用されます。必要に応じて、カスタマイザ・ハーネス・オプションを使用してこれらの初期設定をオーバーライドしてください。

A.3.3.1 カスタマイズ用ユーザー・オプション(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

A.3.3.2 カスタマイズ用パスワード・オプション(password)

passwordオプションは、カスタマイザでデータベース接続を使用する場合に使用します。

パスワードは、userオプションでも設定できます。「カスタマイズ用ユーザー・オプション(user)」を参照してください。

注意:

列定義(optcolsオプション)を使用するときに、SQLJトランスレータのパスワード設定もプロファイル・カスタマイザに転送されます。カスタマイザのpasswordオプションを使用すると、トランスレータの設定を上書きできます。

コマンドライン構文は、次のとおりです。

-P-password=password

次にコマンドラインの例を示します。

-P-password=password

プロパティ・ファイルの構文は、次のとおりです。

profile.password=password

次にプロパティ・ファイルの例を示します。

profile.password=password

デフォルト値は次のとおりです。

null

A.3.3.3 カスタマイズ用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:@

A.3.3.4 カスタマイズ用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

A.3.4 専用のカスタマイザの起動に使用するカスタマイザ・ハーネスのオプション

特別なカスタマイザの起動には、次に示したカスタマイザ・ハーネスのオプションを使用できます。

debug: デバッグに使用するAuditorInstallerカスタマイザを起動するためのオプション
print: プロファイルをテキスト形式で出力するカスタマイザを起動するためのオプション
verify: プロファイルに対してセマンティクス・チェックを実行するSQLCheckerCustomizerカスタマイザを起動するためのオプション

注意:

これらの各オプションを使用すると特定のカスタマイザを起動できますが、SQLJの1回の実行で実行できるカスタマイザは1つのみに限られています。そのため、このオプションを使用した場合は、他のカスタマイズを実行できなくなります。

print、debugおよびverifyのうち、同時に使用できるのは1つのみです。

A.3.4.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

A.3.4.2 専用カスタマイザ: プロファイル出力オプション(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

デフォルト値は次のとおりです。

該当なし

A.3.4.3 専用カスタマイザ: プロファイルのセマンティクス・チェック用オプション(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

A.3.5 カスタマイザ固有のオプションの概要

カスタマイザ固有のオプション(Oracleカスタマイザ用のオプションなど)は、SQLJコマンドラインまたはSQLJプロパティ・ファイルに設定できます。この構文は、カスタマイザ・ハーネスのオプション設定に使用する構文とほとんど同じです。

SQLJコマンドラインでカスタマイザ・オプションを設定する場合は、先頭に次の文字列を付けます。

-P-C

SQLJプロパティ・ファイルで設定するときは、先頭に次の文字列を付けます。

profile.C

この項のこれ以降では、Oracleカスタマイザの機能について説明します。Oracleカスタマイザでは、いくつかのオプションがサポートされています。これらのオプションの大半はブール値であり、有効にするには次のようにします。

-P-Coption

または

-P-Coption=true

ブール値のオプションは、デフォルトでは無効になっています。明示的に無効にするには、次のように指定します。

-P-Coption=false

数値オプションや文字列オプションの設定は、ほとんど同じです。

-P-Coption=value

A.3.6 Oracleカスタマイザのオプション

ここでは、Oracleカスタマイザ固有のオプションについて説明します。まず、サポートされているオプションの概要を示します。

A.3.6.1 Oracleカスタマイザでサポートされているオプション

Oracleカスタマイザでは、次のオプションを使用できます。

compat: バージョンの互換性に関する情報を表示するためのオプション
force: すでに有効なカスタマイズが行われている場合でも、カスタマイズを実行するためのオプション
optcols: パフォーマンスが最適化されるようにイテレータ列型およびサイズ定義を有効化するためのオプション。
optparams: パラメータ・サイズを、JDBCリソース割当て量が最適化されるように定義するためのオプション(optparamdefaultsと併用します)。
optparamdefaults: 特定のデータ型に対してパラメータ・サイズのデフォルトを設定するためのオプション(optparamsと併用します)。
fixedchar: WHERE句に関して、空白埋めを考慮したCHAR比較を有効にするためのオプション。
showSQL: SQL文の変換情報を表示するためのオプション。
stmtcache: 文のキャッシュ・サイズ(実行時に各接続でキャッシングできる文の数)を設定するためのオプション。パフォーマンスの最適化に必要なサイズを設定する場合と、文のキャッシングを無効化するために0(ゼロ)が設定される場合があります。
summary: アプリケーションで使用されているOracleの機能の概要を表示するためのオプション。

これらのオプションによって出力された内容は、SQLJの他のメッセージと同じように、標準出力に書き込まれます。

A.3.6.2 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

A.3.6.3 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

A.3.6.4 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

A.3.6.5 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

A.3.6.6 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

A.3.6.7 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

A.3.6.8 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

A.3.6.9 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

デフォルト値は次のとおりです。

A.3.6.10 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

A.3.7 他のカスタマイザ用のオプション

Oracle SQLJ実装では、この章で後述する特別なカスタマイザも提供されています。これらのカスタマイザにも、コマンドラインのオプションがあります。

SQLCheckerCustomizer (プロファイルのセマンティクス・チェック用): 概要は、「プロファイルのセマンティクス・チェック用のSQLCheckerCustomizer」を参照してください。また、オプションについては、「SQLCheckerCustomizerオプション」を参照してください。
AuditorInstaller (デバッグ用): 概要は、「デバッグ用のAuditorInstallerカスタマイザ」を参照してください。また、オプションについては、「AuditorInstallerオプション」を参照してください。

A.3.8 プロファイルのカスタマイズ用のSQLJトランスレータのオプション

次のオプションは、プロファイルのカスタマイズに関連するSQLJトランスレータのオプションです。これらのオプションの詳細は、このマニュアルの各項を参照してください。

-default-customizer: 使用するデフォルトのカスタマイザを指定します。このオプションは、カスタマイザ・ハーネスの-customizerに、プロファイル・カスタマイザが指定されていない場合に使用します。
-profile: 今回のSQLJの実行でカスタマイズを行うかどうかを指定します。

A.4 プロファイルのJARファイル

前述のように、SQLJコマンドラインでJARファイルを指定して、そのJARファイルに含まれるすべてのプロファイルをカスタマイズします。

注意:

SQLJコマンドラインでは、.sqljファイルまたは.javaファイル、あるいはその両方を指定して標準のSQLJ処理を実行するか、.serファイルまたは.jarファイル、あるいはその両方を指定してカスタマイズのみを実行できます。ただし、その両方の処理を同時には実行できません。
.jarファイルには、プロファイル以外のファイルが含まれている場合があります。マニフェスト・エントリでそのファイルがプロファイルではないことが示されている場合、そのファイルはカスタマイズ時に無視されます。
.jarファイルは、それに含まれる各プロファイルに対して、クラスをロードするコンテキストとして使用されます。プロファイルで.jarファイル内のクラスが参照される場合、そのクラスは.jarファイルからロードされます。プロファイルで参照されるクラスが.jarファイル内にない場合は、通常の処理と同じように、システム・クラス・ローダーによって、CLASSPATHの指定に従ってクラスが検出されてロードされます。

A.4.1 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の行を各プロファイルのマニフェスト・エントリに挿入します。この処理は、マニフェスト内のプロファイル名と、テキスト・ファイルに指定されているプロファイル名が合致すると行われます。

A.4.2 JARファイルのロジスティクス

SQLJコマンドラインでJARファイルを指定すると、そのJAR内の各プロファイルはシリアライズ解除され、カスタマイズされます。

JARファイルのカスタマイズは、それに含まれるすべてのプロファイルが正しくカスタマイズされたときに、正常に実行されます。カスタマイズが正常に終了すると、各プロファイルは.serファイルに再びシリアライズされ、元の.serファイルをカスタマイズ後の.serで置き換えるようにJARが変更され、新しいプロファイル・エントリを示すようにJARマニフェスト・ファイルが更新されます。

JARファイル内のプロファイルのカスタマイズ時に1度でもエラーが発生すると、JARファイルのカスタマイズは失敗し、元のJARファイルは完全には変更されません。

注意:

認証用にシグネチャ・ファイルを使用している場合、元のJARファイルに含まれているシグネチャ・ファイルは、変更されずに更新後のJARファイルに残ります。プロファイルへのアクセスに署名が必要な場合は、新しいJARファイルの署名を再登録する必要があります。

A.5 プロファイルのセマンティクス・チェック用のSQLCheckerCustomizer

OracleにはSQLCheckerCustomizerと呼ばれる特殊なカスタマイザが用意されており、トランスレータを以前実行した際に生成されたプロファイルに対してセマンティクス・チェックを実行できます。このセマンティクス・チェックは、ソース・コードの変換時に通常実行されるものとほとんど同じです。

これは、実行時に使用するデータベースが変換時のセマンティクス・チェックで使用できない場合に特に有効です。このような場合は、デプロイメント後にランタイム・データベースに対してSQLCheckerCustomizerを使用できます。通常は、ソース・コードを使用できなくなった場合に行います。

使用するチェッカは、指定可能です。SQLCheckerCustomizerでは、デフォルトのOracleCheckerフロントエンドを受け入れると、適切なオンライン・チェッカを使用したオンライン・セマンティクス・チェックが実行されます。

注意:

プロファイルのオンライン・セマンティクス・チェックでは、カスタマイザ・ハーネスの接続オプションを使用して、接続パラメータを指定することも可能です。

A.5.1 カスタマイザ・ハーネスの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

A.5.2 SQLCheckerCustomizerオプション

他のカスタマイザと同様に、SQLCheckerCustomizerのオプションも、SQLJコマンドラインで接頭辞-P-Cを付けて設定できます。SQLJプロパティ・ファイルでは、接頭辞profile.Cを使用します。

SQLCheckerCustomizerでは、次のオプションがサポートされています。

checker: 使用するセマンティクス・チェッカを指定するためのオプション。デフォルトでは、OracleCheckerフロントエンドが使用されます(SQLJ変換時のチェックに関して)。
warn: プロファイルのセマンティクス・チェック時に出力される警告およびメッセージのカテゴリを指定するためのオプション。これは、SQLJの-warnフラグ(変換時のセマンティクス・チェックにおける警告カテゴリ用)に相当し、同じ設定をサポートし、同じデフォルトを使用します。

A.5.2.1 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

A.5.2.2 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

A.6 デバッグ用のAuditorInstallerカスタマイザ

ISOコード生成の場合、SQLJでは、AuditorInstallerという特別なカスタマイザが提供されます。このカスタマイザは、SQLJコマンドラインで指定したプロファイルに、オーディタと呼ばれるデバッグ文のセットを挿入します。これらのプロファイルは、前回のカスタマイズによって生成済であることが必要です。

アプリケーションを実行すると、SQLJランタイムでデバッグ文が実行され、メソッド・コールと戻り値のトレース情報が表示されます。

デバッグ文を挿入するには、カスタマイズの一般オプションの場合と同じように、先頭に-P-を付けて、カスタマイザ・ハーネスのdebugオプションを使用します。(このオプションの構文の詳細は、「カスタマイザ・ハーネスの-debugオプションによるAuditorInstallerの起動」を参照してください。)

A.6.1 オーディタとコード・レイヤーの概要

アプリケーションのカスタマイズ時に、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)」を参照してください。

A.6.2 カスタマイザ・ハーネスの-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

A.6.3 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ランタイム実装であり、同等の属性およびメソッドが含まれています。

A.6.4 AuditorInstallerオプション

他のカスタマイザと同様に、AuditorInstallerのオプションも、SQLJコマンドラインで接頭辞-P-Cを付けて設定できます(SQLJプロパティ・ファイルでは、profile.Cを使用します)。

AuditorInstallerでは、次のオプションがサポートされています。

depth: プロファイル内のランタイム機能のレイヤーをどこまで下がるのかを指定するためのオプション。
log: 挿入されたオーディタのデバッグ文からのランタイム出力を書き込むファイルを指定するためのオプション。
prefix: 挿入されたデバッグ文からのランタイム出力の各行に付ける接頭辞を指定するためのオプション。
showReturns: ランタイム・コールをトレースした際の戻りの引数を、挿入済のオーディタに書き込むためのオプション。
showThreads: ランタイム・コールをトレースした際のスレッド名を、挿入済のオーディタに書き込むためのオプション(マルチスレッド・アプリケーション専用)。
uninstall: プロファイルに対して、前回AuditorInstallerが起動したときにプロファイルに挿入されたデバッグ文を削除するためのオプション。

A.6.4.1 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)

A.6.4.2 AuditorInstallerのログ・ファイル・オプション(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)

A.6.4.3 AuditorInstallerのprefixオプション(prefix)

prefixオプションを使用して、ランタイム出力の各行に付ける接頭辞を指定します。この出力は、今回の実行で起動するAuditorInstallerによって挿入されるデバッグ文からの結果です。

通常、このオプションは、depthオプションとともに使用されます。AuditorInstallerを複数回実行して、各レイヤーに異なる接頭辞を指定すると、実行時に出力される情報がどのレイヤーのものか確認できます。

コマンドライン構文は、次のとおりです。

-P-Cprefix="string"

次にコマンドラインの例を示します。

-P-Cprefix="layer 2: "

プロパティ・ファイルの構文は、次のとおりです。

profile.Cprefix="string"

次にプロパティ・ファイルの例を示します。

profile.Cprefix="layer 2: "

デフォルト値は次のとおりです。

Empty

A.6.4.4 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

A.6.4.5 AuditorInstallerのスレッド名オプション(showThreads)

showThreadsオプションは、ランタイム・コールのトレース時にスレッド名の出力を有効化/無効化するためのオプションです(マルチスレッド・アプリケーション専用)。デフォルトでは、出力が無効化されます。

このオプションを有効化すると、トレース出力中のメソッド名の先頭にスレッド名が付加されます。

コマンドライン構文は、次のとおりです。

-P-CshowThreads<=true|false>

次にコマンドラインの例を示します。

-P-CshowThreads

プロパティ・ファイルの構文は、次のとおりです。

profile.CshowThreads<=true|false>

次にプロパティ・ファイルの例を示します。

profile.CshowThreads

デフォルト値は次のとおりです。

false

A.6.4.6 AuditorInstallerのuninstallオプション(uninstall)

uninstallオプションを使用すると、前回AuditorInstallerを起動したときに挿入されたデバッグ文が削除されます。uninstallオプションを使用するたびに、最後に挿入されたオーディタが削除されます。

プロファイル内のすべてのオーディタを削除するには、プロファイルが変更されなかったことを示すメッセージが表示されるまで、AuditorInstallerを繰り返し実行します。

コマンドライン構文は、次のとおりです。

-P-Cuninstall

次にコマンドラインの例を示します。

-P-Cuninstall

プロパティ・ファイルの構文は、次のとおりです。

profile.Cuninstall

次にプロパティ・ファイルの例を示します。

profile.Cuninstall

デフォルト値は次のとおりです。

Disabled

A.6.5 完全なコマンドラインの例

ここでは、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