ルール開発ガイド


Migration Toolkit for Applications 7.2

カスタムルールを作成して移行範囲を強化する

Red Hat Customer Content Services

概要

このガイドでは、Migration Toolkit for Applications にカスタム XML ルールを作成する方法を説明します。

多様性を受け入れるオープンソースの強化

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
1
ID は、ルールが属するルールセット内で一意である必要があります。
2
ラベル形式の説明は、以下を参照してください。
3
effort は、この問題を解決するために必要な作業レベルを示す整数値です。
4
category は、移行に関する問題の重大度を示しています。値は mandatoryoptionalpotential のいずれかになります。これらのカテゴリーの説明は、ルールのカテゴリー を参照してください。
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. ルールアクション

ルールには、messagetag の 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 は、providerandor の 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

分析にカスタムルールセットを必要とするプロバイダー

  • Go
  • Python
  • Node.js
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 式のクエリーを実行できます。このケイパビリティーでは、xpathfilepaths という 2 つの入力パラメーターを使用できます。

when:
  builtin.xml:
    xpath: "<xpath_expressions>" 1
    filepaths: 2
      - "/src/file1.xml"
      - "/src/file2.xml"
1
xpath は、有効な XPath 式である必要があります。
2
filepaths は、XPath クエリーを適用するファイルのリストです。

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 ケイパビリティーを使用すると、プロバイダーはソースコード内の参照を見つけることができます。この機能には、patternlocationannotated という 3 つの入力パラメーターを使用できます。

when:
  java.referenced:
    pattern: "<pattern>" 1
    location: "<location>" 2
    annotated: "<annotated>" 3
1
照合する正規表現パターン (例: org.kubernetes.*)。
2
パターンを照合する必要がある正確な場所を指定します (例: IMPORT)。
3
クエリーを使用して、Java コード内の名前や値などの特定のアノテーションとその要素をチェックします。たとえば、次のクエリーはメソッド内の Bean (url = “http://www.example.com”) アノテーションと一致します。
 annotated:
      pattern: org.framework.Bean
      elements:
      - name: url
        value: "http://www.example.com"

次の場所がサポートされています。

  • 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
1
検索する依存関係の名前。
2
依存関係のバージョンの上限。
3
依存関係のバージョンの下限。
2.1.1.4.1.3. go プロバイダー

go プロバイダーは、Go ソースコードを分析します。このプロバイダーのケイパビリティーは、referenceddependency です。

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
1
検索する依存関係の名前。
2
依存関係のバージョンの上限。
3
依存関係のバージョンの下限。
2.1.1.4.1.4. dotnet プロバイダー

dotnet は、.NET および C# ソースコードを分析するために使用される外部プロバイダーです。現在、このプロバイダーは referenced 機能をサポートしています。

referenced

referenced ケイパビリティーを使用すると、プロバイダーはソースコード内の参照を見つけることができます。

when:
  dotnet.referenced:
    pattern: "<pattern>" 1
    namespace: "<namespace>" 2
1
pattern: 目的の参照と照合する正規表現パターン。たとえば、HttpNotFound などです。
2
namespace: 検索する名前空間を指定します。たとえば、System.Web.Mvc などです。
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
1
pattern: 一致が見つかった場合にソースコード行に対して照合する正規表現パターン。
2
name: テンプレートで使用できる変数の名前。
3
message: カスタム変数を使用するメッセージのテンプレート。
2.1.1.5. 論理条件

アナライザーには、andor の 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
1
名前は、指定されたルールセット内で一意である必要があります。
2
ルールセットのラベルは、そのルールセットに属するすべてのルールに継承されます。

アプリケーション分析を実行するには、次のコマンドを実行します。<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)

手順

  1. 以下のように、/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 ファイルで定義されたルールセットに属するものとして処理します。

手順

  1. --rules オプションを使用してディレクトリー全体を渡す場合は、ruleset.yaml ファイルのテンプレートを作成します。

    name: <RULESET_NAME> 1
    description: <RULESET_DESCRIPTION>
    labels: 2
      - key=val
    1
    名前は、指定されたルールセット内で一意である必要があります。
    2
    ルールセットのラベルは、そのルールセットに属するすべてのルールに継承されます。

2.2.3. YAML ルールを作成する

各ルールファイルには、1 つ以上の YAML ルールが含まれます。すべてのルールはメタデータ、条件、アクションで構成されています。

手順

  1. when 条件を作成します。

    YAML ルールの when 条件には、providerandor を指定できます。

    1. 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:
  2. 適切なフィールドを 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.*
  3. 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. ルールをテストするためのデータの作成

  1. ディレクトリーに、jboss-web.xml および pom.xml ファイルを作成します。

    mkdir /home/<USER>/data/
    touch /home/<USER>/data/jboss-web.xml
    touch /home/<USER>/data/pom.xml
  2. 作成した 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>
  3. 作成した 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 ブロックを完成させます。
    1. このルールは XML ファイル内の一致をチェックするため、builtin プロバイダーの XML ケイパビリティーを使用します。
    2. jboss-web の子である class-loading 要素を照合するには、XPath 式 jboss-web/web-loading を XML クエリーとして使用します。この場合、必要な条件は 1 つだけです。

      when:
        builtin.xml:
          xpath: jboss-web/class-loading
    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. レポートを確認する

レポートを確認して、予想される結果が表示されることを確認します。

手順

  1. 分析が完了すると、コマンドは 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 を開きます。

  2. 左側のメニューの Issues タブに移動します。
  3. ルールが実行されていることを確認します。

    1. Issues テーブルの検索バーに JBoss XML と入力します。
    2. テーブルに、タイトルが Find class loading element in JBoss XML file の問題が存在することを確認します。
  4. 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. 関連情報

法律上の通知

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.