| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| http://www.apache.org/licenses/LICENSE-2.0 |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!-- |
| $HeadURL$ |
| $Revision$ $Date$ |
| --> |
| <document> |
| |
| <properties> |
| <title>Development</title> |
| <author email="dev@commons.apache.org">Apache Commons Documentation Team</author> |
| </properties> |
| |
| <body> |
| |
| <section name="Help with Maven Mojos"> |
| |
| <p> |
| The best sources of information are |
| <a href="http://maven.apache.org/guides/plugin/guide-java-plugin-development.html">Developing Java Plugins for Maven 3.x</a> |
| and <a href="http://www.sonatype.com/book/chapter-11.html">Maven: The Definitive Guide: Chapter 11 Writing Plugins</a>. |
| </p> |
| |
| </section> |
| |
| <section name="New Mojos"> |
| |
| <p> |
| Each Mojo is a java file that extends <code>AbstractMojo</code> that contains an annotation specifying |
| the goal name for the mojo and the maven lifecycle phase that it executes under by default. For, example |
| <source><![CDATA[ |
| package org.apache.commons.release.plugin.mojos; |
| |
| @Mojo(name = "detach-distributions", defaultPhase = LifecyclePhase.VERIFY, threadSafe = true) |
| public class CommonsDistributionDetachmentMojo extends AbstractMojo { |
| ..... |
| }]]></source> |
| specifies the goal <code>commons-release:detach-distributions</code> that is to occur during the VERIFY maven |
| lifecycle. |
| </p> |
| |
| <p> |
| The variables in the mojo that are declared as private with the annotations <code>@Parameter</code> get |
| imported to the Mojo by the existent maven variables or the declared <code><configuration></code>. For |
| example, we have a boolean variable named <code>dryRun</code> declared as: |
| <source><![CDATA[ |
| @Parameter(property = "commons.release.dryRun", defaultValue = "false") |
| private Boolean dryRun; |
| ]]></source> |
| that can be configured by |
| <source><![CDATA[ |
| <plugin> |
| <groupId>org.apache.commons</groupId> |
| <artifactId>commons-release-plugin</artifactId> |
| <version>1.1</version> |
| <configuration> |
| <dryRun>true</dryRun> |
| </configuration> |
| </plugin>]]></source> |
| |
| And, because we've set the <code>property here</code> (as in the 1.1 release), you can, on the command line, |
| use the following <code>-Dcommons.release.dryRun=true</code>. |
| </p> |
| |
| </section> |
| |
| <section name="Unit testing"> |
| |
| <p> |
| We've declared mock maven poms in the <code>resources</code> directory of the <code>src/test</code> folder, |
| under which we've stored in subdirectories corresponding to the names of the mojos that they are testing. All |
| variables that you wish to be available to your mojo must be specifically declared in the mock pom file. For |
| example, we need to use the already existent <code>MavenProject</code> in the maven runtime by instead, in a |
| test package declaring a class extending <code>MavenProjectStub</code> that returns values we wish to be used |
| in testing. We then add this to our pom in the following declaration of the plugin: |
| <source><![CDATA[ |
| <plugin> |
| <groupId>org.apache.commons</groupId> |
| <artifactId>commons-release-plugin</artifactId> |
| <configuration> |
| <project implementation="org.apache.commons.release.plugin.stubs.DistributionDetachmentProjectStub" /> |
| <workingDirectory>target/commons-release-plugin</workingDirectory> |
| <distSvnStagingUrl>mockDistSvnStagingUrl</distSvnStagingUrl> |
| </configuration> |
| </plugin>]]></source> |
| Also note here we are declaring other values that we are using in the testing of the plugin. We then retrieve |
| our instantiated mojo by declaring a <code>MojoRule</code> in our test class, |
| <source><![CDATA[ |
| @Rule |
| public MojoRule rule = new MojoRule() { |
| @Override |
| protected void before() throws Throwable { |
| } |
| |
| @Override |
| protected void after() { |
| } |
| };]]></source> |
| and then retrieve the mojo by newing up a <code>File</code> pointed to the path of the mock pom, and then |
| making the following call: |
| <source><![CDATA[ |
| mojo = (CommonsSiteCompressionMojo) rule.lookupMojo("compress-site", testPom); |
| ]]></source> |
| where we are trying to get the mojo with the <code>compress-site</code> goal. |
| </p> |
| |
| </section> |
| |
| <section name="Debugging"> |
| |
| <p> |
| Maven ships with a debugger under the hood. It is suggested that you have a sandbox project in which you can |
| run the goals or the plugin configuration. Once you have that set up you can run something like |
| <source><![CDATA[ |
| mvnDebug commons-release:detach-distributions |
| ]]></source> |
| which exposes a remote debugger on port 8000 and halts the maven process until you attach a remote debugger |
| to that port. Once you have a remote debugger attached the maven process continues and stops at any |
| breakpoints that you have set up in your project. |
| </p> |
| |
| </section> |
| |
| </body> |
| </document> |
