コントロールを使用する
このトピックでは、Web サービスからコントロールを使用する方法について説明します。説明する内容は次のとおりです。
既存のコントロールを見つける
既存のコントロールを使用する
コントロールをインポートおよび宣言する
コントロールのメソッドを呼び出す
コントロールのコールバックを処理する
コントロールの生成した例外を処理する
このトピックでは、開発者本人または別の開発者が実装したコントロールにアクセスできることを前提にしています。プロジェクトにあるコントロールの CTRL ファイルにアクセスできれば、コントロールにアクセスできます。次の節では、コントロールにアクセスするために、コントロールの CTRL ファイルと Web サービスの JWS ファイルを変更する方法について説明します。
コントロールの詳細については、コントロール : Web サービスからリソースを使用するを参照してください。
既存のコントロールを Web サービスで使用するには、コントロールを Web サービスに追加する方法、コピーする方法、参照する方法があります。どの方法にも特徴があります。以降の節では、状況に応じて最適な方法を使い分けられるように、それぞれの方法について詳しく説明します。
コントロールの CTRL ファイルは、必ず WebLogic Workshop プロジェクトに配置しなければなりません。Java にはパッケージ間の参照に関するルールがあり、このファイルが正しい場所に配置されていないと、コントロールを使用できません。CTRL ファイルをプロジェクトのルート フォルダに配置すると、ルート フォルダにない Web サービス（つまり Java のデフォルト パッケージ）はコントロールを使用できません。
WebLogic Workshop のプロジェクトの構成については、WebLogic Workshop プロジェクトを参照してください。
Web サービスから既存のコントロールを使用するには、コントロールの CTRL ファイルをプロジェクト ツリーの中で探し、そのファイルを Web サービスのデザイン ビューにドラッグします。
既存の CTRL ファイルがプロジェクトに含まれている場合、CTRL ファイルをプロジェクト ツリーからコントロールを使用する Web サービスのデザイン ビューにドラッグして、そのコントロールへの参照を任意の Web サービスに追加することができます。デザイン ビューの右上隅の [コントロールの追加] メニューを使用することもできます。デザイン ビューでコントロールに変更を加えると、参照先の CTRL ファイルに影響します。つまり、同じ CTRL ファイルを参照する他の Web サービスにも影響します。
使用したい CTRL ファイルまたはコントロールがプロジェクトに入っていない場合には、プロジェクトにコピーする必要があります。コントロールのコピー先は、コントロールの使い方によって異なります。コントロールをプロジェクト内の 1 つの Web サービスだけで使用する場合は、Web サービスと同じフォルダに CTRL ファイルをコピーします。プロジェクト内の別々のフォルダにある複数の Web サービスでコントロールを使用する場合は、コントロールの CTRL ファイルを共通のフォルダにコピーすると便利です。ただし、CTRL ファイルは WebLogic Workshop プロジェクト内になければなりません。
コントロールの CTRL ファイルは、必ず WebLogic Workshop プロジェクトに入っている必要があります。
注意 :Java 用語では、デフォルト パッケージで定義されているクラスは、名前を付けられた（デフォルト以外の）パッケージで定義されているクラスから参照できません。つまり、CTRL ファイルをプロジェクトのルート フォルダに配置すると、ルート フォルダにないすべての Web サービスからコントロールを参照できなくなります。Java のパッケージの詳細については、Java の概要を参照してください。
CTRL ファイルを別の場所にコピーすることは、新しいコントロールを作成することと同じです。コピーしたコントロールの定義を変更しなければ、同じコントロールが 2 つ存在することになります。コピー後に元のコントロールを変更しても、コピーしたコントロールは変更されません。つまり、元のコントロールのバグを修正したり、機能を拡張したりしても、コピーしたコントロールには反映されません。
複数の Web サービスで同じコントロールを使用し、そのコントロールに対する変更がそのコントロールを使用するすべての Web サービスの動作に反映されるようにしたい場合は、コントロールをコピーするのではなく、元のコントロールを参照します。
プロジェクト内のコントロールを参照するには、適切な import 文を Web サービスの JWS ファイル内に作成します。コントロールのインポート方法については、コントロールをインポートおよび宣言するを参照してください。
CTRL ファイルを WebLogic Workshop プロジェクト内の別の場所にドラッグすると、package 文は自動的に変更されるので、この節の残りを読む必要はありません。しかし、プロジェクト ツリー内でドラッグする以外の方法でコントロールの CTRL ファイルをコピーする場合、CTRL ファイルの package 文を変更する必要があります。
Java では、ディレクトリ階層におけるソース ファイルの場所によって、ファイルのクラスが属する Java パッケージが決まります。つまり、場所とパッケージ名が一致する必要があります。Java ファイルの場所が <project>\controls\financial ディレクトリの場合、ファイルで次のように Java の package 文を指定しなければなりません。
package controls.financial;
コントロールの CTRL ファイルを別の場所にコピーしたら、ファイルの package 文をその場所に合わせて変更する必要があります。
Java のパッケージの詳細については、Java の概要を参照してください。
Web サービスでコントロールを使用するための方法として、コントロールの CTRL ファイルをデザイン ビューにドラッグする場合、Web サービスの JWS ファイルのコードは必要に応じて自動的に変更されるので、この節の残りを読む必要はありません。しかし、Web サービスの JWS ファイルでコントロールのインスタンスを手動で宣言する場合、WebLogic Workshop がコントロールに接続できるように、コントロールのクラスをインポートする、コントロールのインスタンスを宣言する、およびコントロールのインスタンス宣言に正しくコメントを付けるという作業が必要です。この節では、これらの手順について説明します。
Web サービスからコントロールを使用するには、Java の import 文でコントロールのメイン インタフェースを Web サービスの JWS ファイルにインポートします。通常、import 文は次のような形式となります。
import controls.financial.CurrencyExchangeControl;
Java の import 文の詳細については、Java の概要を参照してください。
コントロールをインポートしたら、Web サービスで使用する前にコントロールのインスタンスを宣言する必要があります。コントロールを宣言するには、コントロールの宣言であることを示す Javadoc コメントを記述し、Web サービス内でコントロールを表すメンバー変数を宣言する必要があります。次に例を示します。
/** * @jws:control */ private CurrentExchangeControl currency;
@jws:control タグは、関連付けられたコードで宣言するオブジェクトを WebLogic Workshop 内でコントロールとして扱うことと、WebLogic Workshop がコントロールをサポート コードに結び付けることを、WebLogic Workshop のユーザ インタフェースに指示します。
宣言自体には、weblogic.jws.control.Control インタフェースを（間接的に）拡張するインタフェースを記述する必要があります。
JWS のメソッドの外側でコントロールのインスタンスを使用しても意味がないので、コントロールのインスタンスは Web サービスの JWS ファイル内のプライベートとして宣言するのが一般的です。
前の節で説明したようにコントロールを宣言したら、Java 標準のドット（.）表記を使用してコントロールのメソッドにアクセスできます。たとえば、CurrencyExchangeControl というコントロールが次のメソッドを定義しているものとします。
String [] getAllAvailableCurrencyNames();
Web サービスの JWS ファイルからメソッドにアクセスするには、次のコードを使用します。
String [] currencyNames; currencyNames = currency.getAllAvailableCurrencyNames();
コントロールの種類によっては、コールバックを指定できます。コールバックを使用すると、コントロールまたは Web サービスからイベントの発生をクライアントに非同期で通知できます。
非同期性の詳細については、非同期性を利用して長期間の処理を実現するを参照してください。
コールバックは、コントロール（または Web サービス）によって定義されるメソッド シグネチャであり、メソッドの実装はクライアント側で提供する必要があります。クライアント側でコールバックを受け取れるようにするには、コールバック ハンドラを実装します。
コントロールにおけるコールバックの定義は次のようになります。
void onReportStatus(String status);
この宣言は、コールバックを定義するサービスまたはコントロールのソース コードに記述します。
コールバックがイベントを表し、クライアントのコールバック ハンドラはイベントの発生時に呼び出されるので、コールバックの名前は「on」で始めるのが一般的です。
クライアントでは、受け取るコールバックに対応するハンドラを実装する必要があります。前の節で取り上げたサンプルのコールバックに対するコールバック ハンドラを実装するには、Web サービスの JWS ファイルに次のコードを含めます。
void exampleControl_onReportStatus(String status)
{
<take appropriate action given status>
}
WebLogic Workshop では、コールバック ハンドラの名前はコントロール インスタンスの名前とコールバックの名前によって決まります。上の例の場合、exampleControl というコントロール インスタンスからコールバックを受け取り、そのコントロールによって onReportStatus というコールバックが定義されています。コールバック ハンドラの完全名は、コントロール インスタンス名の後ろにアンダースコアとコールバック名を付けた exampleControl_onReportStatus となります。
コントロールを設計する場合、コントロールのメソッドによって送出される例外を明示的に宣言するかどうかを選択できます。コントロールのメソッドが例外を送出するように定義する場合、メソッドの呼び出しを try-catch ブロックで囲む必要があります。
例外を宣言しないようにコントロールを設計しても、コントロールを実装するサポート コードが例外を送出する場合があります。そうした例外は、常に weblogic.jws.control.ControlExceptionとして送出されます。
Web サービスで使用するコントロールによって送出される可能性があるすべての例外について、十分に考慮しておく必要があります。コントロールによって送出された例外を処理しないと、Web サービスのメソッドが失敗し、その例外は Web サービスのクライアントに渡されます。ほとんどの場合、クライアントには例外は意味をなさず、問題を診断したり解決したりするために必要な情報もありません。
例外と try-catch ブロックの詳細については、Java の概要を参照してください。