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 [36/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/maven1.html
==============================================================================
--- websites/staging/maventest/trunk/content/maven1.html (added)
+++ websites/staging/maventest/trunk/content/maven1.html Thu Mar 1 16:35:39 2012
@@ -0,0 +1,378 @@
+<!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>Information for Maven 1.0 Users</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="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>
+ >
+ Information for Maven 1.0 Users
+ </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. --><div class="section"><h2><a name="top">Information for Maven 1.0 Users</a><a name="Information_for_Maven_1.0_Users"></a></h2><ol style="list-style-type: decimal"><li><a href="#changed">What's Changed?</a></li><li><a href="#m1-or-m2">Should I use Maven 2.x, Maven 3.x, or Maven 1.0?</a></li><li><a href="#m1-future">What will happen to Maven 1.0?</a></li><li><a href="#m1-plugins">Will my Maven 1.0 plugins be supported?</a></li><li><a href="#m1-maven-xml">How do I write custom scripts without a
+ <tt>maven.xml</tt>
+ file?
+ </a></li><li><a href="#convert">How do I convert from Maven 1.x to Maven 2.x or 3.x?</a></li></ol></div><dl><dt><a name="changed">What's Changed?</a></dt><dd>
+ <p>
+ Maven 2.0 & 3.0 will feel very different to a Maven 1.0 user - and perhaps a little strange. But it is a lot simpler
+ to work with and closer to how Maven was always meant to be! The key changes from Maven 1.0 are:
+ </p>
+ <ul>
+ <li>
+ <i>Faster and smaller</i>
+ - The Maven core no longer uses Ant, Jelly or Xerces making it much smaller, has
+ fewer dependencies, and is perfect for embedding in other tools.
+ </li>
+ <li>
+ <i>Defined build lifecycle</i>
+ - No more <tt>prereqs</tt>, <tt>preGoals</tt> and <tt>postGoals</tt>.
+ The build is a series of well defined phases. This also means that the normal goal names are not used -
+ <tt>compile</tt>, <tt>test</tt> and <tt>install</tt>
+ work for any project type.
+ </li>
+ <li>
+ <i>Built-in multiple project handling</i>
+ - Use the same goals on a set of projects, and aggregate the
+ results.
+ </li>
+ <li>
+ <i>Improved <tt>SNAPSHOT</tt> handling</i>
+ - Snapshots are now checked for updates only once per day by
+ default - though can be configured to be once per build, on a particular interval, or never. A command line
+ option can force a check - making it more like updating from an SCM.
+ </li>
+ <li>
+ <i>No more properties files</i>
+ - All plugins are now configured from the POM (which is now called <tt>pom.xml</tt>).
+ </li>
+ <li>
+ <i>No more <tt>maven.xml</tt></i>
+ - Plugins are now easier to build and integrate, and are the only way
+ to script your builds. (Note that additions may later be made to the POM to allow simple things that
+ scripting
+ was used for, such as goal aliasing).
+ </li>
+ <li>
+ <i>No more Jelly</i>
+ - Plugins are primarily written in Java, though there are providers for other scripting languages.
+ </li>
+ <li>
+ <i>Improved repository layout</i>
+ - Maven 2.0 supports both the existing layout (not Maven 3), and an improved repository
+ layout that has deeper, partitioned structure making it easier to browse.
+ </li>
+ </ul>
+ <p align="right"><a href="#top">[top]</a></p><hr /></dd><dt><a name="m1-or-m2">Should I use Maven 2.x, Maven 3.x, or Maven 1.0?</a></dt><dd>
+ <p>
+ Maven 3.x is the latest stable release, and we certainly recommend it for all new projects.
+ </p>
+ <p>
+ If you are already using Maven 1.0 - you should try out Maven 3.x, as it is very much improved.
+ However, we still continue to support the Maven 1.x releases at this time.
+ </p>
+ <p>
+ If you do use Maven 1.0, and would like to upgrade in the future, you should carefully consider following some
+ of the
+ <a class="externalLink" href="http://maven.apache.org/maven-1.x/using/bestpractices.html">Best Practices</a>
+ listed. These will make your project a lot easier to migrate in the future.
+ </p>
+ <p>
+ The following are the known limitations in the current Maven 2.x release compared to Maven 1.x: none.
+ </p>
+ <p>
+ The following are the known limitations in the current Maven 3.x release compared to Maven 1.x:
+ </p>
+ <ul>
+ <li>Maven 1 repository layout is not supported</li>
+ </ul>
+ <p align="right"><a href="#top">[top]</a></p><hr /></dd><dt><a name="m1-future">What will happen to Maven 1.0?</a></dt><dd>
+ <p>
+ Support for Maven 1.0.2 has been discontinued with the release of Maven 1.1.
+ While significant new features will not be added to the
+ <a class="externalLink" href="http://maven.apache.org/maven-1.x/">Maven 1.x</a> core
+ (such as transitive dependencies), bugfixes and support continue and the
+ repository is still available.
+ </p>
+ <p align="right"><a href="#top">[top]</a></p><hr /></dd><dt><a name="m1-plugins">Will my Maven 1.0 plugins be supported?</a></dt><dd>
+ <p>
+ Not directly.
+ </p>
+ <p>
+ We recommend building your Jelly plugins as thin wrappers around Java beans that do not use Maven 1.0 API's,
+ which will allow easy migration to Maven 2.0.
+ </p>
+ <p align="right"><a href="#top">[top]</a></p><hr /></dd><dt><a name="m1-maven-xml">How do I write custom scripts without a
+ <tt>maven.xml</tt>
+ file?
+ </a></dt><dd>
+ <p>Taken from
+ <a class="externalLink" href="http://mail-archives.apache.org/mod_mbox/maven-users/200504.mbox/%3c1113788711.5625.30.camel@172.16.1.36%3e">
+ this post to the Maven User's List</a>:
+ </p>
+ <blockquote>
+ Everything in m2 is a plugin so for doing any sort of custom work like
+ that you will need to make a plugin. This 1) greatly reduces the
+ complexity within m2 because we only deal with proper plugins. The
+ maven.xml file in m1 was a pseudo plugin essentially and greatly
+ complicated the internals and 2) it promotes the sharing of your work
+ right from the get go. To start with you'll probably write a plugin that
+ is only applicable to your specific requirements, or your team's work,
+ but you'll see people asking for some functionality and you'll go "hey,
+ I have something like that!" and hopefully people who have concrete
+ solutions will generalize their solutions so they can be shared with
+ others. That's what we're trying to encourage.
+ </blockquote>
+ <blockquote>
+ We estimate that there's a lot of work bound up in project's maven.xml
+ that is not being shared and we'd like to try and change that. We plan
+ to make it dead simple to share plugins and hopefully people can use
+ other project's plugins as a start for a plugin that they may need
+ themselves.
+ </blockquote>
+ <p align="right"><a href="#top">[top]</a></p><hr /></dd><dt><a name="convert">How do I convert from Maven 1.x to Maven 2.x or 3.x?</a></dt><dd>
+ This is discussed in <a class="externalLink" href="http://maven.apache.org/guides/mini/guide-m1-m2.html">Guide to Moving from Maven 1.x to Maven 2.x</a>
+ (Maven 3.x is mostly equivalent to Maven 2.x).
+ <p align="right"><a href="#top">[top]</a></p></dd></dl>
+ </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/netbeans-module.html
==============================================================================
--- websites/staging/maventest/trunk/content/netbeans-module.html (added)
+++ websites/staging/maventest/trunk/content/netbeans-module.html Thu Mar 1 16:35:39 2012
@@ -0,0 +1,242 @@
+<!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 Support for NetBeans</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="Milos Kleint, Jesse Glick" />
+ <meta name="Date-Creation-yyyymmdd" content="20111026" />
+ <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 Support for NetBeans
+ </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">
+ <strong>NetBeans</strong>
+ </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 Support for NetBeans<a name="Maven_Support_for_NetBeans"></a></h2><p>NetBeans includes full Maven support since 6.7, including Maven 3 support in 7.0+. You can open any Maven project in the IDE and start coding immediately. For more information see the <a class="externalLink" href="http://wiki.netbeans.org/Maven">NetBeans.org wiki page</a>.</p></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/pdf-config.xml
==============================================================================
--- websites/staging/maventest/trunk/content/pdf-config.xml (added)
+++ websites/staging/maventest/trunk/content/pdf-config.xml Thu Mar 1 16:35:39 2012
@@ -0,0 +1,24 @@
+<xsl:stylesheet
+ version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format">
+
+<xsl:attribute-set name="figure.graphics">
+ <xsl:attribute name="content-width">scale-down-to-fit</xsl:attribute>
+ <xsl:attribute name="content-height">scale-down-to-fit</xsl:attribute>
+ <xsl:attribute name="width">100%</xsl:attribute>
+ <xsl:attribute name="height">100%</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:attribute-set name="base.pre.style">
+ <xsl:attribute name="font-family">monospace</xsl:attribute>
+ <xsl:attribute name="wrap-option">no-wrap</xsl:attribute>
+ <xsl:attribute name="keep-together">auto</xsl:attribute>
+ <xsl:attribute name="white-space-collapse">false</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:attribute-set name="body.pre" use-attribute-sets="base.pre.style">
+ <xsl:attribute name="font-size">9pt</xsl:attribute>
+</xsl:attribute-set>
+
+</xsl:stylesheet>
Added: websites/staging/maventest/trunk/content/plugin-developers/common-bugs.html
==============================================================================
--- websites/staging/maventest/trunk/content/plugin-developers/common-bugs.html (added)
+++ websites/staging/maventest/trunk/content/plugin-developers/common-bugs.html Thu Mar 1 16:35:39 2012
@@ -0,0 +1,368 @@
+<!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>Common Bugs and Pitfalls</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="Benjamin Bentmann" />
+ <meta name="Date-Creation-yyyymmdd" content="20080829" />
+ <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>
+ >
+ Common Bugs and Pitfalls
+ </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 --><div class="section"><h2>Common Bugs and Pitfalls<a name="Common_Bugs_and_Pitfalls"></a></h2><p>Maven is not the smallest project in terms of source code and has as such already suffered from many bugs. Having a closer look at all the issues revealed some coding problems that had widespread among the various subcomponents. This document lists these commonly occurring anti patterns in order to help the Maven community to prevent rather than fix bugs. Note that the primary focus is on pointing out problems that are subtle in their nature rather than giving a comprehensive guide for Java or Maven development.</p><ul><li><a href="#Reading_and_Writing_Text_Files">Reading and Writing Text Files</a></li><li><a href="#Converting_between_URLs_and_Filesystem_Paths">Converting between URLs and Filesystem Paths</a></li><li><a href="#Handling_Strings_Case-insensitively">Handling Strings Case-insensitively</a></li><li><a href="#Creating_Resource_Bundle_Families">Cre
ating Resource Bundle Families</a></li><li><a href="#Using_System_Properties">Using System Properties</a></li><li><a href="#Using_Shutdown_Hooks">Using Shutdown Hooks</a></li><li><a href="#Resolving_Relative_Paths">Resolving Relative Paths</a></li><li><a href="#Determining_the_Output_Directory_for_a_Site_Report">Determining the Output Directory for a Site Report</a></li><li><a href="#Retrieving_the_Mojo_Logger">Retrieving the Mojo Logger</a></li><li><a href="#Depending_on_Plexus_Utilities_1.1">Depending on Plexus Utilities 1.1+</a></li></ul><div class="section"><h3><a name="Reading_and_Writing_Text_Files">Reading and Writing Text Files</a></h3><p>Textual content is composed of characters while file systems merely store byte streams. A file encoding (aka charset) is used to convert between bytes and characters. The challenge is using the right file encoding.</p><p>The JVM has this notion of a default encoding (given by the <tt>file.encoding</tt> property) which it derives fro
m a system's locale. While this might be a convenient feature sometimes, using this default encoding for a project build is in general a bad idea: The build output will depend on the machine/developer who runs the build. As such, usage of the default encoding threatens the dream of a reproducible build.</p><p>For example, if developer A has UTF-8 as default encoding while developer B uses ISO-8859-1, text files are very likely to get messed up during resource filtering or similar tasks.</p><p>Therefore, developers should avoid any direct or indirect usage of the classes/methods that simply employ the platform's default encoding. For instance, <tt>FileWriter</tt> and <tt>FileReader</tt> should usually be avoided:</p><div class="source"><pre>/*
+ * FIXME: This assumes the source file is using the platform's default encoding.
+ */
+Reader reader = new FileReader( javaFile );</pre></div><p>Instead, the classes <tt>OutputStreamWriter</tt> and <tt>OutputStreamReader</tt> can be used in combination with an explicit encoding value. This encoding value can be retrieved from a mojo parameter such that the user can configure the plugin to fit his/her needs.</p><p>To save the user from configuring each plugin individually, conventions have been established that allow a user to centrally configure the file encoding per POM. Plugin developers should respect these conventions whereever possible:</p><ul><li><a class="externalLink" href="http://docs.codehaus.org/display/MAVENUSER/POM+Element+for+Source+File+Encoding">Source File Encoding</a></li><li><a class="externalLink" href="http://cwiki.apache.org/confluence/display/MAVENOLD/Reporting+Encoding+Configuration">Report Output Encoding</a></li></ul><p>Finally note that XML files require special handling because they are equipped with an encoding declaration in the X
ML prolog. Reading or writing XML files with an encoding that does not match their XML prolog's <tt>encoding</tt> attribute is a bad idea:</p><div class="source"><pre>/*
+ * FIXME: This assumes the XML encoding declaration matches the platform's default encoding.
+ */
+Writer writer = new FileWriter( xmlFile );
+writer.write( xmlContent );</pre></div><p>To ease the correct processing of XML files, developers are encouraged to use <tt><a class="externalLink" href="http://plexus.codehaus.org/plexus-utils/apidocs/org/codehaus/plexus/util/ReaderFactory.html#newXmlReader(java.io.File)">ReaderFactory.newXmlReader()</a></tt> and <tt><a class="externalLink" href="http://plexus.codehaus.org/plexus-utils/apidocs/org/codehaus/plexus/util/WriterFactory.html#newXmlWriter(java.io.File)">WriterFactory.newXmlWriter()</a></tt> from the Plexus Utilities.</p></div><div class="section"><h3><a name="Converting_between_URLs_and_Filesystem_Paths">Converting between URLs and Filesystem Paths</a></h3><p>URLs and filesystem paths are really two different things and converting between them is not trivial. The main source of problems is that different encoding rules apply for the strings that make up a URL or filesystem path. For example, consider the following code snippet and its associated console output:</
p><div class="source"><pre>File file = new File( "foo bar+foo" );
+URL url = file.toURI().toURL();
+
+System.out.println( file.toURL() );
+> file:/C:/temp/foo bar+foo
+
+System.out.println( url );
+> file:/C:/temp/foo%20bar+foo
+
+System.out.println( url.getPath() );
+> /C:/temp/foo%20bar+foo
+
+System.out.println( URLDecoder.decode( url.getPath(), "UTF-8" ) );
+> /C:/temp/foo bar foo</pre></div><p>First of all, please note that <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/io/File.html#toURL()">File.toURL()</a></tt> does not escape the space character (and others). This yields an invalid URL, as per <a class="externalLink" href="http://www.faqs.org/rfcs/rfc2396.html">RFC 2396, section 2.4.3 "Excluded US-ASCII Characters"</a>. The class <tt>java.net.URL</tt> will silently accept such invalid URLs, in contrast <tt>java.net.URI</tt> will not (see also <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/net/URL.html#toURI()">URL.toURI()</a></tt>). For this reason, <tt>File.toURL()</tt> has been deprecated and should be replaced with <tt>File.toURI().toURL()</tt>.</p><p>Next, <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/net/URL.html#getPath()">URL.getPath()</a></tt> does in general not return a string that can be used as a filesystem pat
h. It returns a substring of the URL and as such can contain escape sequences. The prominent example is the space character which will show up as "%20". People sometimes hack around this by means of <tt>replace("%20", " ")</tt> but that does simply not cover all cases. It's worth to mention that on the other hand the related method <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/net/URI.html#getPath()">URI.getPath()</a></tt> does decode escapes but still the result is not a filesystem path (compare the source for the constructor <tt>File(URI)</tt>). To summarize, the following idiom is to be avoided:</p><div class="source"><pre>URL url = new URL( "file:/C:/Program%20Files/Java/bin/java.exe" );
+
+/*
+ * FIXME: This does not decode percent encoded characters.
+ */
+File path = new File( url.getPath() );</pre></div><p>To decode a URL, people sometimes also choose <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/net/URLDecoder.html">java.net.URLDecoder</a></tt>. The pitfall with this class is that is actually performs HTML form decoding which is yet another encoding and not the same as the URL encoding (compare the last paragraph in class javadoc about <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/net/URL.html">java.net.URL</a></tt>). For instance, a <tt>URLDecoder</tt> will erroneously convert the character "+" into a space as illustrated by the last sysout in the example above.</p><p>In an ideal world, code targetting JRE 1.4+ could easily avoid these problems by using the constructor <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/io/File.html#File(java.net.URI)">File(URI)</a></tt> as suggested by the following snippet:</p><div class="sou
rce"><pre>URL url = new URL( "file:/C:/Documents and Settings/user/.m2/settings.xml" );
+
+/*
+ * FIXME: This assumes the URL is fully compliant with RFC 3986.
+ */
+File path = new File( new URI( url.toExternalForm() ) );</pre></div><p>The remaining source of frustration is the conversion from <tt>URL</tt> to <tt>URI</tt>. As already said, the <tt>URL</tt> class accepts malformed URLs which will make the constructor of <tt>URI</tt> throw an exception. And indeed, class loaders from Sun JREs up to Java 1.4 will deliver malformed URLs when queried for a resource. Likewise, the class loaders employed by Maven 2.x deliver malformed resource URLs regardless of the JRE version (see <a class="externalLink" href="http://jira.codehaus.org/browse/MNG-3607">MNG-3607</a>).</p><p>For all these reasons, it is recommended to use <tt><a class="externalLink" href="http://commons.apache.org/io/api-release/org/apache/commons/io/FileUtils.html#toFile(java.net.URL)">FileUtils.toFile()</a></tt> from Commons IO or <tt><a class="externalLink" href="http://plexus.codehaus.org/plexus-utils/apidocs/org/codehaus/plexus/util/FileUtils.html#toFile(java.net.URL)">Fil
eUtils.toFile()</a></tt> from a recent Plexus Utilities.</p></div><div class="section"><h3><a name="Handling_Strings_Case-insensitively">Handling Strings Case-insensitively</a></h3><p>When developers need to compare strings without regard to case or want to realize a map with case-insensitive string keys, they often employ <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/lang/String.html#toLowerCase()">String.toLowerCase()</a></tt> or <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/lang/String.html#toUpperCase()">String.toUpperCase()</a></tt> to create a "normalized" string before doing a simple <tt>String.equals()</tt>. Now, the <tt>to*Case()</tt> methods are overloaded: One takes no arguments and one takes a <tt>Locale</tt> object.</p><p>The gotcha with the arg-less methods is that their output depends on the default locale of the JVM but the default locale is out of control of the developer. That means the
string expected by the developer (who runs/tests his code in a JVM using locale <tt>xy</tt>) does not necessarily match the string seen by another user (that runs a JVM with locale <tt>ab</tt>). For example, the comparison shown in the next code snippet is likely to fail for systems with default locale Turkish because Turkish has unusual casing rules for the characters "i" and "I":</p><div class="source"><pre>/*
+ * FIXME: This assumes the casing rules of the current platform
+ * match the rules for the English locale.
+ */
+if ( "info".equals( debugLevel.toLowerCase() ) )
+ logger.info( message );</pre></div><p>For case-insensitive string comparisions which should be locale-insensitive, the method <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/lang/String.html#equalsIgnoreCase(java.lang.String)">String.equalsIgnoreCase()</a></tt> should be used instead. If only a substring like a prefix/suffix should be compared, the method <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/lang/String.html#regionMatches(boolean,%20int,%20java.lang.String,%20int,%20int)">String.regionMatches()</a></tt> can be used instead.</p><p>If the usage of <tt>String.to*Case()</tt> cannot be avoided, the overloaded version taking a <tt>Locale</tt> object should be used, passing in <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/util/Locale.html#ENGLISH">Locale.ENGLISH</a></tt>. The resulting code will still run on Non-English systems, the parameter only locks down the casing rules used
for the string comparison such that the code delivers the same results on all platforms.</p></div><div class="section"><h3><a name="Creating_Resource_Bundle_Families">Creating Resource Bundle Families</a></h3><p>Especially reporting plugins employ resource bundles to support internationalization. One language (usually English) is provided as the fallback/default language in the base resource bundle. Due to the lookup strategy performed by <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/util/ResourceBundle.html#getBundle(java.lang.String,%20java.util.Locale,%20java.lang.ClassLoader)">ResourceBundle.getBundle()</a></tt>, one must always provide a dedicated resource bundle for this default language, too. This bundle should be empty because it inherits the strings via the parent chain from the base bundle, but it must exist.</p><p>The following example illustrates this requirement. Imagine the broken resource bundle family shown below which is inten
ded to provide localization for English, German and French:</p><div class="source"><pre>src/
++- main/
+ +- resources/
+ +- mymojo-report.properties
+ +- mymojo-report_de.properties
+ +- mymojo-report_fr.properties</pre></div><p>Now, if a resource bundle is to be looked up for English on a JVM whose default locale happens to be French, the bundle <tt>mymojo-report_fr.properties</tt> will be loaded instead of the intended bundle <tt>mymojo-report.properties</tt>.</p><p>Reporting plugins that suffer from this bug can easily be detected by executing <tt>mvn site -D locales=xy,en</tt> where <tt>xy</tt> denotes any other language code supported by the particular plugin. Specifying <tt>xy</tt> as the first locale will have the Maven Site Plugin change the JVM's default locale to <tt>xy</tt> which in turn causes the lookup for <tt>en</tt> to fail as outlined above unless the plugin has a dedicated resource bundle for English.</p></div><div class="section"><h3><a name="Using_System_Properties">Using System Properties</a></h3><p>Maven's command line supports the definition of system properties via arguments of the form <tt>-D key=value</tt>. While these prop
erties are called system properties, plugins should never use <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/lang/System.html#getProperty(java.lang.String)">System.getProperty()</a></tt> and related methods to query these properties. For example, the following code snippet will not work reliably when Maven is embedded, say into an IDE or a CI server:</p><div class="source"><pre>public MyMojo extends AbstractMojo
+{
+ public void execute()
+ {
+ /*
+ * FIXME: This prevents proper embedding into IDEs or CI systems.
+ */
+ String value = System.getProperty( "maven.test.skip" );
+ }
+}</pre></div><p>The problem is that the properties managed by the <tt>System</tt> class are global, i.e. shared among all threads in the current JVM. To prevent conflicts with other code running in the same JVM, Maven plugins should instead query the execution properties. These can be obtained from <tt><a class="externalLink" href="http://maven.apache.org/ref/current/maven-core/apidocs/org/apache/maven/execution/MavenSession.html#getExecutionProperties()">MavenSession.getExecutionProperties()</a></tt>.</p></div><div class="section"><h3><a name="Using_Shutdown_Hooks">Using Shutdown Hooks</a></h3><p>People occasionally employ shutdown hooks to perform cleanup tasks, e.g. to delete temporary files as shown in the example below:</p><div class="source"><pre>public MyMojo extends AbstractMojo
+{
+ public void execute()
+ {
+ File tempFile = File.createTempFile( "temp", null );
+ /*
+ * FIXME: This assumes the JVM terminates soon after
+ * the Maven build has finished.
+ */
+ tempFile.deleteOnExit();
+ }
+}</pre></div><p>The problem is that the JVM executing Maven can be running much longer than the actual Maven build. Of course, this does not apply to the standalone invocation of Maven from the command line. However, it affects the embedded usage of Maven in IDEs or CI servers. In those cases, the cleanup tasks will be deferred, too. If the JVM is then executing a bunch of other Maven builds, many such cleanup tasks can sum up, eating up resources of the JVM.</p><p>For this reason, plugin developers should avoid usage of shutdown hooks and rather use <tt>try</tt>/<tt>finally</tt> blocks to perform cleanup as soon as the resources are no longer needed.</p></div><div class="section"><h3><a name="Resolving_Relative_Paths">Resolving Relative Paths</a></h3><p>It is common practice for users of Maven to specify relative paths in the POM, not to mention that the Super POM does so, too. The intention is to resolve such relative paths against the base directory of the current project
. In other words, the paths <tt>target/classes</tt> and <tt>${basedir}/target/classes</tt> should resolve to the same directory for a given POM.</p><p>Unfortunately, the class <tt><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/io/File.html">java.io.File</a></tt> does not resolve relative paths against the project's base directory. As mentioned in its class javadoc, it resolves relative paths against the current working directory. In plain English: Unless a Maven component has complete control over the current working directory, any usage of <tt>java.io.File</tt> in combination with a relative path is a bug.</p><p>At first glance, one might be tempted to argue that the project base directory is equal to the current working directory. However, this assumption is generally not true. Consider the following scenarios:</p><ol style="list-style-type: lower-alpha"><li>Reactor Builds<p>When a child module is build during a reactor build, the current working
directory is usually the base directory of the parent project, not the base directory of the current module. That is the most common scenario where users are faced with the bug.</p></li><li>Embedded Maven Invocations<p>Other tools, most notably IDEs, that run Maven under the hood may have set the current working directory to their installation folder or whatever they like.</p></li><li>Maven Invocations using the <tt>-f</tt> Switch<p>While it is surely an uncommon use-case, the user is free to invoke Maven from an arbitrary working directory by specifying an absolute path like <tt>mvn -f /home/me/projects/demo/pom.xml</tt>.</p></li></ol><p>Hence this example code is prone to misbehave:</p><div class="source"><pre>public MyMojo extends AbstractMojo
+{
+ /**
+ * @parameter
+ */
+ private String outputDirectory;
+
+ public void execute()
+ {
+ /*
+ * FIXME: This will resolve relative paths like "target/classes" against
+ * the user's working directory instead of the project's base directory.
+ */
+ File outputDir = new File( outputDirectory ).getAbsoluteFile();
+ }
+}</pre></div><p>In order to guarantee reliable builds, Maven and its plugins must manually resolve relative paths against the project's base directory. A simple idiom like the following will do just fine:</p><div class="source"><pre>File file = new File( path );
+if ( !file.isAbsolute() )
+{
+ file = new File( project.getBasedir(), file );
+}</pre></div><p>Many Maven plugins can get this resolution automatically if they declare their affected mojo parameters of type <tt>java.io.File</tt> instead of <tt>java.lang.String</tt>. This subtle difference in parameter types will trigger a feature known as <i>path translation</i>, i.e. the Maven core will automatically resolve relative paths when it pumps the XML configuration into a mojo.</p></div><div class="section"><h3><a name="Determining_the_Output_Directory_for_a_Site_Report">Determining the Output Directory for a Site Report</a></h3><p>Most reporting plugins inherit from <tt>AbstractMavenReport</tt>. In doing so, they need to implement the inherited but abstract method <tt>getOutputDirectory()</tt>. To implement this method, plugins usually declare a field named <tt>outputDirectory</tt> which they return in the method. Nothing wrong so far.</p><p>Now, some plugins need to create additional files in the report output directory that accompany the report generated
via the sink interface. While it is tempting to use either the method <tt>getOutputDirectory()</tt> or the field <tt>outputDirectory</tt> directly in order to setup a path for the output files, this leads most likely to a bug. More precisely, those plugins will not properly output files when run by the Maven Site Plugin as part of the site lifecycle. This is best noticed when the output directory for the site is configured directly in the Maven Site Plugin such that it deviates from the expression <tt>${project.reporting.outputDirectory}</tt> that the plugins use by default. Multi-language site generation is another scenario to exploit this bug which is illustrated below:</p><div class="source"><pre>public MyReportMojo extends AbstractMavenReport
+{
+ /**
+ * @parameter default-value="${project.reporting.outputDirectory}"
+ */
+ private File outputDirectory;
+
+ protected String getOutputDirectory()
+ {
+ return outputDirectory.getAbsolutePath();
+ }
+
+ public void executeReport( Locale locale )
+ {
+ /*
+ * FIXME: This assumes the mojo parameter reflects the effective
+ * output directory as used by the Maven Site Plugin.
+ */
+ outputDirectory.mkdirs();
+ }
+}</pre></div><p>There are in principal two situations in which a report mojo could be invoked. The mojo might be run directly from the command line or the default build lifecycle or it might be run indirectly as part of the site generation along with other report mojos. The glaring difference between these two invocations is the way the output directory is controlled. In the first case, the parameter <tt>outputDirectory</tt> from the mojo itself is used. In the second case however, the Maven Site Plugin takes over control and will set the output directory according to its own configuration by calling <tt>MavenReport.setReportOutputDirectory()</tt> on the reports being generated.</p><p>Therefore, developers should always use <tt>MavenReport.getReportOutputDirectory()</tt> if they need to query the effective output directory for the report. The implementation of <tt>AbstractMavenReport.getOutputDirectory()</tt> is only intended as a fallback in case the mojo is not run as part
of the site generation.</p></div><div class="section"><h3><a name="Retrieving_the_Mojo_Logger">Retrieving the Mojo Logger</a></h3><p>Maven employs an IoC container named Plexus to setup a plugin's mojos before their execution. In other words, components required by a mojo will be provided by means of dependency injection, more precisely field injection. The important point to keep in mind is that this field injection happens <i>after</i> the mojo's constructor has finished. This means that references to injected components are invalid during the construction time of the mojo.</p><p>For example, the next snippet tries to retrieve the mojo logger during construction time but the mojo logger is an injected component and as such has not been properly initialized yet:</p><div class="source"><pre>public MyMojo extends AbstractMojo
+{
+ /*
+ * FIXME: This will retrieve a wrong logger instead of the intended mojo logger.
+ */
+ private Log log = getLog();
+
+ public void execute()
+ {
+ log.debug( "..." );
+ }
+}</pre></div><p>In case of the logger, the above mojo will simply use a default console logger, i.e. the code defect is not immediately noticeable by a <tt>NullPointerException</tt>. This default logger will however use a different message format for its output and also outputs debug messages even if Maven's debug mode was not enabled. For this reason, developers must not try to cache the logger during construction time. The method <tt>getLog()</tt> is fast enough and can simply be called whenever one needs it.</p></div><div class="section"><h3><a name="Depending_on_Plexus_Utilities_1.1">Depending on Plexus Utilities 1.1+</a></h3><p>Up to Maven 2.0.5, version 1.1 of the artifact <tt>plexus-utils</tt> was included in the Maven core class loader which is shared with the plugin class realm. This effectively prevented plugins from using another/newer version of <tt>plexus-utils</tt>. This has been solved starting with Maven 2.0.6 by shading (most of) the classes from <tt>plexus-
utils</tt> (see <a class="externalLink" href="http://jira.codehaus.org/browse/MNG-2892">MNG-2892</a>).</p><p>In short, plugins that strictly require a newer version of <tt>plexus-utils</tt> also require Maven 2.0.6 as a minimum. Hence, a POM snippet for a Maven plugin like shown below is misleading:</p><div class="source"><pre><project>
+ <packaging>maven-plugin</packaging>
+ ...
+ <prerequisites>
+ <!-- FIXME: This assumes the plugin works with plexus-utils:1.1, too -->
+ <maven>2.0</maven>
+ </prerequisites>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>org.codehaus.plexus</groupId>
+ <artifactId>plexus-utils</artifactId>
+ <version>1.5.6</version>
+ </dependency>
+ </dependencies>
+ ...
+</project></pre></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>
Added: websites/staging/maventest/trunk/content/plugin-developers/cookbook/add-build-time-to-manifest.html
==============================================================================
--- websites/staging/maventest/trunk/content/plugin-developers/cookbook/add-build-time-to-manifest.html (added)
+++ websites/staging/maventest/trunk/content/plugin-developers/cookbook/add-build-time-to-manifest.html Thu Mar 1 16:35:39 2012
@@ -0,0 +1,286 @@
+<!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>Cookbook - How To Add Build Time To A JAR Manifest</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="Vincent Siveton" />
+ <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>
+ >
+ Cookbook - How To Add Build Time To A JAR Manifest
+ </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>Cookbook: How To Add Build Time To A JAR Manifest?<a name="Cookbook:_How_To_Add_Build_Time_To_A_JAR_Manifest"></a></h2><div class="section"><h3>Summary<a name="Summary"></a></h3><p>This recipe describes how to add build time to a JAR manifest by calling <a class="externalLink" href="http://ant.apache.org">Apache Ant</a> tasks.</p></div><div class="section"><h3>Prerequisite Plugins<a name="Prerequisite_Plugins"></a></h3><p>Here is the list of the plugins used:</p><table border="1" class="bodyTable"><tr class="a"><th align="left"><b>Plugin</b></th><th align="left"><b>Version</b></th></tr><tr class="b"><td align="left"><a href="../../plugins/maven-antrun-plugin/"> <tt>antrun</tt></a></td><td align="left">1.1</td></tr><tr class="a"><td align="left"><a href="../../plugins/maven-jar-plugin/"> <tt>jar</tt></a></td><td align="left">2.2</td></tr></table></div><div class="section"><h3>Sample Generated Manifest<a name="Sample_Generated_Manifest"></a></h
3><div class="source"><pre>Manifest-Version: 1.0
+Archiver-Version: Plexus Archiver
+Created-By: Apache Maven
+Built-By: vsiveton
+Build-Jdk: 1.5.0_12
+Build-Time: 2008-01-18 06:53:13</pre></div></div><div class="section"><h3>Recipe<a name="Recipe"></a></h3><div class="section"><h4>Configuring MANIFEST.MF<a name="Configuring_MANIFEST.MF"></a></h4><p>To generate and add build time into a Jar Manifest, we are using <tt>MANIFEST.MF</tt>, located in the <tt>src/main/resources/META-INF</tt> directory, which contains a built time value to be interpolated, i.e.</p><div class="source"><pre>Build-Time: ${build.time}</pre></div></div><div class="section"><h4>Configuring The POM<a name="Configuring_The_POM"></a></h4><p>The value ${build.time} from the <tt>MANIFEST.MF</tt> will be filtering by Maven due to the <filtering> element. The value is taken from the file <tt>${basedir}/target/filter.properties</tt>, listed by the <filter> element, i.e.</p><div class="source"><pre> <resources>
+ <resource>
+ <directory>src/main/resources</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+
+ <filters>
+ <filter>${basedir}/target/filter.properties</filter>
+ </filters>
+</pre></div></div><div class="section"><h4>Configuring Maven Antrun Plugin<a name="Configuring_Maven_Antrun_Plugin"></a></h4><p>The <tt>filter.properties</tt> file will be generated by the Antrun plugin. We use two core Ant Tasks, <a class="externalLink" href="http://ant.apache.org/manual/CoreTasks/tstamp.html"><tstamp></a> and <a class="externalLink" href="http://ant.apache.org/manual/CoreTasks/echo.html"><echo></a>.</p><div class="source"><pre> <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <executions>
+ <execution>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ <configuration>
+ <tasks>
+ <!-- Safety -->
+ <mkdir dir="${project.build.directory}"/>
+
+ <tstamp>
+ <format property="last.updated" pattern="yyyy-MM-dd hh:mm:ss"/>
+ </tstamp>
+ <echo file="${basedir}/target/filter.properties" message="build.time=${last.updated}"/>
+ </tasks>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+</pre></div></div><div class="section"><h4>Configuring Maven Jar Plugin<a name="Configuring_Maven_Jar_Plugin"></a></h4><p>The last configuration is to set the <tt>defaultManifestFile</tt> to <tt>true</tt> to enable it.</p><div class="source"><pre><plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-jar-plugin</artifactId>
+ <configuration>
+ <useDefaultManifestFile>true</useDefaultManifestFile>
+ </configuration>
+</plugin>
+</pre></div></div><div class="section"><h4>Running Maven<a name="Running_Maven"></a></h4><p>Just call Maven to generate the package:</p><div class="source"><pre>mvn package</pre></div></div></div><div class="section"><h3>Other Tips<a name="Other_Tips"></a></h3><p>You could tweak the Jar Plugin configuration into the War Plugin.</p></div><div class="section"><h3>Resources<a name="Resources"></a></h3><ul><li>Source code: <a class="externalLink" href="http://svn.apache.org/repos/asf/maven/sandbox/trunk/site/cookbook/generate-build-time">http://svn.apache.org/repos/asf/maven/sandbox/trunk/site/cookbook/generate-build-time</a></li><li><a href="../../plugins/maven-antrun-plugin/"> Maven Antrun Plugin</a></li><li><a href="../../plugins/maven-jar-plugin/"> Maven Jar Plugin</a></li></ul></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>