Java 5 Annotations for Plugins
Skip to end of metadata
Go to start of metadata

status: done in Maven Plugin Tools 3.0

Context

Maven plugins are described in META-INF/maven/plugin.xml descriptor, which is in general generated by maven-plugin-plugin. Information for the generator are written as javadoc annotations in java source: see maven-plugin-tools-java.

Using java 5 annotations instead of javadoc ones have multiple benefits:

  • compile-time checks for plugin metadata, with enums for some annotations
  • inheritance support
  • annotations are supported in most IDEs, providing code-completion and syntactic checks

see plexus-component-annotations for an example of such a work done on Plexus.

Existing implementations

Multiple implementations of such annotations exist:

Proposal

Continue the work started on MNG-2521 before plugin-tools extraction from Maven Core.

Annotations:

  • 4 annotations: @Mojo and @Execute at class-level, @Parameter and @Component at field level
  • java package: org.apache.maven.tools.plugin.annotations (consistent with maven-plugin-tools-api
  • a new maven-plugin-tools-annotations component in plugin-tools

Extractor: addition into existing maven-plugin-tools-java

New features

  • use annotations from parents classes coming from reactors and external dependencies.

Implementation

Initial work done in trunk http://svn.apache.org/repos/asf/maven/plugin-tools/trunk/

The maven-plugin-plugin version has been bump to 3.0-SNAPSHOT.

State of the development as of 22/5/2012

Following usage for a plugin developer is working, with annotations near previous javadoc tags:

Improvement Idea #1

rename roleHint to hint to match Plexus @Requirement

DONE

Improvement Idea #2

Remove readonly attribute from @Parameter (was used for Maven components like ${project} to mark that it should not be configured by plugin user), and replace by a new attribute of @Component which is mutually exclusive with role+hint

evaluation: ${project.compileClasspathElements} is an expression that would be readonly but doesn't really resolve to a component, so the term isn't appropriate. Need a better term.

Improvement Idea #3

Introduce JSR-330, by requiring plugin developer to mark injected fields with standard @Inject and make @Parameter and @Component standard Qualifier.
Costs more writing for plugin developer (these @Inject) without much win other than mark the intent in a standard way (and shouldn't change much for maven-plugin-tools)

evaluation: since plugin.xml is still generated and content is injected by Maven core using this plugin.xml and not annotations taken from bytecode, this is not really useful and causes more confusion/harm than benefit

Labels
  • No labels
  1. I think it is a bad smell to have annotations like @Mojo, @MojoExecute, @MojoParameter and @MojoComponent

    We should take use of the whole package namespacing thingy... no need to prefix with Mojo IMHO

    @Goal
    @Execute
    @Parameter
    @Component

    are better, e.g.

    is better than

    Now I would see @Mojo being appropriate if we were ditching inheritance for mojo's, so that if you had

    But actually, I would prefer in that case

    I think the above could be implemented somewhat using synthentic bridging classes generated during the annotation processing

    1. Actually thinking about my final example, there is no need for the @Mojo annotation on the class in that case at all!

      1. ok, no "Mojo" prefix for Execute, Parameter and Component

        for the multiple goals in a single class, yes, a future feature can be added when @Mojo is used as a method annotation
        I only see one issue to implement this feature: annotations are available after compilation, but such a feature would require generating source, then before compilation...
        I don't think that this feature qill be available for the first release, but we can work on it after if really requested

        1. Well I was thinking that using ASM you could just generate the synthetic bridging classes in the process-classes phase. The bytecode would be simple as it will always do the exact same

          1. Ahh yes... I'm seeing the chicken and egg issue....

            Of course the chicken and egg issue also exists for the help mojo that gets generated...