ルール開発ガイド
カスタムルールを作成して移行範囲を強化する
概要
多様性を受け入れるオープンソースの強化
Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。まずは、マスター (master)、スレーブ (slave)、ブラックリスト (blacklist)、ホワイトリスト (whitelist) の 4 つの用語の置き換えから始めます。この取り組みは膨大な作業を要するため、用語の置き換えは、今後の複数のリリースにわたって段階的に実施されます。詳細は、Red Hat CTO である Chris Wright のメッセージ をご覧ください。
第1章 はじめに
1.1. ルール開発ガイドの概要
このガイドは、Migration Toolkit for Applications (MTA) ツール用の YAML ベースのカスタムルールを作成する必要があるソフトウェアエンジニアを対象としています。
概要は Migration Toolkit for Applications の概要 を、詳細は CLI ガイド を参照してください。
1.1.1. このガイドでの <MTA_HOME>
の使用
このガイドでは、置き換え可能な変数 <MTA_HOME>
を使用して、MTA インストールへのパスを示します。
mta-7.2.0-cli<OS>.zip* からは、mta-cli
という名前の 1 つのバイナリーが展開されます。
このガイドで <MTA_HOME>
が出てきた場合は、MTA インストールへの実際のパスに置き換えます。
1.2. MTA のルール
Migration Toolkit for Applications (MTA) には、ルールベースの移行ツール (アナライザー) が含まれています。このツールを使用すると、移行予定のアプリケーションで使用されているアプリケーションユーザーインターフェイス (API)、テクノロジー、およびアーキテクチャーを分析できます。MTA アナライザーのルールでは、次のルールパターンが使用されます。
when(condition) message(message) tag(tags)
MTA ルールを内部的に使用して、次のタスクを実行できます。
- アーカイブからファイルを抽出する。
- ファイルを逆コンパイルする。
- ファイルの種類をスキャンして分類する。
- XML およびその他のファイルコンテンツを分析する。
- アプリケーションコードを分析する。
- レポートを作成する。
MTA は、ルールの実行結果に基づいてデータモデルを構築し、コンポーネントのデータと関係をグラフデータベースに保存します。このデータベースは、レポートのために、移行ルールによって必要に応じて照会および更新されます。
独自のカスタムアナライザールールを作成できます。カスタムルールを使用すると、用意されている標準移行ルールの対象外であるカスタムライブラリーなどのコンポーネントの使用を識別できます。
第2章 YAML ルールを作成する
各アナライザールールは、ソースコードを解析し、移行時に問題となる問題を検出するために使用される、一連の命令です。
アナライザーはユーザーが指定したルールを解析し、それをアプリケーションのソースコードに適用し、一致したルールの問題を生成します。ルールセットは、1 つ以上のルールが集合して形成されます。ルールセットを作成することで、共通の目標を達成する複数のルールを編成できます。アナライザー CLI は、ルールセットを入力引数として受け取ります。
2.1. YAML ルールの構造と構文
MTA ルールは YAML で記述されます。各ルールはメタデータ、条件、およびアクションで構成され、アナライザーに対して、指定した条件が一致する場合に指定したアクションを実行するように指示します。
MTA の YAML ルールファイルには、1 つ以上の YAML ルールが含まれています。
2.1.1. ルールのメタデータ
ルールのメタデータには、ルールに関する一般情報が含まれています。メタデータの構造は次のとおりです。
ruleId: "unique_id" 1 labels: 2 # key=value pair - "label1=val1" # valid label with value omitted - "label2" # valid label with empty value - "label3=" # subdomain prefixed key - "konveyor.io/label1=val1" effort: 1 3 category: mandatory 4
2.1.1.1. ルールのラベル
ラベルは、ルールまたはルールセット、および依存関係に対して指定された key=val
のペアです。依存関係の場合、プロバイダーは依存関係を取得する際にラベルを依存関係に追加します。ルールセットのラベルは、それに属するすべてのルールに自動的に継承されます。
ラベル形式
ラベルは key=val
形式の文字列のリストとして、labels
フィールドの下に次のように指定されます。
labels: - "key1=val1" - "key2=val2"
ラベルのキーにはサブドメインの接頭辞を付けることができます。
labels: - "konveyor.io/key1=val1"
ラベルの値は空にすることもできます。
labels: - "konveyor.io/key="
ラベルの値は省略できます。その場合は空の値として処理されます。
labels: - "konveyor.io/key"
予約済みラベル
アナライザーは、次のように特別な意味を持ついくつかのラベルを定義します。
-
konveyor.io/source
: ルールまたはルールセットが適用されるソーステクノロジーを識別します。 -
konveyor.io/target
: ルールまたはルールセットが適用されるターゲットテクノロジーを識別します。
ラベルセレクター
アナライザー CLI は、オプションとして --label-selector
フィールドを使用します。これは、論理演算 AND、OR、NOT をサポートする文字列式です。これを使用して、ラベルに基づきルールをフィルターインまたはフィルターアウトできます。
例:
キーが
konveyor.io/source
、値がeap6
のラベルを持つすべてのルールをフィルターインするには、次のようにします。--label-selector="konveyor.io/source=eap6"
konveyor.io/source
キーと任意の値のラベルを持つすべてのルールをフィルターインするには、次のようにします。--label-selector="konveyor.io/source"
複数のルールの一致に対して
&&
演算子を使用して論理 AND 演算を実行するには、次のようにします。--label-selector="key1=val1 && key2"
複数のルールの一致に対して
||
演算子を使用して論理 OR 演算を実行するには、次のようにします。--label-selector="key1=val1 || key2"
!
演算子を使用して NOT 演算を実行し、key1=val1
ラベルが設定されているルールをフィルターアウトするには、次のようにします。--label-selector="!key1=val1"
部分式をグループ化し、AND を使用して優先順位を制御するには、次のようにします。
--label-selector="(key1=val1 || key2=val2) && !val3"
依存関係ラベル
アナライザーエンジンは、依存関係にラベルを追加します。このラベルは、プログラミング言語や依存関係がオープンソースか内部依存かなど、依存関係に関する追加情報を提供します。
現在、アナライザーは次のラベルを依存関係に追加します。
labels: - konveyor.io/dep-source=internal - konveyor.io/language=java
依存関係ラベルセレクター
アナライザー CLI は --dep-label-selector
オプションを受け入れます。これにより、依存関係から生成されたインシデントを、ラベルに基づきフィルターインまたはフィルターアウトできます。
たとえばアナライザーは、依存関係が既知のオープンソース依存関係であるかどうかを示す値を持つ konveyor.io/dep-source
ラベルを依存関係に追加します。
このようなオープンソース依存関係のインシデントをすべて除外するには、次のように --dep-label-selector
を使用します。
konveyor-analyzer … --dep-label-selector !konveyor.io/dep-source=open-source
アナライザーの Java プロバイダーは、パッケージのリストに除外ラベルを追加することもできます。このようなパッケージをすべて除外するには、次のように --dep-label-selector
と !
演算子を使用します。
konveyor-analyzer … --dep-label-selector !konveyor.io/exclude
2.1.1.2. ルールのカテゴリー
mandatory
- 移行を成功させるには問題を解決する必要があります。解決しない場合、結果として得られるアプリケーションは正常にビルドまたは実行されません。このような問題の例としては、ターゲットプラットフォームでサポートされていないプロプライエタリー API があります。
optional
- 問題を解決しない場合、アプリケーションは正常に動作するはずですが、最適な結果にはならない可能性があります。移行時に変更しない場合は、移行完了後すぐに変更するようスケジュールする必要があります。このような問題の例としては、EJB 2.x コードが EJB 3 にアップグレードされていない場合が挙げられます。
potential
- 移行プロセス中に問題を調べる必要がありますが、移行を成功させるために問題の解決が必須かどうかを判断するのに十分な情報がありません。このような問題の例としては、ターゲットプラットフォームに直接互換性のある型がない場合に、サードパーティー独自の型を移行する場合が挙げられます。
2.1.1.3. ルールアクション
ルールには、message と tag の 2 種類のアクションを含めることができます。各ルールには、いずれか一方または両方が含まれます。
メッセージアクション
メッセージアクションは、ルールが一致した場合にメッセージに関する問題を作成します。メッセージでは、プロバイダーによってエクスポートされたカスタムデータも使用できます。
message: "helpful message about the issue"
以下に例を示します。
- ruleID: test-rule when: <CONDITION> message: Test rule matched. Please resolve this migration issue.
オプションで、問題に関する関連情報や簡単な修正を提供する外部 URL へのハイパーリンクをメッセージに含めることができます。
links: - url: "konveyor.io" title: "Short title for the link"
メッセージは、ルールのカスタム変数を通じて挿入される、一致に関する情報を含めるテンプレートにすることもできます。
タグアクション
タグアクションは、一致が見つかった場合にアプリケーション用に 1 つ以上のタグを生成するようにアナライザーに指示します。tag
フィールドの各文字列は、タグのコンマ区切りリストにできます。オプションで、タグにカテゴリーを割り当てることができます。
tag: - "tag1,tag2,tag3" - "Category=tag4,tag5"
例:
- ruleID: test-rule when: <CONDITION> tag: - Language=Golang - Env=production - Source Code
タグは、文字列または key=val
ペアにすることができ、キーは MTA のタグカテゴリーとして処理されます。このドキュメントでは、タグアクションを持つルールは「タグ付けルール」と呼ばれます。
タグアクションしか持たないルールに対しては問題が作成されない点に注意してください。
2.1.1.4. ルール条件
各ルールには、MTA が特定のアクションを実行するために満たす必要のある条件を指定する when
ブロックがあります。
when
ブロックには 1 つの条件が含まれますが、その条件の下に複数の条件をネストできます。
when: <condition> <nested-condition>
MTA は、provider
、and
、or
の 3 種類の条件をサポートします。
2.1.1.4.1. プロバイダー条件
アプリケーションアナライザーは、アプリケーションの構築に使用されているプログラミング言語、フレームワーク、およびツールを検出し、それに応じて Language Server Protocol (LSP) を使用して、サポートされている各プロバイダーのデフォルトのルールセットを生成します。サポートされている各プロバイダーは、デフォルトで定義済みのルールセットを持ち、個別のコンテナーで独立して実行されます。
MTA は多言語ソースコード分析をサポートします。ソースコード内の特定の言語の検索は、provider
条件を使用して有効にします。この条件は、特定の言語プロバイダーの検索クエリーを定義します。provider
条件では、コードの分析に使用するプロバイダーの "ケイパビリティー" も指定します。
provider
条件の形式は <provider_name>.<capability>
です。
when: <provider_name>.<capability> <input_fields>
アナライザーは現在、次の provider
条件をサポートしています。
-
builtin
-
java
-
Go
-
dotnet
CLI で複数のアプリケーションを分析するときに 1 つのレポートを提供するためのサポートは、テクノロジープレビュー機能です。テクノロジープレビュー機能は、Red Hat 製品のサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではないことがあります。Red Hat は、実稼働環境でこれらを使用することを推奨していません。テクノロジープレビュー機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。
Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲 を参照してください。
プロバイダールールの条件 | プロバイダー名 |
---|---|
完全にサポートされ、製品に含まれているプロバイダー | Java |
製品内ですでにルールが定義されているプロバイダー | .NET |
分析にカスタムルールセットを必要とするプロバイダー |
|
2.1.1.4.1.1. builtin
プロバイダー
builtin
は、エンジンによって生成されたさまざまなファイルと内部メタデータを分析できる内部プロバイダーです。
このプロバイダーには次のケイパビリティーがあります。
-
file
-
filecontent
-
xml
-
json
-
hasTags
file
file
ケイパビリティーを使用すると、プロバイダーは指定されたパターンに一致するソースコード内のファイルを検索できます。
when: builtin.file: pattern: "<regex_to_match_filenames>"
filecontent
filecontent
ケイパビリティーを使用すると、プロバイダーは指定されたパターンに一致するコンテンツを検索できます。
when: builtin.filecontent: filePattern: "<regex_to_match_filenames_to_scope_search>" pattern: "<regex_to_match_content_in_the_matching_files>"
xml
xml
ケイパビリティーを使用すると、プロバイダーは指定された XML ファイルのリストに対して XPath 式のクエリーを実行できます。このケイパビリティーでは、xpath
と filepaths
という 2 つの入力パラメーターを使用できます。
when: builtin.xml: xpath: "<xpath_expressions>" 1 filepaths: 2 - "/src/file1.xml" - "/src/file2.xml"
json
json
ケイパビリティーを使用すると、プロバイダーは指定された JSON ファイルのリストに対して XPath 式のクエリーを実行できます。現在、json
は XPath のみを入力として受け取り、コードベース内のすべての JSON ファイルに対して検索を実行します。
when:
builtin.json:
xpath: "<xpath_expressions>" 1
- 1
xpath
は、有効な XPath 式である必要があります。
hasTags
hasTags
ケイパビリティーを使用すると、プロバイダーはアプリケーションタグをクエリーできます。内部データ構造をクエリーして、アプリケーションに指定されたタグがあるかどうかを確認します。
when:
# when more than one tag is given, a logical AND is implied
hasTags: 1
- "tag1"
- "tag2"
- 1
- 複数のタグが指定されている場合は、論理積が暗黙的に指定されます。
2.1.1.4.1.2. java
プロバイダー
java
プロバイダーは、Java ソースコードを分析します。
このプロバイダーには次のケイパビリティーがあります。
-
referenced
-
dependency
referenced
referenced
ケイパビリティーを使用すると、プロバイダーはソースコード内の参照を見つけることができます。この機能には、pattern
、location
、annotated
という 3 つの入力パラメーターを使用できます。
when: java.referenced: pattern: "<pattern>" 1 location: "<location>" 2 annotated: "<annotated>" 3
次の場所がサポートされています。
-
CONSTRUCTOR_CALL
-
TYPE
-
INHERITANCE
-
METHOD_CALL
-
ANNOTATION
-
IMPLEMENTS_TYPE
-
ENUM_CONSTANT
-
RETURN_TYPE
-
IMPORT
-
VARIABLE_DECLARATION
-
FIELD
-
METHOD
dependency
dependency
ケイパビリティーを使用すると、プロバイダーは指定されたアプリケーションの依存関係を見つけることができます。MTA は、アプリケーションの依存関係のリストを生成します。このケイパビリティーを使用してリストをクエリーし、依存関係バージョンの指定された範囲内でアプリケーションに特定の依存関係が存在するかどうかを確認できます。
when: java.dependency: name: "<dependency_name>" 1 upperbound: "<version_string>" 2 lowerbound: "<version_string>" 3
2.1.1.4.1.3. go
プロバイダー
go
プロバイダーは、Go ソースコードを分析します。このプロバイダーのケイパビリティーは、referenced
と dependency
です。
referenced
referenced
ケイパビリティーを使用すると、プロバイダーはソースコード内の参照を見つけることができます。
when: go.referenced: "<regex_to_find_reference>"
dependency
dependency
ケイパビリティーを使用すると、プロバイダーはアプリケーションの依存関係を検索できます。
when: go.dependency: name: "<dependency_name>" 1 upperbound: "<version_string>" 2 lowerbound: "<version_string>" 3
2.1.1.4.1.4. dotnet
プロバイダー
dotnet
は、.NET および C# ソースコードを分析するために使用される外部プロバイダーです。現在、このプロバイダーは referenced
機能をサポートしています。
referenced
referenced
ケイパビリティーを使用すると、プロバイダーはソースコード内の参照を見つけることができます。
when: dotnet.referenced: pattern: "<pattern>" 1 namespace: "<namespace>" 2
2.1.1.4.2. カスタム変数
プロバイダー条件には、カスタム変数を関連付けることができます。カスタム変数を使用すると、ソースコード内の一致する行から関連情報を取得できます。これらの変数の値には、ソースコード内で一致するデータが挿入されます。これらの値を使用して、ルールのアクションで詳細なテンプレート化されたメッセージを生成できます (メッセージアクション を参照)。これらは、customVariables
フィールドのルールに追加できます。
- ruleID: lang-ref-004 customVariables: - pattern: '([A-z]+)\.get\(\)' 1 name: VariableName 2 message: "Found generic call - {{ VariableName }}" 3 when: java.referenced: location: METHOD_CALL pattern: com.example.apps.GenericClass.get
2.1.1.5. 論理条件
アナライザーには、and
と or
の 2 つの基本的な論理条件があります。これらを使用して、他の条件の結果を集計し、より複雑なクエリーを作成できます。
2.1.1.5.1. and
条件
and
条件は、条件の配列の結果に対して論理 AND 演算を実行します。and
条件は、その子条件が すべて 一致する場合に一致します。
when: and: - <condition1> - <condition2>
例:
when: and: - java.dependency: name: junit.junit upperbound: 4.12.2 lowerbound: 4.4.0 - java.referenced: location: IMPORT pattern: junit.junit
条件は、他の条件内でネストすることもできます。
例:
when: and: - and: - go.referenced: "*CustomResourceDefinition*" - java.referenced: pattern: "*CustomResourceDefinition*" - go.referenced: "*CustomResourceDefinition*"
2.1.1.5.2. or
条件
or
条件は、条件の配列の結果に対して論理 OR 演算を実行します。or
条件は、その子条件の いずれか が一致する場合に一致します。
when: or: - <condition1> - <condition2>
例:
when: or: - java.dependency: name: junit.junit upperbound: 4.12.2 lowerbound: 4.4.0 - java.referenced: location: IMPORT pattern: junit.junit
2.1.2. ルールセット
ルールセットは、一連のルールで形成されます。MTA では、ルールファイルが必ずルールセットに属する必要はありません。しかし、ルールセットを使用することで、共通の目標を達成する複数のルールをグループ化し、そのルールをルールエンジンに渡すことができます。
ルールセットを作成するには、1 つ以上の YAML ルールをディレクトリーに配置し、そのディレクトリールートに ruleset.yaml
ファイルを作成します。このディレクトリーを、--rules
オプションを使用して MTA CLI への入力として渡すと、このディレクトリー内のすべてのルールは、ruleset.yaml
ファイルで定義されたルールセットの一部として処理されます。
ruleset.yaml
ファイルには、ルールセットのメタデータが保存されます。
name: "Name of the ruleset" 1 description: "Description of the ruleset" labels: 2 - key=val
アプリケーション分析を実行するには、次のコマンドを実行します。<application_to_analyze> をアプリケーションに、<output_dir> を任意のディレクトリーに、<custom_rule_dir> をカスタムルールセットファイルに置き換えます。
$ mta-cli analyze --input=<application_to_analyze> --output=<output_dir> --rules=<custom_rule_dir> --enable-default-rulesets=false
mta-cli ツールは、まず分析に必要なアプリケーションの種類と対応するプロバイダーを決定します。次に、必要な依存関係とツールを持つコンテナー内でプロバイダーを起動します。最後に、プロバイダーがアナライザーを使用して一連のルールセットを実行し、ソースコードを分析します。
2.2. 基本的な YAML ルールを作成する
このセクションでは、基本的な MTA YAML ルールを作成する方法を説明します。これは、すでに MTA がインストールされていることを前提としています。インストール手順は、MTA CLI ガイド を参照してください。
2.2.1. 基本的な YAML ルールのテンプレートを作成する
MTA YAML ベースのルールの基本構造は、以下のとおりです。
when(condition) message(message) tag(tags)
手順
以下のように、
/home/<USER>/
ディレクトリーに YAML ルールの基本構文を含むファイルを作成します。- category: mandatory description: | <DESCRIPTION TITLE> <DESCRIPTION TEXT> effort: <EFFORT> labels: - konveyor.io/source=<SOURCE_TECH> - konveyor.io/target=<TARGET_TECH> links: - url: <HYPERLINK> title: <HYPERLINK_TITLE> message: <MESSAGE> tag: - <TAG1> - <TAG2> ruleID: <RULE_ID> when: <CONDITIONS>
2.2.2. 基本的な YAML ルールセットのテンプレートを作成する
複数の同じようなルールをグループ化する場合は、それらのファイルをディレクトリーに配置し、そのディレクトリーのルートに ruleset.yaml
ファイルを作成することで、それらのルールセットを作成できます。このディレクトリーを、--rules
オプションを使用して MTA CLI への入力として渡すと、MTA はディレクトリー内のすべてのファイルを ruleset.yaml
ファイルで定義されたルールセットに属するものとして処理します。
2.2.3. YAML ルールを作成する
各ルールファイルには、1 つ以上の YAML ルールが含まれます。すべてのルールはメタデータ、条件、アクションで構成されています。
手順
when
条件を作成します。YAML ルールの
when
条件には、provider
、and
、or
を指定できます。provider
条件を作成するプロバイダー条件は、特定の言語プロバイダーの検索クエリーを定義し、プロバイダーの特定のケイパビリティーを呼び出すために使用されます。
条件の一般的な形式は
<provider_name>.<capability>
です。条件には、検索の詳細を指定するための内部フィールドもあります。provider
条件とその内部フィールドを作成する方法は、使用するプロバイダーと呼び出すケイパビリティーによって異なります。以下の表は、利用可能なプロバイダーとそのケイパビリティーを示しています。作成するルールの目的に合ったプロバイダーとケイパビリティーを選択してください。条件のこの部分には、条件のフィールドはまだ含まれていません。
プロバイダー 機能 説明 java
referenced
詳細な検索の場合は、オプションのコード位置を指定して、アノテーションを含むパターンの参照を検索します。
dependency
アプリケーションに指定された依存関係があるか確認します。
builtin
xml
XPath クエリーを使用して XML ファイルを検索します。
json
JSONPath クエリーを使用して JSON ファイルを検索します。
filecontent
RegEx パターンを使用して、通常のファイル内のコンテンツを検索します。
file
指定されたパターンに一致する名前を持つファイルを検索します。
hasTags
タグ付けルールを通じてアプリケーション用にタグが作成されているか確認します。
Go
referenced
パターンの参照を検索します。
dependency
アプリケーションに指定された依存関係があるか確認します。
以下の例は、
referenced
ケイパビリティーを使用するjava
プロバイダー条件を示しています。例:
when: java.referenced:
適切なフィールドを
provider
条件に追加します。以下の表は、利用可能なプロバイダー、そのケイパビリティー、フィールドをすべて示しています。選択したプロバイダーとケイパビリティーに属するフィールドを選択してください。一部のフィールドは必須であることに注意してください。
プロバイダー 機能 Field 必須 ? 説明 java
referenced
pattern
はい
RegEx パターン
location
いいえ
ソースコードの場所。サポートされているすべての検索場所のリストは、以下を参照してください。
annotated
いいえ
アノテーションとその要素 (名前と値)
dependency
name
はい
依存関係の名前
nameregex
いいえ
名前と一致する RegEx
upperbound
いいえ
一致するバージョン番号の下限
lowerbound
いいえ
一致するバージョン番号の上限
builtin
xml
xpath
はい
XPath クエリー
namespace
いいえ
クエリーの範囲を名前空間に絞るためのマップ
filepaths
いいえ
検索範囲を絞るためのオプションのファイルリスト
json
xpath
はい
XPath クエリー
filepaths
いいえ
検索範囲を絞るためのオプションのファイルリスト
filecontent
pattern
はい
コンテンツ内で一致する RegEx パターン
filePattern
いいえ
このパターンに一致する名前を持つファイル内のみを検索します。
file
pattern
はい
このパターンに一致する名前を持つファイルを検索します。
hasTags
文字列タグのインラインリストです。タグ形式の詳細は、ルールアクション の タグアクション を参照してください。
Go
referenced
pattern
はい
RegEx パターン
dependency
name
はい
依存関係の名前
nameregex
いいえ
名前と一致する RegEx
upperbound
いいえ
一致するバージョン番号の下限
lowerbound
いいえ
一致するバージョン番号の上限
次の検索場所を使用して、
java
検索の範囲を絞ることができます。- CONSTRUCTOR_CALL
- TYPE
- INHERITANCE
- METHOD_CALL
- ANNOTATION
- IMPLEMENTS_TYPE
- ENUM_CONSTANT
- RETURN_TYPE
- IMPORT
VARIABLE_DECLARATION
以下の例は、パッケージの参照を検索するルールの
when
条件を示しています。例:
when: java.referenced: location: PACKAGE pattern: org.jboss.*
AND
またはOR
条件を作成します。and
条件は、その子条件が すべて 一致する場合に一致します。次のように、and
条件を作成します。when: and: - java.dependency: name: junit.junit upperbound: 4.12.2 lowerbound: 4.4.0 - java.referenced: location: IMPORT pattern: junit.junit
or
条件は、その子条件の いずれか が一致する場合に一致します。次のように、or
条件を作成します。when: or: - java.dependency: name: junit.junit upperbound: 4.12.2 lowerbound: 4.4.0 - java.referenced: location: IMPORT pattern: junit.junit
2.2.4. カスタム YAML ルールを使用して分析を実行する
分析を実行するには、CLI で --rules
オプションを使用します。
手順
単一のルールファイル (
/home/<USER>/rule.yaml
) 内のルールを使用するには、次のコマンドを実行します。mta-cli analyze --input /home/<USER>/data/ --output /home/<USER>/output/ --rules /home/<USER>/rule.yaml
ここでは、以下のようになります。
-
/home/<USER>/data/
- ソースコードまたはバイナリーのディレクトリー。 -
/home/<USER>/output/
- レポート (HTML および YAML) のディレクトリー
-
-
複数のルールファイルを使用するには、それらのルールファイルをディレクトリーに配置し、
ruleset.yaml
ファイルを追加する必要があります。その後、ディレクトリーは ルールセット として扱われ、--rules
オプションに入力として渡すことができます。
CLI で --target
または --source
オプションを使用する場合、エンジンはそのターゲットのラベルに一致するルールのみを選択することに注意してください。そのため、ルールにターゲットラベルまたはソースラベルが追加されていることを確認する必要があります。詳細は、予約済みラベル を参照してください。
2.3. 最初の YAML ルールを作成する
このセクションでは、最初の MTA YAML ベースのルールを作成してテストするプロセスを説明します。これは、すでに MTA がインストールされていることを前提としています。インストール手順は、CLI ガイド の CLI のインストールと実行 を参照してください。
この例では、アプリケーションが <class-loading>
要素を含む jboss-web.xml
ファイルの定義を行うインスタンスを検出するルールを作成します。また、コードの移行方法を説明するドキュメントへのリンクを提供します。
2.3.1. ルールの YAML ファイルを作成する
- 最初のルール用の YAML ファイルを作成します。
$ mkdir /home/<USER>/rule.yaml
2.3.2. ルールをテストするためのデータの作成
ディレクトリーに、
jboss-web.xml
およびpom.xml
ファイルを作成します。mkdir /home/<USER>/data/ touch /home/<USER>/data/jboss-web.xml touch /home/<USER>/data/pom.xml
作成した
jboss-web.xml
ファイルに、次の内容を貼り付けます。<!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 4.2//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_4_2.dtd"> <jboss-web> <class-loading java2ClassLoadingCompliance="false"> <loader-repository> seam.jboss.org:loader=@projectName@ <loader-repository-config>java2ParentDelegation=false</loader-repository-config> </loader-repository> </class-loading> </jboss-web>
作成した
pom.xml
ファイルに、次の内容を貼り付けます。<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>test</groupId> <artifactId>test</artifactId> <version>1.1.0-SNAPSHOT</version> <properties> <maven.compiler.source>1.7</maven.compiler.source> <maven.compiler.target>1.7</maven.compiler.target> </properties> <dependencies> </dependencies> </project>
2.3.3. ルールの作成
MTA YAML ベースのルールは、以下のルールパターンを使用します。
when(condition) perform(action)
手順
作成した
rule.yaml
ファイルに、次の内容を貼り付けます。- ruleID: <UNIQUE_RULE_ID> 1 description: <DESCRIPTION> 2 when: <CONDITION(S)> 3 message: <MESSAGE> 4 labels: <LABELS> 5 effort: <EFFORT> 6 links: - <LINKS> 7
- 1
- ルールの一意の ID。たとえば、
jboss5-web-class-loading
です。 - 2
- ルールの文字での説明。
- 3
- 1 つ以上の条件を指定して
when
ブロックを完成させます。-
このルールは XML ファイル内の一致をチェックするため、
builtin
プロバイダーの XML ケイパビリティーを使用します。 jboss-web
の子であるclass-loading
要素を照合するには、XPath 式jboss-web/web-loading
を XML クエリーとして使用します。この場合、必要な条件は 1 つだけです。when: builtin.xml: xpath: jboss-web/class-loading
-
このルールは XML ファイル内の一致をチェックするため、
- 4
- 移行の問題を説明する役立つメッセージ。ルールが一致すると、レポートにメッセージが生成されます。以下に例を示します。
message: The class-loading element is no longer valid in the jboss-web.xml file.
- 5
- ルールの文字列ラベルのリスト。
- 6
- この問題を解決するために予想されるストーリーポイントの数。
- 7
- 検出した移行問題に関するドキュメントを指す 1 つ以上のハイパーリンク。
links: - url: https://access.redhat.com/documentation/ja-JP/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6 title: Create or Modify Files That Control Class Loading in JBoss EAP 6
以上でルールが完成しました。ルールは次のようになります。
- ruleID: jboss5-web-class-loading description: Find class loading element in JBoss XML file. when: builtin.xml: xpath: jboss-web/class-loading message: The class-loading element is no longer valid in the jboss-web.xml file. effort: 3 links: - url: https://access.redhat.com/documentation/ja-JP/JBoss_Enterprise_Application_Platform/6.4/html-single/Migration_Guide/index.html#Create_or_Modify_Files_That_Control_Class_Loading_in_JBoss_Enterprise_Application_Platform_6 title: Create or Modify Files That Control Class Loading in JBoss EAP 6
2.3.4. ルールのインストール
手順
CLI で、作成したルールファイルを指定します。
–rules /home/<USER>/rules.yaml
2.3.5. ルールのテスト
手順
ルールをテストするには、作成したテストデータを入力に指定し、MTA CLI のルールオプションを使用してルールを渡します。
mta-cli analyze --input /home/<USER>/data/ --output /home/<USER>/output/ --rules /home/<USER>/rules.yaml
2.3.6. レポートを確認する
レポートを確認して、予想される結果が表示されることを確認します。
手順
分析が完了すると、コマンドは HTML レポートへのパスを出力します。
INFO[0066] Static report created. Access it at this URL: URL="file:/home/<USER>/output/static-report/index.html"
Web ブラウザーで、
/home/<USER_NAME>/output/static-report/index.html
を開きます。- 左側のメニューの Issues タブに移動します。
ルールが実行されていることを確認します。
-
Issues テーブルの検索バーに
JBoss XML
と入力します。 -
テーブルに、タイトルが
Find class loading element in JBoss XML file
の問題が存在することを確認します。
-
Issues テーブルの検索バーに
- jboss-web.xml リンクをクリックして、影響を受けたファイルを開きます。
付録A 参考資料
A.1. ルールのストーリーポイントについて
A.1.1. ストーリーポイントとは
ストーリーポイント は、アジャイルソフトウェア開発で一般的に使用される抽象メトリックで、機能や変更を実装するのに必要な 作業量 を予測します。
Migration Toolkit for Applications はストーリーポイントを使用して、特定のアプリケーションコンストラクトとアプリケーション全体を移行するために必要な作業のレベルを表現します。必ずしも工数に変換される訳ではありませんが、この値はタスク全体で一貫性を持たせる必要があります。
A.1.2. ルールにおけるストーリーポイントの見積方法
ルールのストーリーポイントの作業レベルを見積もることは複雑です。以下は、ルールに必要な作業レベルを見積もる際に MTA が使用する一般的なガイドラインです。
作業レベル | Story Points | 説明 |
---|---|---|
Information | 0 | 移行の優先度が非常に低いか、優先度のない情報警告。 |
Trivial | 1 | 移行は簡単な変更、または API の変更がないか最小限の変更を伴う単純なライブラリーの交換です。 |
Complex | 3 | 移行タスクに必要な変更は複雑ですが、解決策が文書化されています。 |
Redesign | 5 | 移行タスクでは、API が大幅に変更され、再設計または完全なライブラリーの変更が必要になります。 |
Rearchitecture | 7 | 移行には、コンポーネントまたはサブシステムの完全な再アーカイブが必要です。 |
Unknown | 13 | 移行ソリューションは不明なため、完全な再書き込みが必要になる場合があります。 |
A.1.3. タスクカテゴリー
作業量レベルに加えて、移行タスクを分類してタスクの重大度を示すことができます。次のカテゴリーは、移行作業の優先順位を行えるように、問題をグループ化するために使用されます。
- Mandatory
- 移行を成功させるには、タスクを完了する必要があります。変更が行われないと、生成されるアプリケーションはビルドまたは実行に成功しません。たとえば、ターゲットプラットフォームでサポートされないプロプライエタリー API の置き換え例が含まれます。
- Optional
- 移行タスクが完了しない場合、アプリケーションは動作しますが、結果が最適になるとは限りません。移行時に変更が行われない場合は、移行の完了後すぐにスケジュールに配置することが推奨されます。
- Potential
- 移行プロセス中にタスクを調べる必要があります。しかし、移行を成功させるためにタスクが必須かどうかを判断するのに十分な詳細情報がありません。これの例は、直接互換性のあるタイプがないサードパーティーのプロプライエタリータイプの移行です。
- Information
- タスクは、特定のファイルの存在を通知するために含まれています。これらは、モダナイゼーション作業の一部として検証または変更する必要がある場合がありますが、通常は変更は必要ありません。
A.2. 関連情報
A.2.1. 関連情報
- MTA Jira 問題トラッカー: https://issues.redhat.com/projects/MTA/issues
- MTA メーリングリスト: windup-eng@redhat.com
改訂日時: 2025-01-27