Modified: maven/website/content/plugin-developers/common-bugs.html ============================================================================== --- maven/website/content/plugin-developers/common-bugs.html (original) +++ maven/website/content/plugin-developers/common-bugs.html Sun May 12 07:42:36 2024 @@ -2,17 +2,17 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/plugin-developers/common-bugs.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/plugin-developers/common-bugs.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Benjamin Bentmann" /> <meta name="date" content="2008-08-29" /> - <title>Maven</title> + <title>Maven â Common Bugs and Pitfalls</title> <link rel="stylesheet" href="../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../css/site.css" /> <link rel="stylesheet" href="../css/print.css" media="print" /> @@ -39,10 +39,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href=".././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -50,9 +48,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugin-developers/common-bugs.apt";><img src="../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Common Bugs and Pitfalls <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugin-developers/common-bugs.apt";><img src="../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../download.cgi" title="Download">Download</a></li> @@ -143,7 +140,7 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Common_Bugs_and_Pitfalls"></a> +<section> <h1>Common Bugs and Pitfalls</h1> <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> @@ -161,25 +158,25 @@ <p>The JVM has this notion of a default encoding (given by the <code>file.encoding</code> property) which it derives from 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, <code>FileWriter</code> and <code>FileReader</code> should usually be avoided:</p> -<pre><code>/* +<div class="verbatim source"><pre class="prettyprint linenums">/* * FIXME: This assumes the source file is using the platform's default encoding. */ -Reader reader = new FileReader( javaFile );</code></pre> +Reader reader = new FileReader( javaFile );</pre></div> <p>Instead, the classes <code>OutputStreamWriter</code> and <code>OutputStreamReader</code> 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="https://cwiki.apache.org/confluence/display/MAVEN/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 XML prolog. Reading or writing XML files with an encoding that does not match their XML prolog's <code>encoding</code> attribute is a bad idea:</p> -<pre><code>/* +<div class="verbatim source"><pre class="prettyprint linenums">/* * FIXME: This assumes the XML encoding declaration matches the platform's default encoding. */ Writer writer = new FileWriter( xmlFile ); -writer.write( xmlContent );</code></pre> +writer.write( xmlContent );</pre></div> <p>To ease the correct processing of XML files, developers are encouraged to use <code><a class="externalLink" href="https://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util/ReaderFactory.html#newXmlReader(java.io.File)">ReaderFactory.newXmlReader()</a></code> and <code><a class="externalLink" href="https://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util/WriterFactory.html#newXmlWriter(java.io.File)">WriterFactory.newXmlWriter()</a></code> from the Plexus Utilities.</p></section><section> <h2><a id="Converting_between_URLs_and_Filesystem_Paths">Converting between URLs and Filesystem Paths</a></h2> <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> -<pre><code>File file = new File( "foo bar+foo" ); +<div class="verbatim source"><pre class="prettyprint linenums">File file = new File( "foo bar+foo" ); URL url = file.toURI().toURL(); System.out.println( file.toURL() ); @@ -192,50 +189,51 @@ System.out.println( url.getPath() ); > /C:/temp/foo%20bar+foo System.out.println( URLDecoder.decode( url.getPath(), "UTF-8" ) ); -> /C:/temp/foo bar foo</code></pre> +> /C:/temp/foo bar foo</pre></div> <p>First of all, please note that <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/io/File.html#toURL()">File.toURL()</a></code> 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 <code>java.net.URL</code> will silently accept such invalid URLs, in contrast <code>java.net.URI</code> will not (see also <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/net/URL.html#toURI()">URL.toURI()</a></code>). For this reason, <code>File.toURL()</code> has been deprecated and should be replaced with <code>File.toURI().toURL()</code>.</p> <p>Next, <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/net/URL.html#getPath()">URL.getPath()</a></code> does in general not return a string that can be used as a filesystem path. 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 <code>replace("%20", " ")</code> but that does simply not cover all cases. It's worth to mention that on the other hand the related method <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/net/URI.html#getPath()">URI.getPath()</a></code> does decode escapes but still the result is not a filesystem path (compare the source for the constructor <code>File(URI)</code>). To summarize, the following idiom is to be avoided:</p> -<pre><code>URL url = new URL( "file:/C:/Program%20Files/Java/bin/java.exe" ); +<div class="verbatim source"><pre class="prettyprint linenums">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() );</code></pre> +File path = new File( url.getPath() );</pre></div> <p>To decode a URL, people sometimes also choose <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/net/URLDecoder.html";>java.net.URLDecoder</a></code>. 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 <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/net/URL.html";>java.net.URL</a></code>). For instance, a <code>URLDecoder</code> 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 <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/io/File.html#File(java.net.URI)">File(URI)</a></code> as suggested by the following snippet:</p> -<pre><code>URL url = new URL( "file:/C:/Documents and Settings/user/.m2/settings.xml" ); +<div class="verbatim source"><pre class="prettyprint linenums">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() ) );</code></pre> +File path = new File( new URI( url.toExternalForm() ) );</pre></div> <p>The remaining source of frustration is the conversion from <code>URL</code> to <code>URI</code>. As already said, the <code>URL</code> class accepts malformed URLs which will make the constructor of <code>URI</code> 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="https://issues.apache.org/jira/browse/MNG-3607";>MNG-3607</a>).</p> <p>For all these reasons, it is recommended to use <code><a class="externalLink" href="http://commons.apache.org/io/api-release/org/apache/commons/io/FileUtils.html#toFile(java.net.URL)">FileUtils.toFile()</a></code> from Commons IO or <code><a class="externalLink" href="https://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util/FileUtils.html#toFile(java.net.URL)">FileUtils.toFile()</a></code> from a recent Plexus Utilities.</p></section><section> <h2><a id="Handling_Strings_Case-insensitively">Handling Strings Case-insensitively</a></h2> <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 <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/lang/String.html#toLowerCase()">String.toLowerCase()</a></code> or <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/lang/String.html#toUpperCase()">String.toUpperCase()</a></code> to create a "normalized" string before doing a simple <code>String.equals()</code>. Now, the <code>to*Case()</code> methods are overloaded: One takes no arguments and one takes a <code>Locale</code> 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 <code>xy</code>) does not necessarily match the string seen by another user (that runs a JVM with locale <code>ab</code>). 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> -<pre><code>/* +<div class="verbatim source"><pre class="prettyprint linenums">/* * 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 );</code></pre> + logger.info( message );</pre></div> <p>For case-insensitive string comparisons which should be locale-insensitive, the method <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/lang/String.html#equalsIgnoreCase(java.lang.String)">String.equalsIgnoreCase()</a></code> should be used instead. If only a substring like a prefix/suffix should be compared, the method <code><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></code> can be used instead.</p> <p>If the usage of <code>String.to*Case()</code> cannot be avoided, the overloaded version taking a <code>Locale</code> object should be used, passing in <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/util/Locale.html#ENGLISH";>Locale.ENGLISH</a></code>. 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></section><section> <h2><a id="Creating_Resource_Bundle_Families">Creating Resource Bundle Families</a></h2> <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 <code><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></code>, 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 intended to provide localization for English, German and French:</p> +<div class="verbatim"> <pre>src/ +- main/ +- resources/ +- mymojo-report.properties +- mymojo-report_de.properties - +- mymojo-report_fr.properties</pre> + +- 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 <code>mymojo-report_fr.properties</code> will be loaded instead of the intended bundle <code>mymojo-report.properties</code>.</p> <p>Reporting plugins that suffer from this bug can easily be detected by executing <code>mvn site -D locales=xy,en</code> where <code>xy</code> denotes any other language code supported by the particular plugin. Specifying <code>xy</code> as the first locale will have the Maven Site Plugin change the JVM's default locale to <code>xy</code> which in turn causes the lookup for <code>en</code> to fail as outlined above unless the plugin has a dedicated resource bundle for English.</p></section><section> <h2><a id="Using_System_Properties">Using System Properties</a></h2> <p>Maven's command line supports the definition of system properties via arguments of the form <code>-D key=value</code>. While these properties are called system properties, plugins should never use <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/lang/System.html#getProperty(java.lang.String)">System.getProperty()</a></code> 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> -<pre><code>public MyMojo extends AbstractMojo +<div class="verbatim source"><pre class="prettyprint linenums">public MyMojo extends AbstractMojo { public void execute() { @@ -244,11 +242,11 @@ if ( "info".equals( debugLevel */ String value = System.getProperty( "maven.test.skip" ); } -}</code></pre> +}</pre></div> <p>The problem is that the properties managed by the <code>System</code> 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 <code><a class="externalLink" href="https://maven.apache.org/ref/current/maven-core/apidocs/org/apache/maven/execution/MavenSession.html#getExecutionProperties()">MavenSession.getExecutionProperties()</a></code>.</p></section><section> <h2><a id="Using_Shutdown_Hooks">Using Shutdown Hooks</a></h2> <p>People occasionally employ shutdown hooks to perform cleanup tasks, e.g. to delete temporary files as shown in the example below:</p> -<pre><code>public MyMojo extends AbstractMojo +<div class="verbatim source"><pre class="prettyprint linenums">public MyMojo extends AbstractMojo { public void execute() { @@ -259,14 +257,14 @@ if ( "info".equals( debugLevel */ tempFile.deleteOnExit(); } -}</code></pre> +}</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 <code>try</code>/<code>finally</code> blocks to perform cleanup as soon as the resources are no longer needed.</p></section><section> <h2><a id="Resolving_Relative_Paths">Resolving Relative Paths</a></h2> <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 <code>target/classes</code> and <code>${project.basedir}/target/classes</code> should resolve to the same directory for a given POM.</p> <p>Unfortunately, the class <code><a class="externalLink" href="http://java.sun.com/javase/6/docs/api/java/io/File.html";>java.io.File</a></code> 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 <code>java.io.File</code> 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;"> +<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 @@ -274,7 +272,7 @@ if ( "info".equals( debugLevel <li>Maven Invocations using the <code>-f</code> 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 <code>mvn -f /home/me/projects/demo/pom.xml</code>.</p></li></ol> <p>Hence this example code is prone to misbehave:</p> -<pre><code>public MyMojo extends AbstractMojo +<div class="verbatim source"><pre class="prettyprint linenums">public MyMojo extends AbstractMojo { /** * @parameter @@ -289,18 +287,18 @@ if ( "info".equals( debugLevel */ File outputDir = new File( outputDirectory ).getAbsoluteFile(); } -}</code></pre> +}</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> -<pre><code>File file = new File( path ); +<div class="verbatim source"><pre class="prettyprint linenums">File file = new File( path ); if ( !file.isAbsolute() ) { file = new File( project.getBasedir(), file ); -}</code></pre> +}</pre></div> <p>Many Maven plugins can get this resolution automatically if they declare their affected mojo parameters of type <code>java.io.File</code> instead of <code>java.lang.String</code>. 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></section><section> <h2><a id="Determining_the_Output_Directory_for_a_Site_Report">Determining the Output Directory for a Site Report</a></h2> <p>Most reporting plugins inherit from <code>AbstractMavenReport</code>. In doing so, they need to implement the inherited but abstract method <code>getOutputDirectory()</code>. To implement this method, plugins usually declare a field named <code>outputDirectory</code> 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 <code>getOutputDirectory()</code> or the field <code>outputDirectory</code> 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 <code>${project.reporting.outputDirectory}</code> that the plugins use by default. Multi-language site generation is another scenario to exploit this bug which is illustrated below:</p> -<pre><code>public MyReportMojo extends AbstractMavenReport +<div class="verbatim source"><pre class="prettyprint linenums">public MyReportMojo extends AbstractMavenReport { /** * @parameter default-value="${project.reporting.outputDirectory}" @@ -320,13 +318,13 @@ if ( !file.isAbsolute() ) */ outputDirectory.mkdirs(); } -}</code></pre> +}</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 <code>outputDirectory</code> 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 <code>MavenReport.setReportOutputDirectory()</code> on the reports being generated.</p> <p>Therefore, developers should always use <code>MavenReport.getReportOutputDirectory()</code> if they need to query the effective output directory for the report. The implementation of <code>AbstractMavenReport.getOutputDirectory()</code> is only intended as a fallback in case the mojo is not run as part of the site generation.</p></section><section> <h2><a id="Retrieving_the_Mojo_Logger">Retrieving the Mojo Logger</a></h2> <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> -<pre><code>public MyMojo extends AbstractMojo +<div class="verbatim source"><pre class="prettyprint linenums">public MyMojo extends AbstractMojo { /* * FIXME: This will retrieve a wrong logger instead of the intended mojo logger. @@ -337,7 +335,7 @@ if ( !file.isAbsolute() ) { log.debug( "..." ); } -}</code></pre> +}</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 <code>NullPointerException</code>. 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 <code>getLog()</code> is fast enough and can simply be called whenever one needs it. +---</p></section></section> </main> </div>
Modified: maven/website/content/plugin-developers/cookbook/index.html ============================================================================== --- maven/website/content/plugin-developers/cookbook/index.html (original) +++ maven/website/content/plugin-developers/cookbook/index.html Sun May 12 07:42:36 2024 @@ -2,18 +2,18 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/plugin-developers/cookbook/index.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/plugin-developers/cookbook/index.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Brett Porter" /> <meta name="author" content="Vincent Siveton" /> <meta name="date" content="2009-08-02" /> - <title>Maven</title> + <title>Maven â Plugins Cookbook</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -40,10 +40,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -51,9 +49,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugin-developers/cookbook/index.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Plugins Cookbook <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugin-developers/cookbook/index.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -132,7 +129,7 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Maven_Extensions_Cookbook"></a> +<section> <h1>Maven Extensions Cookbook</h1> <p>Extensions are based on components, defined either with Plexus or JSR-330:</p> <ul> Modified: maven/website/content/plugin-developers/cookbook/plexus-plugin-upgrade.html ============================================================================== --- maven/website/content/plugin-developers/cookbook/plexus-plugin-upgrade.html (original) +++ maven/website/content/plugin-developers/cookbook/plexus-plugin-upgrade.html Sun May 12 07:42:36 2024 @@ -2,17 +2,17 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/plugin-developers/cookbook/plexus-plugin-upgrade.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/plugin-developers/cookbook/plexus-plugin-upgrade.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Hervé Boutemy" /> <meta name="date" content="2012-06-02" /> - <title>Maven</title> + <title>Maven â Cookbook - How To Upgrade from Plexus Javadoc Tags to Plexus Java Annotations</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../../css/site.css" /> <link rel="stylesheet" href="../../css/print.css" media="print" /> @@ -39,10 +39,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href="../.././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -50,9 +48,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugin-developers/cookbook/plexus-plugin-upgrade.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Cookbook - How To Upgrade from Plexus Javadoc Tags to Plexus Java Annotations <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugin-developers/cookbook/plexus-plugin-upgrade.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li> @@ -143,15 +140,15 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Cookbook.3A_How_To_Upgrade_from_Plexus_Javadoc_Tags_to_Plexus_Java_Annotations.3F"></a> -<h1>Cookbook: How To Upgrade from Plexus Javadoc Tags to Plexus Java Annotations?</h1><section><a id="Summary"></a> +<section> +<h1>Cookbook: How To Upgrade from Plexus Javadoc Tags to Plexus Java Annotations?</h1><section> <h2>Summary</h2> <p>This recipe describes how to upgrade from Plexus Javadoc Tags to Plexus Java Annotations when defining a Plexus component.</p> <p>This is done in 2 steps:</p> -<ol style="list-style-type: decimal;"> +<ol style="list-style-type: decimal"> <li>replace the <a class="externalLink" href="https://codehaus-plexus.github.io/plexus-maven-plugin/";>deprecated <code>plexus-maven-plugin</code></a>, which only supports Plexus Javadoc Tags, with its <a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/";>successor: <code>plexus-component-metadata</code></a>, which support both Plexus Javadoc Tags and Plexus Java Annotations,</li> <li>update sources with <a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/";>Java Annotations for Plexus</a>.</li></ol> -<p><b>Notice</b>: if you're targeting components for Maven 3.1.0+, using <a href="/maven-jsr330.html"><code>@Named</code>/<code>@Inject</code> JSR-330 annotations</a> instead of <code>@Component</code>/<code>@Requirement</code> Plexus Java Annotations may be a good next step</p></section><section><a id="Prerequisite_Plugins"></a> +<p><b>Notice</b>: if you're targeting components for Maven 3.1.0+, using <a href="/maven-jsr330.html"><code>@Named</code>/<code>@Inject</code> JSR-330 annotations</a> instead of <code>@Component</code>/<code>@Requirement</code> Plexus Java Annotations may be a good next step</p></section><section> <h2>Prerequisite Plugins</h2> <p>Here is the list of the plugins used:</p> <table class="table table-bordered table-striped"> @@ -163,7 +160,7 @@ <td style="text-align: left;">1.3.8</td></tr> <tr class="a"> <td style="text-align: left;"><a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-metadata/";><code>plexus-component-metadata</code></a></td> -<td style="text-align: left;">1.7.1</td></tr></table></section><section><a id="Equivalence_Table"></a> +<td style="text-align: left;">1.7.1</td></tr></table></section><section> <h2>Equivalence Table</h2> <table class="table table-bordered table-striped"> <tr class="a"> @@ -205,11 +202,11 @@ <tr class="b"> <th>source annotations</th> <td style="text-align: center;">javadoc tags:  <br /><code>@plexus.component</code>, <code>@plexus.requirement</code>, <code>@plexus.configuration</code>  </td> -<td style="text-align: center;">javadoc tags + <a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/";><code>plexus-component-annotations</code></a> Java 5 annotations: <br /><a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Component.html";><code>@Component</code></a>, <a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Requirement.html";><code>@Requirement</code></a>, <a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Configuration.html";><code>@Configuration</code></a>,</td></tr></table></section><section><a id="Recipe"></a> -<h2>Recipe</h2><section><a id="Plugin_Configuration"></a> +<td style="text-align: center;">javadoc tags + <a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/";><code>plexus-component-annotations</code></a> Java 5 annotations: <br /><a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Component.html";><code>@Component</code></a>, <a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Requirement.html";><code>@Requirement</code></a>, <a class="externalLink" href="https://codehaus-plexus.github.io/plexus-containers/plexus-component-annotations/apidocs/org/codehaus/plexus/component/annotations/Configuration.html";><code>@Configuration</code></a>,</td></tr></table></section><section> +<h2>Recipe</h2><section> <h3>Plugin Configuration</h3> <p>In your <code>pom.xml</code>, replace <code>plexus-maven-plugin</code> configuration:</p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> <build> <plugins> <plugin> @@ -225,9 +222,9 @@ </executions> </plugin> </build> -</project></code></pre> +</project></pre></div> <p>with corresponding <code>plexus-component-metadata</code> configuration:</p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> <build> <plugins> <plugin> @@ -243,11 +240,11 @@ </executions> </plugin> </build> -</project></code></pre> -<p>If <code>merge-descriptors</code> is used, move the handwritten xml file to <code>${project.basedir}/src/main/resources/META-INF/plexus</code>.</p></section><section><a id="Replacing_Plexus_Javadoc_Tags_with_Plexus_Java_5_Annotations"></a> +</project></pre></div> +<p>If <code>merge-descriptors</code> is used, move the handwritten xml file to <code>${project.basedir}/src/main/resources/META-INF/plexus</code>.</p></section><section> <h3>Replacing Plexus Javadoc Tags with Plexus Java 5 Annotations</h3> <p>In your <code>pom.xml</code>, add <code>plexus-component-annotations</code> dependency:</p> -<pre><code><project> +<div class="verbatim source"><pre class="prettyprint linenums"><project> <dependencies> <dependency> <groupId>org.codehaus.plexus</groupId> @@ -255,9 +252,9 @@ <version>1.7.1</version> </dependency> </dependencies> -</project></code></pre> +</project></pre></div> <p>In your java sources, replace javadoc tags:</p> -<pre><code>/** +<div class="verbatim source"><pre class="prettyprint linenums">/** * @plexus.component role="foo.MyComponent" role-hint="hint-value" */ public class MyComponentImplementation @@ -267,9 +264,9 @@ public class MyComponentImplementation * @plexus.requirement */ private InjectedComponent; -}</code></pre> +}</pre></div> <p>with corresponding Java 5 annotations</p> -<pre><code>import org.codehaus.plexus.component.annotations.Component; +<div class="verbatim source"><pre class="prettyprint linenums">import org.codehaus.plexus.component.annotations.Component; import org.codehaus.plexus.component.annotations.Requirement; @Component( role = MyComponent.class, hint = "hint-value" ) @@ -278,7 +275,7 @@ public class MyComponentImplementation { @Requirement private InjectedComponent; -}</code></pre></section></section></section> +}</pre></div></section></section></section> </main> </div> </div> Modified: maven/website/content/plugin-developers/index.html ============================================================================== --- maven/website/content/plugin-developers/index.html (original) +++ maven/website/content/plugin-developers/index.html Sun May 12 07:42:36 2024 @@ -2,17 +2,17 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/plugin-developers/index.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/plugin-developers/index.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Brett Porter" /> <meta name="date" content="2008-01-01" /> - <title>Maven</title> + <title>Maven â Plugin Developers Centre</title> <link rel="stylesheet" href="../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../css/site.css" /> <link rel="stylesheet" href="../css/print.css" media="print" /> @@ -39,10 +39,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href=".././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -50,9 +48,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugin-developers/index.apt";><img src="../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Plugin Developers Centre <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugin-developers/index.apt";><img src="../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../download.cgi" title="Download">Download</a></li> @@ -143,7 +140,7 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Plugin_Developers_Centre"></a> +<section> <h1>Plugin Developers Centre</h1> <p>This documentation centre is for those who are developing Maven plugins. This might be for your own build, or as an accompaniment to your third party tool.</p> <p><b>What is a Mojo?</b> A mojo is a <b>M</b>aven plain <b>O</b>ld <b>J</b>ava <b>O</b>bject. Each mojo is an executable <i>goal</i> in Maven, and a plugin is a distribution of one or more related mojos.</p> @@ -153,13 +150,13 @@ <li><a href="../guides/plugin/guide-java-report-plugin-development.html"> Your First Report Mojo</a> - Learn how to write your first reporting plugin</li> <li><a href="./plugin-testing.html"> Testing your Plugin</a> - How to write tests for your plugins</li> <li>TODO: creating and using custom packaging (like <a href="/archetype/archetype-packaging/"><code>maven-archetype</code> packaging</a>)</li> -<li><a href="./common-bugs.html"> Common Bugs and Pitfalls</a> - Overview of problematic coding patterns</li></ul><section><a id="Reference"></a> +<li><a href="./common-bugs.html"> Common Bugs and Pitfalls</a> - Overview of problematic coding patterns</li></ul><section> <h2>Reference</h2> <ul> <li><a href="../developers/mojo-api-specification.html"> Mojo API and Annotation Reference</a></li> <li><a href="/plugin-tools/maven-plugin-tools-annotations/index.html"> Maven Plugin Tools and annotations</a></li> <li><a href="../ref/current/index.html"> Maven API Reference</a></li> -<li><a href="../guides/mini/guide-maven-classloading.html"> Maven Class Loading</a></li></ul></section><section><a id="Extensions"></a> +<li><a href="../guides/mini/guide-maven-classloading.html"> Maven Class Loading</a></li></ul></section><section> <h2>Extensions</h2> <ul> <li><a href="../examples/maven-3-lifecycle-extensions.html">Maven 3 lifecycle extensions</a></li> Modified: maven/website/content/plugin-developers/plugin-testing.html ============================================================================== --- maven/website/content/plugin-developers/plugin-testing.html (original) +++ maven/website/content/plugin-developers/plugin-testing.html Sun May 12 07:42:36 2024 @@ -2,18 +2,18 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/plugin-developers/plugin-testing.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/plugin-developers/plugin-testing.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Vincent Siveton" /> <meta name="date" content="2008-01-01 2015-06-16" /> - <title>Maven</title> + <title>Maven â Developers centre - Testing Plugins Strategies</title> <link rel="stylesheet" href="../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../css/site.css" /> <link rel="stylesheet" href="../css/print.css" media="print" /> @@ -40,10 +40,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href=".././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -51,9 +49,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugin-developers/plugin-testing.apt";><img src="../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Developers centre - Testing Plugins Strategies <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugin-developers/plugin-testing.apt";><img src="../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../download.cgi" title="Download">Download</a></li> @@ -144,25 +141,25 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Introduction"></a> +<section> <h1>Introduction</h1> -<p>Currently, Maven only supports unit testing out of the box. This document is intended to help Maven Developers test plugins with unit tests, integration tests, and functional tests.</p></section><section><a id="Testing_Styles.3A_Unit_Testing_vs._Functional.2FIntegration_Testing"></a> +<p>Currently, Maven only supports unit testing out of the box. This document is intended to help Maven Developers test plugins with unit tests, integration tests, and functional tests.</p></section><section> <h1>Testing Styles: Unit Testing vs. Functional/Integration Testing</h1> <p>A unit test attempts to verify a mojo as an isolated unit, by mocking out the rest of the Maven environment. A mojo unit test does not attempt to run your plugin in the context of a real Maven build. Unit tests are designed to be fast.</p> <p>A functional/integration test attempts to use a mojo in a real Maven build, by launching a real instance of Maven in a real project. Normally this requires you to construct special dummy Maven projects with real POM files. Often this requires you to have already installed your plugin into your local repository so it can be used in a real Maven build. Functional tests run much more slowly than unit tests, but they can catch bugs that you may not catch with unit tests.</p> -<p>The general wisdom is that your code should be mostly tested with unit tests, but should also have some functional tests.</p></section><section><a id="Unit_Tests"></a> -<h1>Unit Tests</h1><section><a id="Using_JUnit_alone"></a> +<p>The general wisdom is that your code should be mostly tested with unit tests, but should also have some functional tests.</p></section><section> +<h1>Unit Tests</h1><section> <h2>Using JUnit alone</h2> <p>In principle, you can write a unit test of a plugin Mojo the same way you'd write any other JUnit test case, by writing a class that <code>extends TestCase</code>.</p> -<p>However, most mojos need more information to work properly. For example, you'll probably need to inject a reference to a MavenProject, so your mojo can query project variables.</p></section><section><a id="Using_PlexusTestCase"></a> +<p>However, most mojos need more information to work properly. For example, you'll probably need to inject a reference to a MavenProject, so your mojo can query project variables.</p></section><section> <h2>Using PlexusTestCase</h2> <p>Mojo variables are injected using Plexus, and many Mojos are written to take specific advantage of the Plexus container (by executing a lifecycle or having various injected dependencies).</p> <p>If all you need are Plexus container services, you can write your class with <code>extends PlexusTestCase</code> instead of TestCase.</p> -<p>With that said, if you need to inject Maven objects into your mojo, you'll probably prefer to use the maven-plugin-testing-harness.</p></section><section><a id="maven-plugin-testing-harness"></a> +<p>With that said, if you need to inject Maven objects into your mojo, you'll probably prefer to use the maven-plugin-testing-harness.</p></section><section> <h2>maven-plugin-testing-harness</h2> <p>The <a href="/plugin-testing/maven-plugin-testing-harness/">maven-plugin-testing-harness</a> is explicitly intended to test the <code>org.apache.maven.reporting.AbstractMavenReport#execute()</code> implementation.</p> <p>In general, you need to include <code>maven-plugin-testing-harness</code> as a dependency, and create a *MojoTest (by convention) class which <code>extends AbstractMojoTestCase</code>.</p> -<pre><code>... +<div class="verbatim source"><pre class="prettyprint linenums">... <dependencies> ... <dependency> @@ -173,8 +170,8 @@ </dependency> ... </dependencies> -...</code></pre> -<pre><code>public class YourMojoTest +...</pre></div> +<div class="verbatim source"><pre class="prettyprint linenums">public class YourMojoTest extends AbstractMojoTestCase { /** @@ -198,17 +195,17 @@ assertNotNull( mojo ); } -}</code></pre> -<p>For more information, refer to <a class="externalLink" href="http://cwiki.apache.org/confluence/display/MAVENOLD/Maven+Plugin+Harness";>Maven Plugin Harness Wiki</a></p></section></section><section><a id="Integration.2FFunctional_testing"></a> -<h1>Integration/Functional testing</h1><section><a id="maven-verifier"></a> +}</pre></div> +<p>For more information, refer to <a class="externalLink" href="http://cwiki.apache.org/confluence/display/MAVENOLD/Maven+Plugin+Harness";>Maven Plugin Harness Wiki</a></p></section></section><section> +<h1>Integration/Functional testing</h1><section> <h2>maven-verifier</h2> <p>maven-verifier tests are run using JUnit or TestNG, and provide a simple class allowing you to launch Maven and assert on its log file and built artifacts. It also provides a ResourceExtractor, which extracts a Maven project from your src/test/resources directory into a temporary working directory where you can do tricky stuff with it. Follow the <a href="/shared/maven-verifier/getting-started.html">Getting Started</a> guide to learn more about creating maven-verifier tests.</p> <p>Maven itself uses maven-verifier to run its core integration tests. For more information, please refer to <a class="externalLink" href="https://cwiki.apache.org/confluence/display/MAVEN/Creating+a+Maven+Integration+Test";>Creating a Maven Integration Test</a>.</p> -<p><b>Note</b>: maven-verifier and maven-verifier-plugin sound similar, but are totally different unrelated pieces of code. maven-verifier-plugin simply verifies the existence/absence of files on the filesystem. You could use it for functional testing, but you may need more features than maven-verifier-plugin provides.</p></section><section><a id="maven-invoker-plugin"></a> +<p><b>Note</b>: maven-verifier and maven-verifier-plugin sound similar, but are totally different unrelated pieces of code. maven-verifier-plugin simply verifies the existence/absence of files on the filesystem. You could use it for functional testing, but you may need more features than maven-verifier-plugin provides.</p></section><section> <h2>maven-invoker-plugin</h2> <p>You can use <a class="externalLink" href="https://maven.apache.org/plugins/maven-invoker-plugin/";>maven-invoker-plugin</a> to invoke Maven and to provide some BeanShell/Groovy tests. Tests written in this way don't run under JUnit/TestNG; instead, they're run by Maven itself.</p> <p>You can take a look at the <a class="externalLink" href="https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-install-plugin/src/it/";>maven-install-plugin</a> how there are integration tests are written.</p> -<pre><code><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<div class="verbatim source"><pre class="prettyprint linenums"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> ... <build> @@ -236,7 +233,7 @@ </plugins> </build> ... -</project></code></pre></section></section> +</project></pre></div></section></section> </main> </div> </div> Modified: maven/website/content/plugins/index.html ============================================================================== --- maven/website/content/plugins/index.html (original) +++ maven/website/content/plugins/index.html Sun May 12 07:42:36 2024 @@ -2,14 +2,14 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/plugins/index.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/plugins/index.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Brett Porter" /> <meta name="author" content="Jason van Zyl" /> <meta name="author" content="Dennis Lundberg" /> @@ -17,7 +17,7 @@ <meta name="author" content="Benson Margulies" /> <meta name="author" content="Karl-Heinz Marbaise" /> <meta name="date" content="2017-05-05" /> - <title>Maven</title> + <title>Maven â Available Plugins</title> <link rel="stylesheet" href="../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../css/site.css" /> <link rel="stylesheet" href="../css/print.css" media="print" /> @@ -44,10 +44,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href=".././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -55,9 +53,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugins/index.apt";><img src="../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Available Plugins <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugins/index.apt";><img src="../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../download.cgi" title="Download">Download</a></li> @@ -136,12 +133,12 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Available_Plugins"></a> +<section> <h1>Available Plugins</h1> <p>Maven is - at its heart - a plugin execution framework; all work is done by plugins. Looking for a specific goal to execute? This page lists the core plugins and others. There are the build and the reporting plugins:</p> <ul> <li><b>Build plugins</b> will be executed during the build and they should be configured in the <code><build/></code> element from the POM.</li> -<li><b>Reporting plugins</b> will be executed during the site generation and they should be configured in the <code><reporting/></code> element from the POM. Because the result of a Reporting plugin is part of the generated site, Reporting plugins should be both internationalized and localized. You can read more about the <a href="./localization.html">localization of our plugins</a> and how you can help.</li></ul><section><a id="Supported_By_The_Maven_Project"></a> +<li><b>Reporting plugins</b> will be executed during the site generation and they should be configured in the <code><reporting/></code> element from the POM. Because the result of a Reporting plugin is part of the generated site, Reporting plugins should be both internationalized and localized. You can read more about the <a href="./localization.html">localization of our plugins</a> and how you can help.</li></ul><section> <h2>Supported By The Maven Project</h2> <p>To see the most up-to-date list browse the Maven repository, specifically the <a class="externalLink" href="https://repo.maven.apache.org/maven2/org/apache/maven/plugins/";> <code>org/apache/maven/plugins</code></a> subdirectory. <i>(Plugins are organized according to a directory structure that resembles the standard Java package naming convention)</i></p> <table class="table table-bordered table-striped"> @@ -611,7 +608,7 @@ <td style="text-align: left;"><a class="externalLink" href="https://issues.apache.org/jira/browse/MWRAPPER";>Jira MWRAPPER</a></td></tr></table> <p>* <b>B</b>uild or <b>R</b>eporting plugin</p> <p>There are also some sandbox plugins into our <a class="externalLink" href="https://svn.apache.org/repos/asf/maven/sandbox/trunk/plugins";>source repository</a>.</p> -<p>Previous archived versions of plugins reference documentations are <a href="../plugins-archives/">located here</a>.</p></section><section><a id="Retired"></a> +<p>Previous archived versions of plugins reference documentations are <a href="../plugins-archives/">located here</a>.</p></section><section> <h2>Retired</h2> <table class="table table-bordered table-striped"> <tr class="a"> @@ -661,7 +658,7 @@ <td style="text-align: left;">B</td> <td style="text-align: left;">2.4</td> <td style="text-align: left;">2019-04-30</td> -<td style="text-align: left;">Plugin to help with repository-based tasks.</td></tr></table></section><section><a id="Outside_The_Maven_Land"></a> +<td style="text-align: left;">Plugin to help with repository-based tasks.</td></tr></table></section><section> <h2>Outside The Maven Land</h2><section> <h3>At MojoHaus (formerly known as <a id="codehaus.org">codehaus.org</a>)</h3> <p>There are also <a class="externalLink" href="https://www.mojohaus.org/plugins.html";>many plug-ins</a> available at the <a class="externalLink" href="https://github.com/mojohaus";> MojoHaus</a> project at GitHub.</p> @@ -705,7 +702,7 @@ <td style="text-align: left;">Generate a list of tasks based on tags in your code.</td></tr> <tr class="a"> <td style="text-align: left;"><a class="externalLink" href="https://www.mojohaus.org/versions-maven-plugin/";> <code>versions</code></a></td> -<td style="text-align: left;">Manage versions of your project, its modules, dependencies and plugins.</td></tr></table></section><section><a id="Misc"></a> +<td style="text-align: left;">Manage versions of your project, its modules, dependencies and plugins.</td></tr></table></section><section> <h3>Misc</h3> <p>A number of other projects provide their own Maven plugins. This includes:</p> <table class="table table-bordered table-striped"> @@ -752,9 +749,9 @@ <tr class="a"> <td style="text-align: left;"><a class="externalLink" href="https://www.simplify4u.org/pgpverify-maven-plugin/";> <code>pgpverify</code></a></td> <td style="text-align: left;"><a class="externalLink" href="https://www.simplify4u.org/";>Simplify4U</a></td> -<td style="text-align: left;">Verify PGP signature of all project dependencies.</td></tr></table></section></section><section><a id="Resources"></a> +<td style="text-align: left;">Verify PGP signature of all project dependencies.</td></tr></table></section></section><section> <h2>Resources</h2> -<ol style="list-style-type: decimal;"> +<ol style="list-style-type: decimal"> <li><a href="../guides/mini/guide-configuring-plugins.html">Guide to Configuring Plugins</a></li></ol></section></section> </main> </div> Modified: maven/website/content/plugins/localization.html ============================================================================== --- maven/website/content/plugins/localization.html (original) +++ maven/website/content/plugins/localization.html Sun May 12 07:42:36 2024 @@ -2,18 +2,18 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M18 from content/apt/plugins/localization.apt at 2024-05-11 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M10 from content/apt/plugins/localization.apt at 2024-05-12 | Rendered using Apache Maven Fluido Skin 2.0.0-M6 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M18" /> + <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M10" /> <meta name="author" content="Dennis Lundberg" /> <meta name="author" content="Vincent Siveton" /> <meta name="date" content="2012-03-12" /> - <title>Maven</title> + <title>Maven â Localization of Plugins</title> <link rel="stylesheet" href="../css/apache-maven-fluido-2.0.0-M6.min.css" /> <link rel="stylesheet" href="../css/site.css" /> <link rel="stylesheet" href="../css/print.css" media="print" /> @@ -40,10 +40,8 @@ <div class="container-fluid"> <header> <div id="banner"> - <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><h1>Apache Maven Site</h1> -</a></div> - <div class="pull-right"><a href=".././" id="bannerRight"><h1>$esc.xml( $banner.name )</h1> -</a></div> + <div class="pull-left"><a href="https://www.apache.org/"; id="bannerLeft"><img src="../images/apache-maven-project.png" alt="Apache Maven Site" style="" /></a></div> + <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/maven-logo-black-on-white.png" alt="" style="" /></a></div> <div class="clear"><hr/></div> </div> @@ -51,9 +49,8 @@ <ul class="breadcrumb"> <li><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li><a href="../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - - <li class="active ">Maven <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugins/localization.apt";><img src="../images/accessories-text-editor.png" title="Edit" /></a></li> - <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-11</li> + <li class="active ">Localization of Plugins <a href="https://github.com/apache/maven-site/tree/master/content/apt/plugins/localization.apt";><img src="../images/accessories-text-editor.png" title="Edit" /></a></li> + <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2024-05-12</li> <li class="pull-right"><span class="divider">|</span> <a href="../scm.html" title="Get Sources">Get Sources</a></li> <li class="pull-right"><a href="../download.cgi" title="Download">Download</a></li> @@ -132,7 +129,7 @@ </div> </header> <main id="bodyColumn" class="span10" > -<section><a id="Localization_of_Plugins"></a> +<section> <h1>Localization of Plugins</h1> <p>Most of the plugins involved with the site generation are fully internationalized. This means that adapting them to another language, a process known as localization, is very easy. All that is needed is to download a couple of properties files and start translating the texts in them. If you want to provide a patch for an unsupported language, there are detailed instructions below.</p> <p>For the basic site generation there are currently files for three components that needs to be localized to support a new language: Maven Site Plugin, Maven Project Info Reports Plugin and Maven Doxia Tools.</p> @@ -517,7 +514,7 @@ <td style="text-align: left;">OK</td> <td style="text-align: left;"><a href="/plugins/maven-site-plugin/l10n-status.html">l10n report</a></td> <td style="text-align: left;"><a class="externalLink" href="https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-site-plugin/src/main/resources/";>SVN</a></td></tr></table> -<p>Is your favourite plugin missing a localization for your language? Please help us expand the language support by following the instructions below.</p><section><a id="Localizing_a_Plugin"></a> +<p>Is your favourite plugin missing a localization for your language? Please help us expand the language support by following the instructions below.</p><section> <h2>Localizing a Plugin</h2> <ul> <li>Check out the source code for the plugin you want to add a translation to.</li> @@ -527,7 +524,7 @@ <li>Convert the new file so that all non-US-ASCII characters are transformed into Unicode escapes, see below for a tool that can help with this.</li> <li>Run "mvn install" for the plugin.</li> <li>Configure a project to use the latest SNAPSHOT version of the plugin you are working on. Also configure the project to produce a site in the language you are adding a translation for. For Spanish, as we used in the example above, it would look like this: -<pre><code> <build> +<div class="verbatim source"><pre class="prettyprint linenums"> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> @@ -537,30 +534,32 @@ </configuration> </plugin> </plugins> - </build></code></pre></li> + </build></pre></div></li> <li>Run "mvn site" on that project to test it.</li> <li>When you are happy with your translation, create an issue in JIRA for the plugin in question, with a description like this: "Add Spanish translation". Take note of the issue number.</li> <li>Create a patch file that contains your new translation. Use the issue number when you name the file: -<pre>svn diff > MYISSUE-123.patch</pre></li> -<li>Attach your patch file to the issue in JIRA.</li></ul></section><section><a id="Tools"></a> +<div class="verbatim"> +<pre>svn diff > MYISSUE-123.patch</pre></div></li> +<li>Attach your patch file to the issue in JIRA.</li></ul></section><section> <h2>Tools</h2> <p>There is a command line tool called <b>native2ascii</b> that can be used to convert a text file to use Unicode-encoded characters instead of native-encoded characters. This is part of the Java SDK and you can <a class="externalLink" href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/native2ascii.html";>read more about it here</a>. You use it like this:</p> -<pre>native2ascii checkstyle-report_es.properties checkstyle-report_es-encoded.properties</pre><section><a id="Tools_to_find_out_the_charset_of_a_file"></a> +<div class="verbatim"> +<pre>native2ascii checkstyle-report_es.properties checkstyle-report_es-encoded.properties</pre></div><section> <h3>Tools to find out the charset of a file</h3> <ul> <li>Unix <code>file</code> command</li> <li><a class="externalLink" href="http://cpdetector.sourceforge.net/";>cpdetector</a></li> <li><a class="externalLink" href="http://plugins.intellij.net/plugin/?id=24";>IntelliJ IDEA ShowEncodingPlugin</a></li> -<li><a class="externalLink" href="http://notepad-plus.sourceforge.net/";>Notepad++</a></li></ul></section><section><a id="Tools_to_write_a_file_in_a_given_charset"></a> +<li><a class="externalLink" href="http://notepad-plus.sourceforge.net/";>Notepad++</a></li></ul></section><section> <h3>Tools to write a file in a given charset</h3> -<p>Any editor like Notepad++, Eclipse, IntelliJ IDEA, ...</p></section><section><a id="Tools_to_convert_a_file_from_one_encoding_to_another_encoding"></a> +<p>Any editor like Notepad++, Eclipse, IntelliJ IDEA, ...</p></section><section> <h3>Tools to convert a file from one encoding to another encoding</h3> <ul> <li>Unix <code>iconv</code> command</li> -<li>Notepad++</li></ul></section><section><a id="IDE_plugins"></a> +<li>Notepad++</li></ul></section><section> <h3>IDE plugins</h3> <ul> -<li><a class="externalLink" href="http://propedit.sourceforge.jp/index_en.html";>Properties Editor Eclipse Plugin</a></li></ul></section></section><section><a id="References"></a> +<li><a class="externalLink" href="http://propedit.sourceforge.jp/index_en.html";>Properties Editor Eclipse Plugin</a></li></ul></section></section><section> <h2>References</h2> <p>Please refer to the <a class="externalLink" href="http://java.sun.com/javase/technologies/core/basic/intl/";>Java Internationalization home page</a> for an introduction to the topic.</p> <p>You can also refer to this Sun FAQ: <a class="externalLink" href="http://developers.sun.com/global/technology/standards/reference/faqs/determining-file-encoding.html";>How Can I Determine the Encoding of a File?</a></p></section></section>
