documentation for the maven-inherit-plugin

I've uploaded some documentation for the maven-inherit-plugin in the usual format:

http://www.ops4j.org/projects/pax/construct/maven-inherit-plugin

and improved the code to use custom Javadoc tags to get the extended plugin details.

For example:

  /**
  * @extendsPlugin archetype
  * @extendsGoal create
  * @goal create-project
  * @requiresProject false
  */
  public class OSGiProjectArchetypeMojo extends MavenArchetypeMojo
  {
    // if you override member fields, remember to propagate the values using reflection
  }

Simple Maven Plugin Inheritance

Pax Construct extends a number of other maven mojos from the archetype, compiler and eclipse plugins. Extending maven mojos is a bit of a pain at the moment, because plexus (the component manager used by maven) relies on javadoc comments to generate the plugin XML. Unfortunately when the parent mojo is provided by an external project, the javadoc isn't available to plexus.

At first I relied on duplicating parameters in the sub-mojo to trick plexus into creating the right plugin XML, then used reflection to forcibly update any private fields in the parent mojo.

Maintaining these parameters was a bit of a nightmare, so I developed a new plugin called the maven-inherit-plugin to help with the plugin XML. It attempts to merge the various plugin XML fragments and warns about any potential field clashes that would require reflection.

To use it in your plugin pom, add the following XML:

    <plugin>
      <groupid>org.ops4j.pax.construct.ng</groupid>
      <artifactid>maven-inherit-plugin</artifactid>
      <executions>
        <execution>
          <goals>
            <goal>inherit</goal>
          </goals>
        </execution>
      </executions>
    </plugin>

  ...

  <pluginRepositories>
    <pluginRepository>
      <id>ops4j-repository</id>
      <url>http://repository.ops4j.org/maven2</url>
    </pluginRepository>
  </pluginRepositories>

It looks for dependencies of type "maven-plugin" and will merge the XML fragments describing their goals with any matching local goals that have the following syntax:

    @extendsPlugin {plugin}
    @goal {local-goal}

If you want to rename a inherited goal, use this syntax:

    @extendsPlugin {plugin}
    @extendsGoal {inherited-goal}
    @goal {local-goal}

For example, in Pax-Construct I extend the archetype goal into a number of sub-goals, such as:

  /**
  * @extendsPlugin archetype
  * @extendsGoal create
  * @goal create-project
  * @requiresProject false
  */

Overridden fields generate a warning at compile time and must be updated using reflection. See the main pax plugin for examples of using this technique to add behaviour to existing plugins.

Source code is available from:

    https://scm.ops4j.org/repos/ops4j/projects/pax/construct/maven-inherit-plugin

(updated to show new javadoc tags)

Calling all testers! Pax Construct v2 beta1

Well, we've finally completed the move to our new home and are slowly unpacking boxes "on-demand" :)

Meanwhile, back at OPS4J I've finished a major refactoring of the Pax Construct plugin and slimmed down the archetypes to produce a much leaner project layout. The more adventurous of you might like to try out the beta version:

http://repository.ops4j.org/maven2/org/ops4j/pax/construct/scripts/0.2.0-beta1/scripts-0.2.0-beta1.zip

Be warned - the usual beta disclaimers apply! Especially since the only machine I have with Windows is still packed away, and so all testing so far has been on my macbook using Ubuntu (my main development environment). Also, the docs are woefully out of date - at this moment the code is the best documentation, but you can use -h with any of the scripts to get basic usage.

Second warning: Pax Construct v2 is not compatible with projects created using older versions, but a script is being developed to migrate projects to the new layout. However you can use v2 to create and manage new projects.

Some highlights of v2:

• Transitive wrapping - you can choose to embed dependencies, or create further wrappers
• Transitive import - provided dependencies of imported bundles are automatically added
• Simple import management - the import list is maintained inside a single provision pom
• Optional generation of Eclipse project files - use "mvn clean install -Peclipse"
• Enhanced compilation - supports compiling against bundles with embedded jars
• Refactoring support - bundles can be moved around, poms will be created as necessary
• Improved maven mojos - can be used inside other poms to create projects for testing

Here's a couple of wrapping examples, which should be done inside a project created with pax-create-project - the first creates a bundle with embedded dependencies (use "mvn clean install" to build it) the second replaces it with a series of bundles, one per dependency:

pax-wrap-jar -g commons-logging -a commons-logging -v 1.1 -- -DembedTransitive

pax-wrap-jar -g commons-logging -a commons-logging -v 1.1 -- -DwrapTransitive -Doverwrite

A more complex example involving Spring-OSGi can be downloaded here:

Spring-OSGi deployment script (unix)
Spring-OSGi deployment script (windows)

Download the script for your OS, make sure the v2 scripts are in your path and run it - it should build and deploy a basic Spring-OSGi setup based on milestone 3, along with some wrappers and the weather sample. (note: it can take a few seconds to startup on Felix, the default framework)

There's a lot of cool stuff behind the scenes, and I'm starting on proper documentation for it this week. BTW, if you find any bugs with beta1 please raise them at http://issues.ops4j.org while I work on the docs :)