プラグインを作ろう！ (9) -- @parameter：パラメータを使う

Mojo も Java オブジェクトなのでフィールドを宣言して使用することが多いと思いますが、そのフィールドの値を外部から設定できるようにしておくと柔軟性が向上します。　Mojo ではこれをパラメータと呼びます。

以下でパラメータの定義や設定の仕方を見ていきます。　ただし、今回はパラメータの型は文字列 (java.lang.String) に限定します。　他の型については次回以降に。　また、mojo のサンプルコードでは、package 宣言や import 文は省略します。

パラメータの定義　「@parameter」

パラメータの定義は簡単です。　private フィールドに JavaDoc アノテーション「@parameter」を付加するだけです：

/** @goal sayhi */
public class HelloMojo extends AbstractMojo{
    
    /** @parameter */
    private String target;
    
    public void execute()throws MojoExecutionException{
        getLog().info("***** Hello, "+this.target+" ! *****");
    }
}

ただし、このままではフィールドの値は「null」となっています。　パラメータに値を設定する方法は概ね以下のような方法があります：

プラグインを使用するプロジェクトの POM ファイルから設定する
@parameter に引数 default-value を付加する
@parameter に引数 expression を付加する
mvn コマンドの実行時に引数として設定する

優先順位は

POM ファイル
mvn コマンドの引数、expression
default-value

です。

通常の Java オブジェクトのように、フィールドの宣言と同時に値を代入する*1ことによって値を設定することも出来ますが、プラグインのドキュメントを生成したりする際に読み込まれないので、この方法は控えた方がよいでしょう。　ちなみに、優先順位は default-value よりも低いです。

以降でそれぞれの方法を見ていきます。

POM ファイルからのパラメータ値の設定

パラメータに設定したい値は、プラグインを使用するプロジェクトによって変更したいのが普通です。　その場合、「/project/build/plugins」要素下に以下のような <plugin> 要素を書きます。

...
<plugin>
  <groupId>org.sample</groupId>
  <artifactId>hello</artifactId>
  <configuration>
    <target>world</target>
  </configuration>
</plugin>
...

パラメータの値を設定しているのは <configuration> 要素下の

<target>world<target>

の部分です。　この例では名前が「target」のパラメータに「world」という値を設定しています。

デフォルト値の設定　「@parameter default-value="..."」

上記のように、プラグインを使用するプロジェクト側で値を設定するのが普通ですが、もし値が設定されなかった場合のために、デフォルト値を設定しておいた方がよいでしょう。　これには、@parameter に引数 default-value を指定します：

/** @goal sayhi */
public class HelloMojo extends AbstractMojo{
    
    /**  @parameter default-value="world" */
    private String target;
    
    public void execute()throws MojoExecutionException{
        getLog().info("***** Hello, "+this.target+" ! *****");
    }
}

アノテーションによるパラメータ値の設定　「@parameter expression="..."」

パラメータに設定したい値を、実行環境やプラグインを使用するプロジェクトの POM ファイルにしたがったものにしたいこともよくあるかと思います。　これを行うためには @parameter に引数 expression を指定します：

/** @goal sayhi */
public class HelloMojo extends AbstractMojo{
    
    /** @parameter expression="${user.name}" */
    private String target;
    
    public void execute()throws MojoExecutionException{
        getLog().info("***** Hello, "+this.target+" ! *****");
    }
}

上記の例では環境変数「user.name」の値をパラメータに設定しています。

また、POM ファイル中の値を設定したい場合、例えば「/project/packaging」要素の子テキストの値を設定したい場合は

/** @parameter expression = ${project.packaging} */

のようにします。

mvn コマンド実行時の引数によるパラメータ値の設定

mvn コマンド実行時に値を設定したい場合は、まず上記の引数 expression の設定が必要です。　ここでは

/** @parameter expression = "${xxx}" */
private String target;

と宣言したとしましょう。

mvn コマンドの実行時にパラメータを指定したい場合は、mvn コマンドの引数として「-D環境変数名=値」という形式の文字列を渡します。　ここで、環境変数名とは、@parameter の引数 expression に指定した文字列のうち、"${" と "}" で囲まれた部分（上記の例では "xxx"）です*2。　具体的にはコマンドは以下のようになります（パラメータに "world" を指定する場合）：