Цель статьи - рассказать об опыте разработки плагина.

Базовые понятия

@Mojo – исполняемый класс maven плагина.
AbstractMojo – базовый абстрактный класс maven .
@Parameter – параметры, которые указываются при вызове плагина.

Простой пример. Плагин для проверки наличия каких либо файлов в проекте

project-file-verifier-maven-plugin – подмодуль, содержащий mojo и логику проверки наличия файла readme.md. Описывает простое взаимодействие плагина с CDI контейнером.

verify-checks – подмодуль выполняющий ряд проверок работы project-file-verifier-maven-plugin для демонстрации.

CDI

Помимо readme.md существуют и другие базовые файлы в проекте которые необходимо валидировать. Чтобы расширить проверки понадобится добавить еще несколько реализаций интерфейса CheckService. Но встает вопрос, как мы будем создавать объекты этих классов, т.к. все привыкли к практикам CDI. Я выбирал для себя контейнер weld-se-core.

<dependency>
	<groupId>org.jboss.weld.se</groupId>
	<artifactId>weld-se-core</artifactId>
	<version>3.1.4.Final</version>
</dependency>
<dependency>
<dependency>
	<groupId>javax.inject</groupId>
    <artifactId>javax.inject</artifactId>
</dependency>

Инициализация такого контейнера:

Weld weld = new Weld();

WeldContainer container = weld.initialize();

Инициализация бинов в контейнере:

WeldContainer.current().select(clazz).get()

Для удобства я вынес эти строки в static блок отдельного класса Util

public class CDIContainerUtil {
   static void initIfNotExist() {
       if (WeldContainer.getRunningContainerIds().size() == 0) {
           Weld weld = new Weld();
           weld.initialize();
           Reflections reflections = new Reflections("chigarout.tutoral");
           Set<Class<?>> set = reflections.getTypesAnnotatedWith(javax.inject.Singleton.class);
           for (Class class1 : set)
               WeldContainer.current().select(class1);
       }
   }
}

Соответственно добавив аннотацию @Singlton для сервиса и @Inject для привязки должны получить работающий плагин уже на базе CDI контейнера. Добавляем следующий mojo для проверки наличия gitignore.

import chigarout.tutorial.project_file_verifier.service.CheckService;
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugin.MojoFailureException;
import org.apache.maven.plugins.annotations.Mojo;

import javax.inject.Inject;
import javax.inject.Named;

@Mojo(name = "gitignore_check", threadSafe = false)
public class GitIgnoreCheckMojo extends AbstractMojo {
    @Inject
    @Named("GitIgnoreCheckService")
    CheckService mdParser;

    public GitIgnoreCheckMojo() {
        CDIContainerUtil.initIfNotExist();
    }

    public void execute() throws MojoExecutionException, MojoFailureException {
        if (!mdParser.check()) throw new MojoFailureException("Необходимо добавить gitignore в проект.");
        getLog().info(String.format("Файл gitignore  существует в проекте"));
    }
}

Mojo для проверки наличия readme.md.

@Mojo(name = "check", threadSafe = false)
public class CheckMojo extends AbstractMojo {

	CheckService mdParser;

	public CheckMojo(){
    	mdParser = new MDCheckService();
	}

	public void execute() throws MojoExecutionException, MojoFailureException {
    	File mdFile = new File("readme.md");
    	if(!mdParser.check(mdFile)) throw new  MojoFailureException("Необходимо добавить readme.md в проект.");
    	getLog().info(String.format("Файл %s существует в проекте", mdFile.getAbsoluteFile()));
	}
}

pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://maven.apache.org/POM/4.0.0"
         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>
    <parent>
        <groupId>chigarout.tutoral</groupId>
        <artifactId>cdi-base-tutorial-maven-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <artifactId>project-file-verifier-maven-plugin</artifactId>
    <packaging>maven-plugin</packaging>

    <dependencies>
        <dependency>
            <groupId>org.apache.maven</groupId>
            <artifactId>maven-plugin-api</artifactId>
            <version>3.2.5</version>
        </dependency>
        <dependency>
            <groupId>org.apache.maven.plugin-tools</groupId>
            <artifactId>maven-plugin-annotations</artifactId>
            <version>3.5.2</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.reflections</groupId>
            <artifactId>reflections</artifactId>
            <version>0.9.11</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-plugin-plugin</artifactId>
                <version>3.4</version>
            </plugin>
        </plugins>
    </build>
</project>

Тестирование.

Когда плагин разросся или содержит сложную логику может быть проблематично выпо��нять отладку. Как следует отладив плагин можно потратить уйму времени. Есть возможность протестировать плагин через JUinit. Для этого на понадобится maven-plugin-testing-harness.

<dependency>

<groupId>org.apache.maven.plugin-testing</groupId>

<artifactId>maven-plugin-testing-harness</artifactId>

<version>3.3.0</version>

<scope>test</scope>

</dependency>

Внутри плагина содержится AbstractMojoTestCase от которого нужно будет создавать имплементации тестов. Тест кейс не воспринимает аннотации @Test @Before и т.д. Вместо этого он поддерживает именование методов с приставкой test. Вместо @Before нужно переопределить метод protected void setUp() от AbstractMojoTestCase. Если мы хотим использовать CDI то нужно пользоваться методом protected Mojo lookupMojo(String goal, File pom) throws Exception.

· goal – наименование цели.

· File – тестовый pom файл. Можно указать и основной, но я добавил отдельный pom test/resources.

Есть непонятное поведение плагина. При том что мы указываем pom из папки ресурсов тестов плагин все равно будет смотреть в корневой pom чтобы взять оттуда <artifactId>. Далее по этому artifactId он будет искать плагин в <build> для запуска уже в тестовом pom, что не совсем верно в случае если мы хотим тестировать плагин как внешнее api, т.е. если тесты находятся в verify-checks, а не в project-file-verifier-maven-plugin. Для этого я добавил в переопределение переменной basedir в тесте.

protected void setUp() throws Exception {

String oldpath = System.getProperty("user.dir");

System.setProperty("basedir",oldpath+"/src/test/resources");

super.setUp ();

}

В добавок пришлось в тестовом pom выставить artifactId в project-file-verifier-maven-plugin, что не совсем логично. Тем не менее после такого костыля. Получаем рабочий тест.

public class SampleMavenPluginTest extends AbstractMojoTestCase {

	protected void setUp() throws Exception {
    	String oldpath = System.getProperty("user.dir");
    	System.setProperty("basedir",oldpath+"/src/test/resources");
    	super.setUp ();
	}

 	public void testReadMeExist() throws Exception {
     	File pom = getTestFile("pom.xml" );
     	MDCheckMojo mojo = (MDCheckMojo) lookupMojo( "md_check", pom );
     	mojo.execute();
 	}
  
	public void testGitIgnoreExist() throws Exception {
    	File pom = getTestFile("pom.xml" );
    	GitIgnoreCheckMojo mojo = (GitIgnoreCheckMojo) lookupMojo( "gitignore_check", pom )
    	mojo.execute();
	}
}

output инициализации и проверок наличия файлов.

Модуль проверок verify-checks:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://maven.apache.org/POM/4.0.0"
         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>
    <parent>
        <groupId>chigarout.tutoral</groupId>
        <artifactId>cdi-base-tutorial-maven-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <artifactId>verify-checks</artifactId>

    <dependencies>
        <dependency>
            <groupId>org.apache.maven.plugin-testing</groupId>
            <artifactId>maven-plugin-testing-harness</artifactId>
            <version>3.3.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>chigarout.tutoral</groupId>
            <artifactId>project-file-verifier-maven-plugin</artifactId>
            <version>1.0-SNAPSHOT</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.apache.maven</groupId>
            <artifactId>maven-core</artifactId>
            <version>3.2.5</version>
        </dependency>
        <dependency>
            <groupId>org.apache.maven</groupId>
            <artifactId>maven-compat</artifactId>
            <version>3.2.5</version>
        </dependency>

        <dependency>
            <groupId>org.apache.maven</groupId>
            <artifactId>maven-project</artifactId>
            <version>2.2.1</version>
        </dependency>
        <dependency>
            <groupId>org.codehaus.plexus</groupId>
            <artifactId>plexus-component-annotations</artifactId>
            <version>1.7.1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.11</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

</project>

Т.к все мои проверки делаю в тестовой среде, то в ресурсах лежит дополнительный pom.xml со следующим содержимым

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://maven.apache.org/POM/4.0.0"
         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>
    <parent>
        <groupId>chigarout.tutoral</groupId>
        <artifactId>cdi-base-tutorial-maven-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <artifactId>project-file-verifier-maven-plugin</artifactId>
    <dependencies>
        <dependency>
            <groupId>org.apache.maven.plugin-testing</groupId>
            <artifactId>maven-plugin-testing-harness</artifactId>
            <version>3.3.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>chigarout.tutoral</groupId>
            <artifactId>project-file-verifier-maven-plugin</artifactId>
            <version>1.0-SNAPSHOT</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.apache.maven</groupId>
            <artifactId>maven-core</artifactId>
            <version>3.8.5</version>
        </dependency>
        <dependency>
            <groupId>org.apache.maven</groupId>
            <artifactId>maven-compat</artifactId>
            <version>3.8.5</version>
        </dependency>
        <dependency>
            <groupId>org.apache.maven</groupId>
            <artifactId>maven-artifact</artifactId>
            <version>3.8.5</version>
        </dependency>
        <dependency>
            <groupId>org.apache.maven</groupId>
            <artifactId>maven-project</artifactId>
            <version>2.2.1</version>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.11</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>chigarout.tutoral</groupId>
                <artifactId>project-file-verifier-maven-plugin</artifactId>
                <version>1.0-SNAPSHOT</version>
                <configuration></configuration>
                <executions>
                    <execution>
                        <configuration></configuration>
                        <phase>package</phase>
                        <goals>
                            <goal>md_check</goal>
                            <goal>gitignore_check</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Запуск mvn clean install вызовет goal md_check и gitignore_check.

Далее после сборки получаем ошибку

[ERROR] Failed to execute goal chigarout.tutoral:project-file-verifier-maven-plugin:1.0-SNAPSHOT:gitignore_check (default) on project verify-checks: Необходимо добавить gitignore в проект. -> [Help 1]

Плагин отработал штатно. Добавив .gitignore получим успешную сборку.

Отладка

Если посмотреть как выполняет отладку IntelJIdea то можно увидеть следующий вызов.

"...\java.exe" -Dmaven.multiModuleProjectDirectory=...\maven-plugin-example "-Dmaven.home=...\plugins\maven\lib\maven3" "-Dclassworlds.conf=...\plugins\maven\lib\maven3\bin\m2.conf" "-Dmaven.ext.class.path=...\plugins\maven\lib\maven-event-listener.jar" "-javaagent: ...\lib\idea_rt.jar=54536: ...\IntelliJ IDEA 2019.3.5\bin" -Dfile.encoding=UTF-8 -classpath "...\plugins\maven\lib\maven3\boot\plexus-classworlds-2.6.0.jar" org.codehaus.classworlds.Launcher -Didea.version2019.3.5 clean

Вызывается Java с добавлением параметров для дебага и с указанием main класса. org.codehaus.classworlds.Launcher – это оболочка запускающая все команды в maven.

Кроме этого у maven есть mvnDebug.exe, который лежит на уровне с mvn.exe. Запуск выглядит аналогично как и с mvn.

mvnDebug clean install.

mvnDebug будет ждать пока мы включим debug соединение в idea и после этого запустит процесс сборки.

Summary

За то время когда сам пытался разбираться с вопросами maven плагинов находил только отдельные куски нужной информации на stackoverflow и habr. В статье постарался показать как можно безболезненно сделать свой mojo, применяя устоявшиеся практики CDI и тестирования. Ничего даже не мешает вести разработку через тестирование (TDD).

Приведенный пример опубликован на github .

CookBook maven plugin. CDI, отладка и тестирование