ユーザー定義の規則
Migration Toolkit for Application Binaries では、ユーザーのアプリケーションのマイグレーションに固有のシナリオを検出するためにユーザー定義の分析規則を使用できます。 ユーザー定義の規則は、XML ファイルで記述されます。 規則ファイルは、XML リスト・ファイルでグループ化され、その後 --userRuleLocation パラメーターを使用して指定されます。 --userRuleLocation パラメーターは、規則リスト XML ファイルが含まれているディレクトリーの絶対パスまたは相対パスです。
Migration Toolkit for Application Binaries では、ツール内で事前に記述された規則を使用しないで、ユーザー定義の分析規則のみを、実行される規則にすることができます。 これを行うには、コマンドで --userRulesOnly パラメーターを使用します。 このパラメーターは、--userRuleLocation とともに使用する必要があります。
各 XML 規則は、id 属性および description 属性が含まれた <rule> エレメントで開始する必要があります。 id は、すべての規則で固有でなければなりません。 規則の id は userDefined_ で開始することをお勧めします。 規則の id が userDefined_ で開始していない場合は、組み込みの規則との競合が生じないように、バイナリー・スキャナーによって接頭部が id に追加されます。 <rule> エレメントには、ちょうど 1 つの子エレメントが含まれている必要があります。 ルールで複数の一致基準を結合する必要がある場合は、 <and> エレメントと <or> エレメントを使用する必要があります。 複数の一致基準を結合するときに使用されるロジックは、これらの各エレメントの名前と整合していることに注意してください。 <or> エレメントを使用すると、ネストされた規則のいずれかにフラグが立てられると、規則全体にフラグが立てられます。 <and> エレメントを使用すると、規則全体にフラグを立てるために、ネストされたすべての規則にフラグを立てる必要があります。 ルールは、ネストされた <and> および <or> エレメントの複数レベルで定義できます。 以下のような規則のスキーマが <rule> エレメントに含まれている必要があります。
xmlns="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule binary-scanner-rule_1_0.xsd"例えば、以下の規則は、 javax.ws.rs.core パッケージと、 javax.ws.rs.ext パッケージまたは application/json ストリング・リテラルのいずれかを含むアプリケーションにフラグを立てます。 ストリング・リテラルの結果はレポートの結果リストに含まれず、規則にはアーカイブごとに 1 回だけフラグが立てられます。
<rule xmlns="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule binary-scanner-rule_1_0.xsd" id="userDefined_MyExampleRule" description="This is my example rule">
<and>
<detectPackage names="javax.ws.rs.core" flagOnce="true"/>
<or flagOnce="true">
<detectPackage names="javax.ws.rs.ext"/>
<detectStringLiteral hideResult="true">
<literal value="application/json"/>
</detectStringLiteral>
</or>
</and>
</rule>
Migration Toolkit for Application Binaries でサポートされる規則のタイプは、以下のとおりです。
- アノテーション検出 (detectAnnotation)
- 属性検出 (detectAttribute)
- クラス検出 (detectClass)
- コンストラクター検出 (detectConstructor)
- コンストラクター・パラメーター検出 (detectConstructorParameter)
- DTD 検出 (detectDTD)
- エレメント検出 (detectElement)
- 列挙またはフィールドの検出 (detectEnumOrField)
- ファイル検出 (detectFile)
- HTML action タグ検出 (detectHtmlActionTag)
- JSP タグ・ライブラリー検出 (detectJspTaglib)
- マニフェスト属性検出 (detectManifestAttribute)
- メソッド検出 (detectMethod)
- メソッド・パラメーター検出 (detectMethodParameter)
- パッケージ検出 (detectPackage)
- プロパティー検出 (detectProperty)
- ストリング・リテラル検出 (detectStringLiteral)
ユーザー定義の各 XML 規則では、フラグを立てる問題を記述するために一緒に記述された HTML ヘルプ・ファイルを持つことができます。 このような HTML ヘルプ・ファイルには、IBM のレポート・ライターで適切に処理するための以下の特定の要件があります。
- すべての表示可能なコンテンツには、<body> 内の <div> の内側に <p> が含まれている必要がある。
- コンテンツの開始が最初の <p> でインデックス付けされ、最後が <body> 内の最後の <div> でインデックス付けされている。
- ヘッダーは、 <span class="SubHeader"> 内の <div> の先頭行にあります。
<body><div>
<span class="SubHeader">Rule Name</span>
<p>Information about</p>
<p>
The rule can be written
</p>
<ul>
<li>here</li>
<li>here</li>
<li>and here</li>
</ul>
</div></body>
規則は、リスト内でカテゴリーによってグループ化されます。 リスト内で、レポートに組み込む HTML ヘルプのパス、重大度、開発コストなど、規則の追加情報を指定することもできます。 規則のリストは、<rules> エレメントで開始する必要があります。 <rules> エレメントには mainCategory が含まれている必要があり、secondaryCategory を指定してリストに含まれている規則のカテゴリーを記述することができます。 このようなカテゴリーは、分析レポートで規則をグループ化するために使用されます。 <rules> エレメントには、規則 XML ファイルに関する追加情報を指定して提供する 1 つ以上の子 <rule> エレメントを含めることができます。 <rule> エレメントには以下の属性を含めることができます。
- fileName - 規則の定義が含まれている XML ファイルの相対パスまたは絶対パスを定義するストリング属性。 この属性は必須です。
- help - 規則にフラグが立てられた場合にレポートに含める規則のヘルプが入っている HTML ファイルの相対パスまたは絶対パスを定義するストリング属性。 HTML ファイル内のコンテンツは、<body> エレメント内に含まれている必要があります。 この属性はオプションです。
- severity - 規則の重大度を定義する列挙。 サポートされる値は、severe、warning、および info です。 この属性はオプションです。
- devCost - この規則でフラグが立てられたマイグレーション・シナリオの解決にかかる基本開発コスト (日数) を定義する浮動小数点数値。 これは、規則を修正するための 1 回のコストです。 この情報は、JSON レポートおよび Transformation Advisor で使用可能です。 この値を instanceCost とともに使用して、Transformation Advisor でこの規則の開発コストが計算されます。 この属性はオプションであり、デフォルトは 0 です。
- instanceCost - 検出されたこの規則の各インスタンスの解決にかかる開発コスト (日数) を定義する浮動小数点数値。 この情報は、JSON レポートおよび Transformation Advisor で使用可能です。 この値を devCost とともに使用して、Transformation Advisor でこの規則の開発コストが計算されます。 この属性はオプションであり、デフォルトは 0 です。
- complexity - この規則にフラグを立てるアプリケーションのマイグレーションに関連した複雑さを定義する列挙。 サポートされる値は、simple、moderate、および complex です。 この情報は、JSON レポートおよび Transformation Advisor で使用可能です。 この属性はオプションです。
- recipes -この規則にフラグを立てるアプリケーションのマイグレーションに関連する OpenRewrite リポジトリーに用意されているレシピのリスト。 複数の値がリストに追加されると、最初のレシピが選択されます。 この属性はオプションです。
以下のような規則リストのスキーマが <rules> エレメントに含まれている必要があります。
xmlns="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list binary-scanner-rule-list_1_0.xsd"例：
<rules xmlns="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list binary-scanner-rule-list_1_0.xsd" mainCategory="Primary rule category" secondaryCategory="Secondary rule category">
<rule fileName="detectDeprecatedMethod.xml" help="/rulehelp/detectFindMethod.html" severity="warning" devCost="0.5" instanceCost="0.1"/>
<rule fileName="detectOldLibrary.xml" help="/rulehelp/detectOldLibrary.html" severity="severe" devCost="5" complexity="complex" />
</rules>
規則の開発を簡単にするために、規則の XML ファイルと規則リストの XML ファイルの両方のスキーマ・ファイルが、wamt/user-rules ディレクトリーに配置されます。 規則を記述する際に検証を受ける (ご使用の統合開発環境 (IDE) でサポートされている場合) ためにファイル・パスを指定するには、schemaLocation 属性でスキーマ・ファイルの場所を更新します。 これは必須ではありませんが、規則の記述時にエラーを捕捉しやすくなります。
例えば、規則ファイルが wamt ディレクトリー内のディレクトリーにある場合、以下のようにします。
xmlns="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://websphere.ibm.com/xml/ns/wamt/binary-scanner-rule-list ../user-rules/binary-scanner-rule-list_1_0.xsd"