このセクションでは、デフォルトでサポートされていないメッセージ形式をカバーするために、 Virtualize のインターフェイス と操作を拡張する方法について説明します。
このセクションの内容:
| Table of Contents | ||
|---|---|---|
|
カスタム メッセージ形式とは
SOAtest/ Virtualize には、SOAtest/Virtualize のビルトイン メッセージ形式を拡張できるフレーム ワークがあります。 このフレーム ワークは、ユーザーが作業する任意のメッセージ形式をサポートします。たとえば、メインフレーム メッセージ形式、バイナリ形式、またはその他の独自のメッセージ形式などです。メッセージ形式は、ネイティブ形式と XML 間の変換を作成することで定義します。この変換によってユーザーは、 SOAtest で利用可能な XML ツールを使用して、メッセージを構成し検証できます。 拡張機能は Java で実装されます。
カスタム メッセージ形式が追加されると、 Virtualize はそのメッセージ形式を使用してリクエスト/レスポンス メッセージを構成および送信できる新しいレスポンダー を自動的に作成します。ユーザーはこの新しいクライアントのインスタンスをユーザーの テスト シナリオに追加できます。
これらのクライアントの使用方法については、カスタム Message Responder を参照してください。新しいメッセージ形式は XML Converter ツールにも表示されます。詳細については、「XML Converter」に記載しています。
フォーマット間の一般的な変換定義に加えて、そのフォーマット中の各メッセージの正確な構造を定義する、特定のメッセージ タイプのセットを任意で定義できます。たとえば、ユーザーは XML 変換に一般的な FIX を定義したとします。しかし、ユーザーのアプリケーションで使用される特定の FIX メッセージのセットも定義したとします。各メッセージ タイプの構成は、 XML スキーマを使用して定義され、 SOAtest/Virtualize の拡張機能によって提供されます。
カスタム メッセージ形式用に実装するインターフェイス
環境を設定したら (拡張機能の追加: 基本手順)、Extensibility API ドキュメントに記載のある以下のインターフェイスを実装します。
- com.parasoft.api.message.ICustomXMLConverter
- com.parasoft.api.message.ISchemaGenerator (任意)
ICustomXMLConverter の実装
ネイティブ形式と XML 間の変換ロジックを実装するのに使用する必須クラスです。toXML() メソッドはユーザーのメッセージを XML フォーマットで返し、 toNative() メソッドはユーザーのメッセージをネイティブ形式で返します。 メソッドは次の引数を受け取ります:
- INativeMessage または IXMLMessage: 変換されるメッセージの表現を読み出すのに使用します。
- IConversionContext: 構成設定と、異なるメソッド間でのデータの共有方法を提供します。 さらに、 IConversionContext は ScriptingContext を継承します。 ScriptingContext は Parasoft の標準スクリプティング コンテキストで、変数やデータ ソース値への接続や、ツール間で共有するためにオブジェクトの設定や取得ができます。
toXML() は INativeMessage を返し、 toNative() は IXMLMessage を返します。便宜上使用できる、これらのインターフェイスのデフォルト実装があります (DefaultNativeMessage および DefaultXMLMessage) 。
toNative では、実装者は xmlMessage パラメーターのメッセージ タイプが {@code null} である場合に対応する必要があります。定義されている特定の変換が、明確なメッセージ タイプを渡されないと XML からネイティブ メッセージへの変換方法が分からない場合、{@link CustomConversionException} がスローされます。
toXML では、変換が任意で書かれている可能性があるので、渡された nativeMessage のメッセージ タイプを自動的に検出できます。この自動検出は、リテラル ビューからフォーム ビューに切り替えるときや、仮想アセットの生成にトラフィック ウィザードを使用するときに、メッセージ タイプを判断するために使用されます。変換が自動検出をサポートしない場合、メッセージ タイプを明示的に選択するか、 SOAtestはメッセージ タイプの検出を試みます (必ずしも正しいとは限りません)。自動検出をサポートするには、実装者は渡される nativeMessage のメッセージ タイプを無視するべきです。代わりに自分でメッセージ タイプを判断し、返される XML メッセージに設定します。
変換が自動検出をサポートしているかどうかを SOAtest/Virtualize が判断する方法であるため、実装者は nativeMessage パラメーターのメッセージ タイプが {@code null} である場合に対応する必要があります。定義されている特定の変換が自動検出をサポートしてなく、そのためにメッセージ タイプを渡されないと変換方法が分からない場合、 {@link CustomConversionException} がスローされるべきです。
変換中に発生した エラー の対処方法は 2 種類あります。エラーが変換処理を中止すべき致命的なエラーの場合、適切なエラーメッセージと CustomConversionException がスローされます。エラーが致命的でない場合 (つまり変換処理は継続できる場合)、 メッセージは IConversionContext.report(String メッセージ) を使用してレポートされ、(おそらく部分的に) 変換されたメッセージはメソッドによって返されます。エラーが例外のスローや report() の呼び出しによってレポートされた場合、クライアント/レスポンダーの GUI ダイアログとしてレポートされるか、クライアント / レスポンダーが実行時のエラーメッセージとしてレポートされます。
これらの変換処理は、以下の状況においてクライアント や XML Converter ツールから実行されます。
- フォーム ビューと Literal ビューを切り替える。
- 回線を通じて送信するために、 フォーム入力ビューまたは フォーム XML ビューからメッセージを構成する。
- 受信したメッセージを処理する。
- XML Converter ツールを実行する。
ISchemaGenerator の実装
与えられたメッセージ形式に対して特定のメッセージ タイプを定義するとき、各メッセージ タイプに対する XML スキーマ を提供する必要があります。ISchemaGenerator はオプションのクラスです。与えられた特定のメッセージ タイプに XML スキーマを提供するメソッドを提供します。このクラスを実装せずに parasoft-extension.xml でこのクラスを参照している場合、代わりにスキーマ ファイルへの参照を提供する必要があります (詳細については、「カスタム メッセージ形式用に parasoft-extension.xml を定義」を参照してください)。
このインターフェイスは、次の引数を取る generateSchema() というメソッドだけを持ちます。
- IMessageType: スキーマが生成されるべきメッセージ タイプについての情報を提供します。渡された IMessageType のインスタンスは、 parasoft-extension.xml で定義されたメッセージ タイプの ID と名前を含みます。
ICustomXMLConverterConfiguration: カスタム メッセージ形式 クライアントの [変換オプション] タブから渡される値へのアクセスを提供します。
generateSchema() は スキーマ ファイルへの参照である URI を返します。動的に生成されたスキーマへの参照、カスタム メッセージ形式拡張を提供する JAR ファイルにあるスキーマへの参照、または SOAtest 外部のリソースへの参照が考えられます。 スキーマの生成にエラーが生じた場合、空の URI が返され、フォーム入力ビューは与えられたメッセージ タイプで適切に反映されません。
| Anchor | ||||
|---|---|---|---|---|
|
必要なクラスを実装したら、parasoft-extension.xml を定義します ( 拡張機能の追加: 基本手順 (Virtualize))。以下のスキーマを使用します:
| Code Block |
|---|
<?xml version="1.0" encoding="UTF-8"?>
<extension xmlns="urn:ocm/parasoft/extensibility-framework/extension"
type="messageFormat"
name='the name of your message format, appears in menus' description='A more detailed description'>
<class>com.myCompany.MyConverter</class> <!-- implements ICustomXMLConverter -->
<messageFormat xmlns="http://schemas.parasoft.com/extensibility-framework/messageFormat">
<defaultMimeType>text/plain</defaultMimeType>
<messageTypes generatorClass="com.myCompany.SchemaGenerator">
<messageType id='unique ID' name='name' xsd='path to schema in jar'/>
. . .
</messageTypes>
<client icon="myClient.gif" defaultTransport='default transport' />
<responder icon="myResponder.gif" />
</messageFormat>
<version id='your version ID' updaterClass="com.myCompany.myUpdater"/>
<form xmlns="urn:com/parasoft/extensibility-framework/gui">
<section label="field group 1">
<field id="key 1" label="field 1"/>
<field id="key 2" label="field 2"/>
</section>
<section label="field group 2">
<field id="key 3" label="field 3"/>
. . .
</section>
. . .
</form>
</extension> |
section 要素の下の field id は、 ICustomXMLConverterConfiguration インスタンスから、さまざまな API メソッドに渡された値を読み出すために使われます。そしてユーザーによって提供された値が、ユーザーの実装に渡されることを許可します。 それらはまた、保存されるときに、レスポンダー デプロイメント記述子ファイルにユーザーが提供する値を維持するために使用されます。GUI に表示される field label はこの XML に基づいて構成されます。セクション レイアウトはプログラムに影響を及ぼしません。エンドユーザーが使用しやすいように、さまざまな GUI フィールドをセクションまたはカテゴリに整理します。
拡張子の名前とともに、ICustomXMLConverter を実装するクラスの完全修飾クラス名は、クライアントで使用されるメッセージ形式を識別するために使用されます。.tst またじゃ .pva ファイルの保存後に、修飾されたクラス名または拡張の名前を変更すると、クライアントが使用しているメッセージ形式を解決できない結果となります。
<MessageFormat> 要素
この要素は、この拡張タイプに固有のものです。インポートされるユーザーのカスタム メッセージ形式に、有効かつ正確である必要があります。
- <defaultMimeType>: ユーザーのメッセージ形式のデフォルト MIME タイプを指定します。MIME タイプは、メッセージが含む情報のタイプを識別するために使用されます。デフォルトの MIME タイプは、メッセージを送信するときにメッセージ ヘッダーで Content Type として使用されます。
- <messageTypes>: 指定のメッセージ タイプのセットを定義するオプション要素です。messageTypes 要素が提供されない場合、ネイティブ形式と XML 間の特定のメッセージタイプを定義しない一般変換を定義します。このような形式の例としては、 CSV があります。
- generatorClass - ISchemaGenerator を実装するクラスの完全修飾名を持つオプション属性です。
- <messageType>: ユーザーのカスタム メッセージ形式のメッセージ タイプを定義します。
id - ユーザーのメッセージ タイプの文字列識別子です。ひとつのメッセージ形式中で一意である必要があります。 クライアント/レスポンダーを保存するときにも使用されるので、変更すると保存されたクライアントが使用しているメッセージ タイプを解決できなくなります。
- name - GUI にユーザーが使用しているメッセージ タイプを表示するのに使用されます。
- xsd - xsd への URL パスです。この属性はジェネレーター クラスを提供しない場合に必要です。その他の場合は無視されます。
- <responder>: ユーザーのカスタム メッセージ形式のために生成されたカスタム Virtualize レスポンダーの基本情報を持つオプション要素です。
- icon - カスタム Virtualize レスポンダーの GUI に表示するアイコンを指定するオプション属性です。これは JAR ファイルまたは Virtualize クラスパス上の Java プロジェクト内に含まれるアイコンへの相対パスです。提供されない場合、 Virtualize はカスタム Virtualize レスポンダーにデフォルトのツール アイコンを使用します。
新しいメッセージ形式の検証
プロジェクトをビルドし ( 拡張機能の追加: 基本手順 (Virtualize)) Virtualize を再起動します。
- [新規追加] > [テスト] または [レスポンダー] を選択して、ユーザーのメッセージ形式の名前を含む新しいクライアント/レスポンダーを .tst または .pva ファイルに追加できることを検証します。
ユーザーの新しいフォーマットは XML Converter のドロップダウン メニューにも表示されます。
ヒント
parasoft-extension.xml に定義される GUI フィールドは、カスタム メッセージ形式 client/responder の [変換オプション] タブに表示されます。
- 拡張 GUI で提供される値は、 名前 - 値の文字列マップとして保存されます。結果として、 parasoft-extension.xml の form 要素内のフィールドを再編しても、ユーザー値の保存方法に影響ありません。しかしながら、ID を変更するとこれに影響します。ID は値の保存やロードに使用されるため、一意である必要があります。ID を変更すると、その前に保存した構成が以前の値をロードせず、値は空白となります。この場合、Version Updater を使用して、古い ID で保存された古い設定を新しい ID のセットへ移行できます。
- カスタム フォーム GUI では、文字列の GUI フィールドだけがサポートされます。ユーザーの拡張が整数やその他のタイプを必要とする場合、拡張の実装で文字列のコンテンツを任意の型に変換できます。
- テーブルやリストは、文字列フィールドでカンマ区切りの値として実装できます。