You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by bu...@apache.org on 2012/03/01 17:35:47 UTC
svn commit: r806895 [33/46] - in /websites/staging/maventest/trunk: ./
content/ content/ant/ content/background/ content/css/ content/developers/
content/developers/conventions/ content/developers/release/
content/developers/website/ content/docs/ cont...
Added: websites/staging/maventest/trunk/content/guides/mini/guide-wagon-providers.html
==============================================================================
--- websites/staging/maventest/trunk/content/guides/mini/guide-wagon-providers.html (added)
+++ websites/staging/maventest/trunk/content/guides/mini/guide-wagon-providers.html Thu Mar 1 16:35:39 2012
@@ -0,0 +1,255 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia at Mar 1, 2012 -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Guide to Selecting Alternative Wagon Providers</title>
+ <style type="text/css" media="all">
+ @import url("../../css/maven-base.css");
+ @import url("../../css/maven-theme.css");
+ @import url("../../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+ <meta name="author" content="John Casey" />
+ <meta name="Date-Revision-yyyymmdd" content="20120301" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+
+<script type="text/javascript">_uacct = "UA-140879-1";
+ urchinTracker();</script>
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../.././" id="bannerLeft">
+ <img src="../../images/apache-maven-project-2.png" alt="" />
+ </a>
+ <span id="bannerRight">
+ <img src="../../images/maven-logo-2.gif" alt="" />
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+ <div class="xleft">
+ <a href="http://www.apache.org/" class="externalLink">Apache</a>
+ >
+ <a href="../../index.html">Maven</a>
+ >
+ Guide to Selecting Alternative Wagon Providers
+ </div>
+ <div class="xright">
+ Last Published: 2012-03-01
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+ <h5>Main</h5>
+ <ul>
+ <li class="none">
+ <a href="../../index.html">Welcome</a>
+ </li>
+ </ul>
+ <h5>Get Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../download.html">Download</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+ </li>
+ <li class="none">
+ <a href="../../license.html">License</a>
+ </li>
+ </ul>
+ <h5>IDE Integration</h5>
+ <ul>
+ <li class="none">
+ <a href="../../eclipse-plugin.html">Eclipse</a>
+ </li>
+ <li class="none">
+ <a href="../../netbeans-module.html">NetBeans</a>
+ </li>
+ </ul>
+ <h5>About Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../what-is-maven.html">What is Maven?</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-features.html">Features</a>
+ </li>
+ <li class="none">
+ <a href="../../general.html">FAQ (official)</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+ </li>
+ <li class="none">
+ <a href="../../powered-by-m2.html">Powered By</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="../../plugins/index.html">Maven Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/index.html">Index (category)</a>
+ </li>
+ <li class="none">
+ <a href="../../run-maven/index.html">Running Maven</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../users/index.html">User Centre</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../repository/index.html">Maven Repository Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../developers/index.html">Maven Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../articles.html">Books and Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+ </li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li class="none">
+ <a href="../../community.html">Community Overview</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../users/getting-help.html">Getting Help</a>
+ </li>
+ <li class="none">
+ <a href="../../issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="../../source-repository.html">Source Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../team-list.html">The Maven Team</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="../../project-info.html">Project Information</a>
+ </li>
+ </ul>
+ <h5>Maven Projects</h5>
+ <ul>
+ <li class="none">
+ <a href="../../ant-tasks/index.html">Ant Tasks</a>
+ </li>
+ <li class="none">
+ <a href="../../archetype/index.html">Archetype</a>
+ </li>
+ <li class="none">
+ <a href="../../doxia/index.html">Doxia</a>
+ </li>
+ <li class="none">
+ <a href="../../jxr/index.html">JXR</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-1.x/index.html">Maven 1.x</a>
+ </li>
+ <li class="none">
+ <a href="../../index.html">Maven 2 & 3</a>
+ </li>
+ <li class="none">
+ <a href="../../plugins/index.html">Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../scm/index.html">SCM</a>
+ </li>
+ <li class="none">
+ <a href="../../shared/index.html">Shared Components</a>
+ </li>
+ <li class="none">
+ <a href="../../surefire/index.html">Surefire</a>
+ </li>
+ <li class="none">
+ <a href="../../wagon/index.html">Wagon</a>
+ </li>
+ </ul>
+ <h5>ASF</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+ </a>
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <div class="section"><h2>Guide to Selecting Alternative Wagon Providers<a name="Guide_to_Selecting_Alternative_Wagon_Providers"></a></h2><p>By default, Maven uses the <tt>java.net.URLConnection</tt> (<tt>HttpURLConnection</tt>) classes provided with the JDK to access repositories that use the HTTP/HTTPs protocols. Unfortunately, since this implementation contains certain bugs, Maven users may find themselves unable to connect to servers that demand some configurations. A couple examples of weird behavior include line-wrapping the Authorization header's Base64 value when passwords are long, and using cached values in preemptive authentication for successive connections to the same server.</p><p>Maven 2.2.0 attempted to amend this problem by switching over to a Wagon implementation that's based on Apache HttpClient. Unfortunately, it soon became apparent that HttpClient doesn't support NTLM (at least, version 2), which effectively means users behind NTLMv2 proxies cann
ot use Maven 2.2.0.</p><p>To hopefully resolve this once and for all, Maven 2.2.1 will contain support for specifying which Wagon provider you want to use for a given protocol during the build. The provider name will then be appended to the protocol using the format <tt><protocol>-<provider></tt> to form the component role-hint for the Wagon.</p><p>As of Maven 2.2.1, there are two ways to specify which Wagon provider should be used: via the command line, or in the <tt><server></tt> configuration section of the <tt>settings.xml</tt>.</p><div class="section"><h3>Command-Line Configuration<a name="Command-Line_Configuration"></a></h3><p>To specify the Wagon provider from the command line, simply use the <tt>-Dmaven.wagon.provider.<protocol>=<provider-name></tt> command-line option, like the following:</p><div class="source"><pre>mvn -Dmaven.wagon.provider.http=httpclient clean install</pre></div><p>This instructs Maven to use the HttpClient-based W
agon implementation for connections to HTTP repositories.</p></div><div class="section"><h3><tt>settings.xml</tt> Configuration<a name="settings.xml_Configuration"></a></h3><p>To specify which Wagon provider to use for a particular server, modify your <tt>settings.xml</tt> file to add the <tt><wagonProvider></tt> configuration to your <tt><server></tt> entry, like the following:</p><div class="source"><pre><settings>
+ [...]
+ <servers>
+ <server>
+ <id>central</id>
+ <configuration>
+ <wagonProvider>httpclient</wagonProvider>
+ [...]
+ </configuration>
+ </server></pre></div></div><div class="section"><h3>Available Wagon Providers<a name="Available_Wagon_Providers"></a></h3><p>Maven 2.2.1 provides two providers for HTTP/HTTPS Wagons: <tt>lightweight</tt> and <tt>httpclient</tt>. If you add a new HTTP Wagon implementation via build extension, you'll need to make sure the extension binds its Wagon components to role-hints of the form <tt><protocol>-<provider></tt> in order to allow users to specify your alternative Wagon provider. For instance, the HttpClient HTTP Wagon component definition looks like this:</p><div class="source"><pre><component>
+ <role>org.apache.maven.wagon.Wagon</role>
+ <role-hint>http-httpclient</role-hint>
+ <implementation>org.apache.maven.wagon.providers.http.HttpWagon</implementation>
+ <instantiation-strategy>per-lookup</instantiation-strategy>
+</component></pre></div><p><b>NOTE:</b> The default provider for HTTP/HTTPS Wagons is <tt>lightweight</tt>.</p></div></div>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ © 2002-2012
+ The Apache Software Foundation
+
+ - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+ Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/maventest/trunk/content/guides/mini/guide-webapp.html
==============================================================================
--- websites/staging/maventest/trunk/content/guides/mini/guide-webapp.html (added)
+++ websites/staging/maventest/trunk/content/guides/mini/guide-webapp.html Thu Mar 1 16:35:39 2012
@@ -0,0 +1,264 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia at Mar 1, 2012 -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Guide to Webapps</title>
+ <style type="text/css" media="all">
+ @import url("../../css/maven-base.css");
+ @import url("../../css/maven-theme.css");
+ @import url("../../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+ <meta name="author" content="Jason van Zyl" />
+ <meta name="Date-Revision-yyyymmdd" content="20120301" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+
+<script type="text/javascript">_uacct = "UA-140879-1";
+ urchinTracker();</script>
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../.././" id="bannerLeft">
+ <img src="../../images/apache-maven-project-2.png" alt="" />
+ </a>
+ <span id="bannerRight">
+ <img src="../../images/maven-logo-2.gif" alt="" />
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+ <div class="xleft">
+ <a href="http://www.apache.org/" class="externalLink">Apache</a>
+ >
+ <a href="../../index.html">Maven</a>
+ >
+ Guide to Webapps
+ </div>
+ <div class="xright">
+ Last Published: 2012-03-01
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+ <h5>Main</h5>
+ <ul>
+ <li class="none">
+ <a href="../../index.html">Welcome</a>
+ </li>
+ </ul>
+ <h5>Get Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../download.html">Download</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+ </li>
+ <li class="none">
+ <a href="../../license.html">License</a>
+ </li>
+ </ul>
+ <h5>IDE Integration</h5>
+ <ul>
+ <li class="none">
+ <a href="../../eclipse-plugin.html">Eclipse</a>
+ </li>
+ <li class="none">
+ <a href="../../netbeans-module.html">NetBeans</a>
+ </li>
+ </ul>
+ <h5>About Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../what-is-maven.html">What is Maven?</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-features.html">Features</a>
+ </li>
+ <li class="none">
+ <a href="../../general.html">FAQ (official)</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+ </li>
+ <li class="none">
+ <a href="../../powered-by-m2.html">Powered By</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="../../plugins/index.html">Maven Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/index.html">Index (category)</a>
+ </li>
+ <li class="none">
+ <a href="../../run-maven/index.html">Running Maven</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../users/index.html">User Centre</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../repository/index.html">Maven Repository Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../developers/index.html">Maven Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../articles.html">Books and Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+ </li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li class="none">
+ <a href="../../community.html">Community Overview</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../users/getting-help.html">Getting Help</a>
+ </li>
+ <li class="none">
+ <a href="../../issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="../../source-repository.html">Source Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../team-list.html">The Maven Team</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="../../project-info.html">Project Information</a>
+ </li>
+ </ul>
+ <h5>Maven Projects</h5>
+ <ul>
+ <li class="none">
+ <a href="../../ant-tasks/index.html">Ant Tasks</a>
+ </li>
+ <li class="none">
+ <a href="../../archetype/index.html">Archetype</a>
+ </li>
+ <li class="none">
+ <a href="../../doxia/index.html">Doxia</a>
+ </li>
+ <li class="none">
+ <a href="../../jxr/index.html">JXR</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-1.x/index.html">Maven 1.x</a>
+ </li>
+ <li class="none">
+ <a href="../../index.html">Maven 2 & 3</a>
+ </li>
+ <li class="none">
+ <a href="../../plugins/index.html">Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../scm/index.html">SCM</a>
+ </li>
+ <li class="none">
+ <a href="../../shared/index.html">Shared Components</a>
+ </li>
+ <li class="none">
+ <a href="../../surefire/index.html">Surefire</a>
+ </li>
+ <li class="none">
+ <a href="../../wagon/index.html">Wagon</a>
+ </li>
+ </ul>
+ <h5>ASF</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+ </a>
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <div class="source"><pre>
+mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-webapp -DarchetypeArtifactId=maven-archetype-webapp
+</pre></div><div class="source"><pre>
+<project>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-webapp</artifactId>
+ <packaging>war</packaging>
+ <version>1.0-SNAPSHOT</version>
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>3.8.1</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+ <build>
+ <finalName>my-webapp</finalName>
+ </build>
+</project>
+</pre></div><p>Note the <i>packaging</i> element - this tells Maven to build as a WAR. Change into the webapp project's directory and try:</p><div class="source"><pre>
+mvn clean package
+</pre></div><p>You'll see target/my-webapp.war is built, and that all the normal steps were executed.</p><p>Now you can modify this webapp project and turn it into anything you need!</p>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ © 2002-2012
+ The Apache Software Foundation
+
+ - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+ Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/maventest/trunk/content/guides/mini/index.html
==============================================================================
--- websites/staging/maventest/trunk/content/guides/mini/index.html (added)
+++ websites/staging/maventest/trunk/content/guides/mini/index.html Thu Mar 1 16:35:39 2012
@@ -0,0 +1,241 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia at Mar 1, 2012 -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Maven Mini Guides</title>
+ <style type="text/css" media="all">
+ @import url("../../css/maven-base.css");
+ @import url("../../css/maven-theme.css");
+ @import url("../../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+ <meta name="author" content="Jason van Zyl" />
+ <meta name="Date-Revision-yyyymmdd" content="20120301" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+
+<script type="text/javascript">_uacct = "UA-140879-1";
+ urchinTracker();</script>
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../.././" id="bannerLeft">
+ <img src="../../images/apache-maven-project-2.png" alt="" />
+ </a>
+ <span id="bannerRight">
+ <img src="../../images/maven-logo-2.gif" alt="" />
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+ <div class="xleft">
+ <a href="http://www.apache.org/" class="externalLink">Apache</a>
+ >
+ <a href="../../index.html">Maven</a>
+ >
+ Maven Mini Guides
+ </div>
+ <div class="xright">
+ Last Published: 2012-03-01
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+ <h5>Main</h5>
+ <ul>
+ <li class="none">
+ <a href="../../index.html">Welcome</a>
+ </li>
+ </ul>
+ <h5>Get Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../download.html">Download</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+ </li>
+ <li class="none">
+ <a href="../../license.html">License</a>
+ </li>
+ </ul>
+ <h5>IDE Integration</h5>
+ <ul>
+ <li class="none">
+ <a href="../../eclipse-plugin.html">Eclipse</a>
+ </li>
+ <li class="none">
+ <a href="../../netbeans-module.html">NetBeans</a>
+ </li>
+ </ul>
+ <h5>About Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../what-is-maven.html">What is Maven?</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-features.html">Features</a>
+ </li>
+ <li class="none">
+ <a href="../../general.html">FAQ (official)</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+ </li>
+ <li class="none">
+ <a href="../../powered-by-m2.html">Powered By</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="../../plugins/index.html">Maven Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/index.html">Index (category)</a>
+ </li>
+ <li class="none">
+ <a href="../../run-maven/index.html">Running Maven</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../users/index.html">User Centre</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../repository/index.html">Maven Repository Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../developers/index.html">Maven Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../articles.html">Books and Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+ </li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li class="none">
+ <a href="../../community.html">Community Overview</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../users/getting-help.html">Getting Help</a>
+ </li>
+ <li class="none">
+ <a href="../../issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="../../source-repository.html">Source Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../team-list.html">The Maven Team</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="../../project-info.html">Project Information</a>
+ </li>
+ </ul>
+ <h5>Maven Projects</h5>
+ <ul>
+ <li class="none">
+ <a href="../../ant-tasks/index.html">Ant Tasks</a>
+ </li>
+ <li class="none">
+ <a href="../../archetype/index.html">Archetype</a>
+ </li>
+ <li class="none">
+ <a href="../../doxia/index.html">Doxia</a>
+ </li>
+ <li class="none">
+ <a href="../../jxr/index.html">JXR</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-1.x/index.html">Maven 1.x</a>
+ </li>
+ <li class="none">
+ <a href="../../index.html">Maven 2 & 3</a>
+ </li>
+ <li class="none">
+ <a href="../../plugins/index.html">Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../scm/index.html">SCM</a>
+ </li>
+ <li class="none">
+ <a href="../../shared/index.html">Shared Components</a>
+ </li>
+ <li class="none">
+ <a href="../../surefire/index.html">Surefire</a>
+ </li>
+ <li class="none">
+ <a href="../../wagon/index.html">Wagon</a>
+ </li>
+ </ul>
+ <h5>ASF</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+ </a>
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <div class="section"><h2>Maven Mini Guides<a name="Maven_Mini_Guides"></a></h2></div>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ © 2002-2012
+ The Apache Software Foundation
+
+ - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+ Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/maventest/trunk/content/guides/plugin/guide-ant-plugin-development.html
==============================================================================
--- websites/staging/maventest/trunk/content/guides/plugin/guide-ant-plugin-development.html (added)
+++ websites/staging/maventest/trunk/content/guides/plugin/guide-ant-plugin-development.html Thu Mar 1 16:35:39 2012
@@ -0,0 +1,561 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia at Mar 1, 2012 -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Guide to Developing Ant Plugins</title>
+ <style type="text/css" media="all">
+ @import url("../../css/maven-base.css");
+ @import url("../../css/maven-theme.css");
+ @import url("../../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+ <meta name="author" content="John Casey
+Dennis Lundberg" />
+ <meta name="Date-Creation-yyyymmdd" content="20101217" />
+ <meta name="Date-Revision-yyyymmdd" content="20120301" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+
+<script type="text/javascript">_uacct = "UA-140879-1";
+ urchinTracker();</script>
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../.././" id="bannerLeft">
+ <img src="../../images/apache-maven-project-2.png" alt="" />
+ </a>
+ <span id="bannerRight">
+ <img src="../../images/maven-logo-2.gif" alt="" />
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+ <div class="xleft">
+ <a href="http://www.apache.org/" class="externalLink">Apache</a>
+ >
+ <a href="../../index.html">Maven</a>
+ >
+ Guide to Developing Ant Plugins
+ </div>
+ <div class="xright">
+ Last Published: 2012-03-01
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+ <h5>Main</h5>
+ <ul>
+ <li class="none">
+ <a href="../../index.html">Welcome</a>
+ </li>
+ </ul>
+ <h5>Get Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../download.html">Download</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+ </li>
+ <li class="none">
+ <a href="../../license.html">License</a>
+ </li>
+ </ul>
+ <h5>IDE Integration</h5>
+ <ul>
+ <li class="none">
+ <a href="../../eclipse-plugin.html">Eclipse</a>
+ </li>
+ <li class="none">
+ <a href="../../netbeans-module.html">NetBeans</a>
+ </li>
+ </ul>
+ <h5>About Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../what-is-maven.html">What is Maven?</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-features.html">Features</a>
+ </li>
+ <li class="none">
+ <a href="../../general.html">FAQ (official)</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+ </li>
+ <li class="none">
+ <a href="../../powered-by-m2.html">Powered By</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="../../plugins/index.html">Maven Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/index.html">Index (category)</a>
+ </li>
+ <li class="none">
+ <a href="../../run-maven/index.html">Running Maven</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../users/index.html">User Centre</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../repository/index.html">Maven Repository Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../developers/index.html">Maven Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../articles.html">Books and Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+ </li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li class="none">
+ <a href="../../community.html">Community Overview</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../users/getting-help.html">Getting Help</a>
+ </li>
+ <li class="none">
+ <a href="../../issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="../../source-repository.html">Source Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../team-list.html">The Maven Team</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="../../project-info.html">Project Information</a>
+ </li>
+ </ul>
+ <h5>Maven Projects</h5>
+ <ul>
+ <li class="none">
+ <a href="../../ant-tasks/index.html">Ant Tasks</a>
+ </li>
+ <li class="none">
+ <a href="../../archetype/index.html">Archetype</a>
+ </li>
+ <li class="none">
+ <a href="../../doxia/index.html">Doxia</a>
+ </li>
+ <li class="none">
+ <a href="../../jxr/index.html">JXR</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-1.x/index.html">Maven 1.x</a>
+ </li>
+ <li class="none">
+ <a href="../../index.html">Maven 2 & 3</a>
+ </li>
+ <li class="none">
+ <a href="../../plugins/index.html">Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../scm/index.html">SCM</a>
+ </li>
+ <li class="none">
+ <a href="../../shared/index.html">Shared Components</a>
+ </li>
+ <li class="none">
+ <a href="../../surefire/index.html">Surefire</a>
+ </li>
+ <li class="none">
+ <a href="../../wagon/index.html">Wagon</a>
+ </li>
+ </ul>
+ <h5>ASF</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+ </a>
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <!-- 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. --><!-- NOTE: For help with the syntax of this file, see: --><!-- http://maven.apache.org/doxia/referen
ces/apt-format.html --><!-- NOTE: This guide has been adapted from "Guide to Developing Java Plugins" --><!-- by Bob Allison. --><div class="section"><h2>Developing Ant Plugins for Maven 2.x<a name="Developing_Ant_Plugins_for_Maven_2.x"></a></h2><div class="section"><h3>Warning<a name="Warning"></a></h3><p><b>The documentation below assumes that you have updated your locally cached cached copy of the maven-plugin-plugin. To update your copy, you will need to include the -U option when you build your plugin project:</b></p><div class="source"><pre>mvn -U clean install</pre></div><p>The maven-plugin-plugin is responsible for reading plugin metadata in its various forms and writing a standard Maven plugin descriptor based on the input. It was designed to accommodate multiple plugin languages side by side, but its initial design was slightly flawed for plugin languages that don't include the metadata inline with the source (within the same file). Since the 2.0.1 release of Maven
, the maven-plugin-plugin has contained revisions to handle this scenario. Since the API has changed (in a backward-compatible way), and since the Ant plugin support requires these changes be in place, you will see an <tt>AbstractMethodError</tt> if you try to build an Ant-based plugin using the old maven-plugin-plugin.</p></div><div class="section"><h3>Introduction<a name="Introduction"></a></h3><p>The intent of this document is to help users learn to develop Maven plugins using Ant.</p><p>As of the 2.0.1 release, Maven supports Ant-driven plugins. These plugins allow the invocation of Ant targets (specified in scripts embedded in the plugin JAR) at specific points in the build lifecycle. They can also inject parameter values into the Ant project instances when a target is called.</p></div><div class="section"><h3>Conventions<a name="Conventions"></a></h3><p>In this guide, we'll use the standard Maven directory structure for projects, to keep our POMs as simple as possible.
It's important to note that this is only a standard layout, not a requirement. The important locations for our discussion are the following:</p><div class="source"><pre> /<project-root>
+ |
+ +- pom.xml
+ |
+ +- /src
+ | |
+ | +- /main
+ | | |
+ | | +- /scripts (source location for script-driven plugins)
+ | | | |
+ ...</pre></div></div><div class="section"><h3>Getting Started<a name="Getting_Started"></a></h3><p>We'll start with the simplest of all possible plugins. This plugin takes no parameters, and will simply print a message out to the screen when invoked. This should familiarize the reader with the basics of mapping Ant build scripts to the Maven plugin framework. From there, we will gradually increase the complexity of our plugin, adding parameters, interacting with standard project locations, and binding to lifecycle phases. Finally, we'll see how a single Ant build script can be mapped to multiple Maven mojos within the same plugin.</p><div class="section"><h4>Hello, World<a name="Hello_World"></a></h4><p>Our first plugin will simply print "Hello, World" to the console.</p><div class="section"><h5>The Build Script<a name="The_Build_Script"></a></h5><p>The elemental Ant-driven mojo consists of a simple Ant build script, a mapping metadata file, and of course the plu
gin's POM. If our goal is to print "Hello, World", we might use an Ant build script that looks something like this:</p><div class="source"><pre>hello.build.xml:
+--------------------------------
+
+<project>
+ <target name="hello">
+ <echo>Hello, World</echo>
+ </target>
+</project></pre></div></div><div class="section"><h5>The Mapping Document<a name="The_Mapping_Document"></a></h5><p>Once we've created this build script, we need to tell Maven how to use it as a plugin. This involves creating a mapping document. Note that where the build script was named <b>hello.build.xml</b>, the mapping document is named <b>hello.mojos.xml</b>. The naming of these files is very important, as this is how the plugin parser matches mapping documents to build scripts. It has the general form:</p><ul><li><i>basename</i><b>.build.xml</b> - The Ant build script.</li><li><i>basename</i><b>.mojos.xml</b> - The corresponding mapping document.</li></ul><p>A simple mapping document used to wire the above build script into Maven's plugin framework might look as follows:</p><div class="source"><pre>hello.mojos.xml:
+------------------------------
+
+<pluginMetadata>
+ <mojos>
+ <mojo>
+ <goal>hello</goal>
+
+ <!-- this element refers to the Ant target we'll invoke -->
+ <call>hello</call>
+ <description>
+ Say Hello, World.
+ </description>
+ </mojo>
+ </mojos>
+</pluginMetadata></pre></div></div><div class="section"><h5>The POM<a name="The_POM"></a></h5><p>Now that we have the build script and mapping document, we're ready to build this plugin. However, in order to build, we need to provide a POM for our new plugin. As it turns out, the POM required for an Ant-driven plugin is fairly complex. This is because we have to configure the maven-plugin-plugin to use the Ant plugin parsing tools in addition to the defaults (such as the Java parsing tools). Our POM might look something like this:</p><div class="source"><pre>pom.xml:
+------------------------------
+
+<project>
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>org.myproject.plugins</groupId>
+ <artifactId>hello-plugin</artifactId>
+ <version>1.0-SNAPSHOT</version>
+
+ <packaging>maven-plugin</packaging>
+
+ <name>Hello Plugin</name>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-script-ant</artifactId>
+ <version>2.0.6</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <plugins>
+ <plugin>
+ <!-- NOTE: We don't need groupId if the plugin's groupId is
+ org.apache.maven.plugins OR org.codehaus.mojo.
+ -->
+ <artifactId>maven-plugin-plugin</artifactId>
+ <version>2.5</version>
+
+ <!-- Add the Ant plugin tools -->
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.maven.plugin-tools</groupId>
+ <artifactId>maven-plugin-tools-ant</artifactId>
+ <version>2.5</version>
+ </dependency>
+ </dependencies>
+
+ <!-- Tell the plugin-plugin which prefix we will use.
+ Later, we'll configure Maven to allow us to invoke this
+ plugin using the "prefix:mojo" shorthand.
+ -->
+ <configuration>
+ <goalPrefix>hello</goalPrefix>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+</project></pre></div></div><div class="section"><h5>Build It and Run It<a name="Build_It_and_Run_It"></a></h5><p>Once we have a POM for our new plugin, we can install it into the local repository just as we would any other Maven project:</p><div class="source"><pre>mvn install</pre></div><p>and invoke it like this:</p><div class="source"><pre>mvn org.myproject.plugins:hello-plugin:hello</pre></div><p>This should output the following:</p><div class="source"><pre>[echo] Hello, World</pre></div></div></div></div><div class="section"><h3>Using <b>prefix:mojo</b> Invocation Syntax<a name="Using_prefix:mojo_Invocation_Syntax"></a></h3><p>Our new plugin works, but look at that command line... The next thing is to configure Maven so we can use the familiar <b>prefix:mojo</b> invocation syntax, and leave that verbose, fully-qualified mess behind.</p><p>As you know, Maven maps plugins to user-friendly prefixes. However, these prefixes might overlap; that is, multiple plugins ma
y try to use the same prefix inadvertently. To avoid the obvious ambiguity associated with such a collision, Maven will search a predetermined list of plugin groupIds for a given prefix, with the first match winning. So, if we want to add our new plugin to this search, we need to configure the list of plugin groupIds.</p><div class="section"><h4>Configuring Plugin-Prefix Searching<a name="Configuring_Plugin-Prefix_Searching"></a></h4><p>In order to reference our new plugin by prefix, we need to add its groupId to the <tt><pluginGroups/></tt> list in the <tt>settings.xml</tt> file. As you probably know, this file is usually found under $HOME/.m2. The added section to make our plugin's groupId searchable should look like this:</p><div class="source"><pre>~/.m2/settings.xml:
+------------------------------
+
+<settings>
+ .
+ .
+ .
+ <pluginGroups>
+ <pluginGroup>org.myproject.plugins</pluginGroup>
+ </pluginGroups>
+ .
+ .
+ .
+</settings></pre></div></div><div class="section"><h4>Run It<a name="Run_It"></a></h4><p>We can check that this worked by invoking our new mojo once again, this time using the prefix syntax:</p><div class="source"><pre>mvn hello:hello</pre></div></div></div><div class="section"><h3>Adding Plugin Parameters<a name="Adding_Plugin_Parameters"></a></h3><p>Now, suppose it's not enough that our plugin display static text to the console. Suppose we need it to display a greeting that is a little more personalized. We can easily add support for this by adding a <b>name</b> parameter. For good measure, we'll output the current project's name as well.</p><div class="section"><h4>Change the Ant Script<a name="Change_the_Ant_Script"></a></h4><p>The build script will have to change to output the new information:</p><div class="source"><pre>hello.build.xml:
+--------------------------------
+
+<project>
+ <target name="hello">
+ <echo>Hello, ${name}. You're building project: ${projectName}</echo>
+ </target>
+</project></pre></div></div><div class="section"><h4>Change the Mapping Document<a name="Change_the_Mapping_Document"></a></h4><p>Now that we have a build script which requires two new parameters, we have to tell the mapping document about them, so they will be injected into the Ant Project instance.</p><div class="source"><pre>hello.mojos.xml:
+------------------------------
+
+<pluginMetadata>
+ <mojos>
+ <mojo>
+ <goal>hello</goal>
+
+ <!-- this element refers to the Ant target we'll invoke -->
+ <call>hello</call>
+
+ <requiresProject>true</requiresProject>
+
+ <description>
+ Say Hello, including the user's name, and print the project name to the console.
+ </description>
+ <parameters>
+ <parameter>
+ <name>name</name>
+ <property>name</property>
+ <required>true</required>
+ <expression>${name}</expression>
+ <type>java.lang.String</type>
+ <description>The name of the user to greet.</description>
+ </parameter>
+
+ <parameter>
+ <name>projectName</name>
+ <property>projectName</property>
+ <required>true</required>
+ <readonly>true</readonly>
+ <defaultValue>${project.name}</defaultValue>
+ <type>java.lang.String</type>
+ <description>The name of the project currently being built.</description>
+ </parameter>
+ </parameters>
+ </mojo>
+ </mojos>
+</pluginMetadata></pre></div><p>You'll notice several differences from the old version of the mapping document. First, we've added <b>requiresProject="true"</b> to the mojo declaration. This tells Maven that our mojo requires a valid project before it can execute. In our case, we need a project so we can determine the correct <b>projectName</b> to use. Next, we've added two parameter declarations to our mojo mapping; one for <b>name</b> and another for <b>projectName</b>.</p><p>The <b>name</b> parameter declaration provides an expression attribute. This allows the user to specify <tt>-Dname=somename</tt> on the command line. Otherwise, the only way to configure this parameter would be through a <tt><configuration/></tt> element within the plugin specification in the user's POM. Note that this parameter is required to have a value before our mojo can execute.</p><p>The <b>projectName</b> parameter declaration provides two other interesting items. First,
it specifies a <tt>defaultValue</tt> attribute, which specifies an expression to be evaluated against Maven's current build state in order to extract the parameter's value. Second, it specifies a <tt>readonly</tt> attribute, which means the user cannot directly configure this parameter - either via command line or configuration within the POM. It can only be modified by modifying the build state referenced in the <tt>defaultValue</tt>. In our case, the name element of the POM. Also note that this parameter is declared to be required before our mojo can execute.</p></div><div class="section"><h4>Rebuild It and Run It<a name="Rebuild_It_and_Run_It"></a></h4><p>Now that we've modified our plugin, we have to rebuild it before running it again.</p><div class="source"><pre>mvn clean install</pre></div><p>Next, we should run the plugin again to verify that it's doing what we expect. However, before we can run it, we have some requirements to satisfy. First, we have to be sure we're
executing in the context of a valid Maven POM...runnning in the plugin's own project directory should satisfy that requirement. Then, we have to satisfy the name requirement. We can do this directly through the command line. So, the resulting invocation of our plugin will look like this:</p><div class="source"><pre>mvn -Dname=<your-name-here> hello:hello</pre></div><p>or, in my case:</p><div class="source"><pre>mvn -Dname=John hello:hello</pre></div><p>This should output the following:</p><div class="source"><pre>[echo] Hello, John. You're building project: Hello Plugin</pre></div></div></div><div class="section"><h3>Defining Multiple Mojos from One Build Script<a name="Defining_Multiple_Mojos_from_One_Build_Script"></a></h3><p>If you're familiar with Ant, you're probably familiar with the common usage pattern of defining multiple build types within a single build script. For instance, you might have a build type for cleaning the project, another for producing the app
lication JAR file, and yet another for producing the full distribution including Javadocs, etc.</p><p>The concept is pretty simple. Discrete chunks of the build process are separated into targets within the script. These targets can reference one another in order to make reuse within the build script possible.</p><p>These same concepts map pretty well to Maven, actually. However, instead of targets directly referencing one another, they would be bound to the appropriate phases of the build lifecycle. In this way, multiple Ant targets from the same build script can be reused piecemeal at different points in multiple build lifecycles (clean, site, and the main lifecycle are three examples).</p><p>This section will describe how to map multiple logical mojos onto different targets within the same Ant build script. It's also possible to reference targets from multiple build scripts, but we'll cover this later.</p><div class="section"><h4>Two Targets, One Script<a name="Two_Target
s_One_Script"></a></h4><p>To test this, we'll split our echo statement into two targets. Then, we'll reference each as separate mojos in the build. The new script looks like this:</p><div class="source"><pre>one-two.build.xml:
+--------------------------------
+
+<project>
+ <target name="one">
+ <echo>Hello, ${name}.</echo>
+ </target>
+
+ <target name="two">
+ <echo>You're building project: ${projectName}</echo>
+ </target>
+</project></pre></div></div><div class="section"><h4>Map the Mojos<a name="Map_the_Mojos"></a></h4><p>Next, we'll add new mapping document to map these two new mojos:</p><div class="source"><pre>one-two.mojos.xml:
+------------------------------
+
+<pluginMetadata>
+ <mojos>
+ <mojo>
+ <goal>one</goal>
+
+ <!-- this element refers to the Ant target we'll invoke -->
+ <call>one</call>
+
+ <description>
+ Say Hello. Include the user's name.
+ </description>
+ <parameters>
+ <parameter>
+ <name>name</name>
+ <property>name</property>
+ <required>true</required>
+ <expression>${name}</expression>
+ <type>java.lang.String</type>
+ <description>The name of the user to greet.</description>
+ </parameter>
+ </parameters>
+ </mojo>
+
+ <mojo>
+ <goal>two</goal>
+
+ <!-- this element refers to the Ant target we'll invoke -->
+ <call>two</call>
+ <requiresProject>true</requiresProject>
+
+ <description>
+ Write the project name to the console.
+ </description>
+ <parameters>
+ <parameter>
+ <name>projectName</name>
+ <property>projectName</property>
+ <required>true</required>
+ <readonly>true</readonly>
+ <defaultValue>${project.name}</defaultValue>
+ <type>java.lang.String</type>
+ <description>The name of the project currently being built.</description>
+ </parameter>
+ </parameters>
+ </mojo>
+ </mojos>
+</pluginMetadata></pre></div><p>Now that we've split the old functionality into two distinct mojos, there are some interesting consequences. Aside from the obvious, mojo <b>one</b> no longer requires a valid project instance in order to execute, since we only require the user's name in order to greet him.</p></div><div class="section"><h4>Build It, Run It<a name="Build_It_Run_It"></a></h4></div><div class="section"><h4>Rebuild It and Run It<a name="Rebuild_It_and_Run_It"></a></h4><p>Since we've modified our plugin, we have to rebuild it again before re-running it.</p><div class="source"><pre>mvn clean install</pre></div><p>Now that we have two separate mojos, we can execute them singly, or in any order we choose. We can bind them to phases of the lifecycle using plugin configuration inside the build element of a POM. We can execute them like this:</p><div class="source"><pre>mvn -Dname=John hello:one
+
+RETURNS:
+
+[echo] Hello, John.
+
+
+mvn hello:two (executed in the plugin's project directory)
+
+RETURNS:
+
+[echo] You're building project: Hello Plugin</pre></div><p>Alternatively, you could build a POM like this:</p><div class="source"><pre>test-project/pom.xml:
+----------------------------
+
+<project>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.myproject.tests</groupId>
+ <artifactId>hello-plugin-tests</artifactId>
+ <version>1.0</version>
+
+ <name>Test Project</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.myproject.plugins</groupId>
+ <artifactId>hello-plugin</artifactId>
+ <version>1.0-SNAPSHOT</version>
+
+ <configuration>
+ <name>John</name>
+ </configuration>
+
+ <executions>
+ <execution>
+ <phase>validate</phase>
+ <goals>
+ <goal>one</goal>
+ <goal>two</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project></pre></div><p>Then, simply call Maven on this new POM:</p><div class="source"><pre>cd test-project
+mvn validate</pre></div><p>You should see the following output:</p><div class="source"><pre>[echo] Hello, John.
+...
+[echo] You're building project: Test Project</pre></div></div><div class="section"><h4>A Note on Multiple Build Scripts<a name="A_Note_on_Multiple_Build_Scripts"></a></h4><p>It's worth mentioning that Ant-driven plugins can just as easily contain multiple Ant build scripts. Simply follow the naming rules - naming each <tt>A.build.xml</tt>, <tt>B.build.xml</tt>, <tt>C.build.xml</tt>, etc. for example - and be sure to provide a mapping document to correspond to each build script that contains a mojo (other build scripts may be contained in the plugin, and referenced by one of these; they don't need mapping documents). So, for the above examples (assuming they all contained mojo targets), you'd need: <tt>A.mojos.xml</tt>, <tt>B.mojos.xml</tt>, and <tt>C.mojos.xml</tt>. If <tt>C.build.xml</tt> was referenced by A and B, but didn't contain mojo targets, then you don't need a <tt>C.mojos.xml</tt> for obvious reasons.</p></div></div><div class="section"><h3>Advanced Usage<a name="A
dvanced_Usage"></a></h3><p>Below are some tips on some of the more advanced options related to Ant mojos.</p><div class="section"><h4>Component References<a name="Component_References"></a></h4><p>If your plugin needs a reference to a Plexus component, it will have to define something similar to the following in the mapping document:</p><div class="source"><pre><pluginMetadata>
+ <mojos>
+ <mojo>
+ .
+ .
+ .
+ <components>
+ <component>
+ <role>org.apache.maven.project.MavenProjectBuilder</role>
+ <hint>default</hint> <!-- This is optional -->
+ </component>
+ </components>
+ .
+ .
+ .
+ </mojo>
+ </mojos>
+</pluginMetadata></pre></div></div><div class="section"><h4>Forking New Lifecycles<a name="Forking_New_Lifecycles"></a></h4><p>In case your plugin needs to fork a new lifecycle, you can include the following in the mapping document:</p><div class="source"><pre><pluginMetadata>
+ <mojos>
+ <mojo>
+ .
+ .
+ .
+ <execute>
+ <lifecycle>my-custom-lifecycle</lifecycle>
+ <phase>package</phase>
+
+ <!-- OR -->
+
+ <goal>some:goal</goal>
+ </execute>
+ .
+ .
+ .
+ </mojo>
+ </mojos>
+</pluginMetadata></pre></div></div><div class="section"><h4>Deprecation<a name="Deprecation"></a></h4><p>As time goes on, you will likely have to deprecate part of your plugin. Whether it's a mojo parameter, or even an entire mojo, Maven can support it, and remind your users that the mojo or configuration they're using is deprecated, and print a message directing them to adjust their usage.</p><p>To deprecate a mojo parameter, simply add this:</p><div class="source"><pre><pluginMetadata>
+ <mojos>
+ <mojo>
+ .
+ .
+ .
+ <parameters>
+ <parameter>
+ .
+ .
+ .
+ <deprecated>Use this other parameter instead.</deprecated>
+ .
+ .
+ .
+ </parameter>
+ </parameters>
+ .
+ .
+ .
+ </mojo>
+ </mojos>
+</pluginMetadata></pre></div><p>To deprecate an entire mojo, add this:</p><div class="source"><pre><pluginMetadata>
+ <mojos>
+ <mojo>
+ .
+ .
+ .
+ <deprecated>Use this other mojo instead.</deprecated>
+ .
+ .
+ .
+ </mojo>
+ </mojos>
+</pluginMetadata></pre></div></div></div></div>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ © 2002-2012
+ The Apache Software Foundation
+
+ - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+ Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>