Modified: maven/website/content/guides/mini/guide-using-toolchains.html ============================================================================== --- maven/website/content/guides/mini/guide-using-toolchains.html (original) +++ maven/website/content/guides/mini/guide-using-toolchains.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-using-toolchains.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-using-toolchains.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,7 +10,9 @@ <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-M4" /> - <meta name="author" content="Maria Odea Ching, Dennis Lundberg, Karl Heinz Marbaise" /> + <meta name="author" content="Maria Odea Ching +Dennis Lundberg +Karl Heinz Marbaise" /> <meta name="date" content="2016-03-08" /> <title>Maven – Guide to Using Toolchains</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> @@ -48,7 +50,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Using Toolchains <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-using-toolchains.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Using Toolchains <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-using-toolchains.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -154,104 +156,83 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide to Using Toolchains</h2><section> -<h3>What is Toolchains?</h3> +<section> +<h1>Guide to Using Toolchains</h1><section> +<h2>What is Toolchains?</h2> <p>The Maven Toolchains provide a way for plugins to discover what JDK (or other tools) are to be used during the build, without the need to configure them in each plugin nor in every <code>pom.xml</code>, or forcing a precise location among every machine building the project.</p> <p>With Maven Toolchains applied to JDK toolchain, a project can now be built using a specific version of JDK independent from the one Maven is running with. Think how JDK versions can be set in IDEs like IDEA, NetBeans and Eclipse, or how you can compile with an older JDK from Maven running with a recent one.</p><section> -<h4>Prerequisites</h4> -<p>Toolchains will only work in Maven 2.0.9 and higher versions. For more details about its design and implementation, please see <a href="http://cwiki.apache.org/confluence/display/MAVENOLD/Toolchains"; class="externalLink">Toolchains</a>.</p> +<h3>Prerequisites</h3> +<p>Toolchains will only work in Maven 2.0.9 and higher versions. For more details about its design and implementation, please see <a class="externalLink" href="http://cwiki.apache.org/confluence/display/MAVENOLD/Toolchains";>Toolchains</a>.</p> <p>Below are some plugins which are toolchain-aware, with the toolchain-type used:</p> -<table class="table table-striped"> -<thead> +<table class="bodyTable bodyTableBorder"> <tr class="a"> <th>Toolchain type</th> -<th><strong>Plugin</strong></th> -<th><strong>Starting with</strong></th> -<th><strong>Hosted at</strong></th></tr></thead><tbody> +<th><b>Plugin</b></th> +<th><b>Starting with</b></th> +<th><b>Hosted at</b></th></tr> <tr class="b"> -<td>jdk</td> -<td><code>[maven-compiler-plugin](/plugins/maven-compiler-plugin/)</code></td> -<td>2.1</td> -<td>Apache Maven</td></tr> +<td style="text-align: center;">jdk</td> +<td style="text-align: left;"><code><a href="/plugins/maven-compiler-plugin/">maven-compiler-plugin</a></code></td> +<td style="text-align: left;">2.1</td> +<td style="text-align: left;">Apache Maven</td></tr> <tr class="a"> -<td>jdk</td> -<td><code>[maven-jarsigner-plugin](/plugins/maven-jarsigner-plugin/)</code></td> -<td>1.3</td> -<td>Apache Maven</td></tr> +<td style="text-align: center;">jdk</td> +<td style="text-align: left;"><code><a href="/plugins/maven-jarsigner-plugin/">maven-jarsigner-plugin</a></code></td> +<td style="text-align: left;">1.3</td> +<td style="text-align: left;">Apache Maven</td></tr> <tr class="b"> -<td>jdk</td> -<td><code>[maven-javadoc-plugin](/plugins/maven-javadoc-plugin/)</code></td> -<td>2.5</td> -<td>Apache Maven</td></tr> +<td style="text-align: center;">jdk</td> +<td style="text-align: left;"><code><a href="/plugins/maven-javadoc-plugin/">maven-javadoc-plugin</a></code></td> +<td style="text-align: left;">2.5</td> +<td style="text-align: left;">Apache Maven</td></tr> <tr class="a"> -<td>jdk</td> -<td><code>[maven-pmd-plugin](/plugins/maven-pmd-plugin/)</code></td> -<td>3.14.0</td> -<td>Apache Maven</td></tr> +<td style="text-align: center;">jdk</td> +<td style="text-align: left;"><code><a href="/plugins/maven-pmd-plugin/">maven-pmd-plugin</a></code></td> +<td style="text-align: left;">3.14.0</td> +<td style="text-align: left;">Apache Maven</td></tr> <tr class="b"> -<td>jdk</td> -<td><code>[maven-surefire-plugin](/plugins/maven-surefire-plugin/)</code></td> -<td>2.5</td> -<td>Apache Maven</td></tr> +<td style="text-align: center;">jdk</td> +<td style="text-align: left;"><code><a href="/plugins/maven-surefire-plugin/">maven-surefire-plugin</a></code></td> +<td style="text-align: left;">2.5</td> +<td style="text-align: left;">Apache Maven</td></tr> <tr class="a"> -<td>jdk</td> -<td><code>[animal-sniffer-maven-plugin](https://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/)</code></td> -<td>1.3</td> -<td>MojoHaus</td></tr> +<td style="text-align: center;">jdk</td> +<td style="text-align: left;"><code><a class="externalLink" href="https://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/";>animal-sniffer-maven-plugin</a></code></td> +<td style="text-align: left;">1.3</td> +<td style="text-align: left;">MojoHaus</td></tr> <tr class="b"> -<td>jdk</td> -<td><code>[cassandra-maven-plugin](https://www.mojohaus.org/cassandra-maven-plugin/)</code></td> -<td>0.7.0-1</td> -<td>MojoHaus</td></tr> +<td style="text-align: center;">jdk</td> +<td style="text-align: left;"><code><a class="externalLink" href="https://www.mojohaus.org/cassandra-maven-plugin/";>cassandra-maven-plugin</a></code></td> +<td style="text-align: left;">0.7.0-1</td> +<td style="text-align: left;">MojoHaus</td></tr> <tr class="a"> -<td>jdk</td> -<td><code>[exec-maven-plugin](https://www.mojohaus.org/exec-maven-plugin/)</code></td> -<td>1.1.1</td> -<td>MojoHaus</td></tr> +<td style="text-align: center;">jdk</td> +<td style="text-align: left;"><code><a class="externalLink" href="https://www.mojohaus.org/exec-maven-plugin/";>exec-maven-plugin</a></code></td> +<td style="text-align: left;">1.1.1</td> +<td style="text-align: left;">MojoHaus</td></tr> <tr class="b"> -<td>jdk</td> -<td><code>[jdiff-maven-plugin](https://www.mojohaus.org/jdiff-maven-plugin/)</code></td> -<td>1.0-beta-1-SNAPSHOT</td> -<td>MojoHaus</td></tr> +<td style="text-align: center;">jdk</td> +<td style="text-align: left;"><code><a class="externalLink" href="https://www.mojohaus.org/jdiff-maven-plugin/";>jdiff-maven-plugin</a></code></td> +<td style="text-align: left;">1.0-beta-1-SNAPSHOT</td> +<td style="text-align: left;">MojoHaus</td></tr> <tr class="a"> -<td>jdk</td> -<td><code>[keytool-maven-plugin](https://www.mojohaus.org/keytool/keytool-maven-plugin/)</code></td> -<td>1.4</td> -<td>MojoHaus</td></tr> +<td style="text-align: center;">jdk</td> +<td style="text-align: left;"><code><a class="externalLink" href="https://www.mojohaus.org/keytool/keytool-maven-plugin/";>keytool-maven-plugin</a></code></td> +<td style="text-align: left;">1.4</td> +<td style="text-align: left;">MojoHaus</td></tr> <tr class="b"> -<td>protobuf</td> -<td><code>[maven-protoc-plugin](http://sergei-ivanov.github.io/maven-protoc-plugin/examples/protobuf-toolchain.html)</code></td> -<td>0.3.2</td> -<td>github</td></tr></tbody> -</table> -</section></section><section> -<h3>Using Toolchains in Your Project</h3> +<td style="text-align: center;">protobuf</td> +<td style="text-align: left;"><code><a class="externalLink" href="http://sergei-ivanov.github.io/maven-protoc-plugin/examples/protobuf-toolchain.html";>maven-protoc-plugin</a></code></td> +<td style="text-align: left;">0.3.2</td> +<td style="text-align: left;">github</td></tr></table></section></section><section> +<h2>Using Toolchains in Your Project</h2> <p>There are two essential components that you need to configure in order to use toolchains:</p> -<p>1 the <code>[maven-toolchains-plugin](/plugins/maven-toolchains-plugin/)</code> in your project POM,</p> -<p>1 the <code>[toolchains.xml](/ref/current/maven-core/toolchains.html)</code> file on the building machine.</p> +<ol style="list-style-type: decimal"> +<li>the <code><a href="/plugins/maven-toolchains-plugin/">maven-toolchains-plugin</a></code> in your project POM,</li> +<li>the <code><a href="/ref/current/maven-core/toolchains.html">toolchains.xml</a></code> file on the building machine.</li></ol> <p>The <code>maven-toolchains-plugin</code> is the one that sets the toolchain to be used by the toolchain-aware plugins in your project.</p> <p>For example, you want to use a different JDK version to build your project than the version used to run Maven, you can configure the version you want to use via this plugin as shown in the <code>pom.xml</code> below:</p> - -<div class="source"><pre class="prettyprint linenums"><code><plugins> +<div class="source"><pre class="prettyprint linenums"><plugins> ... <plugin> <groupId>org.apache.maven.plugins</groupId> @@ -279,13 +260,11 @@ under the License. </configuration> </plugin> ... -</plugins> -</code></pre></div> -<p>As you can see in the example above, a JDK toolchain with <code><version></code> “1.5” and <code><vendor></code> “sun” is to be used. Now how does the plugin know where this JDK is installed? This is where the <code>toolchains.xml</code> file comes in.</p> -<p>The <code>toolchains.xml</code> file (see below) is the configuration file where you set the installation paths of your toolchains. This file should be put in your <code>${user.home}/.m2</code> directory. When the <code>maven-toolchains-plugin</code> executes, it looks for the <code>toolchains.xml</code> file, reads it and looks for a toolchain matching the toolchains requirements configured in the plugin. In our example, that would be a JDK toolchain with <code><version></code> “1.5” and <code><vendor></code> “sun”. Once a match is found, the plugin then stores the toolchain to be used in the MavenSession. As you can see in our <code>toolchains.xml</code> below, there is indeed a JDK toolchain with <code><version></code> “1.5” and <code><vendor></code> “sun” configured. So when the <code>maven-compiler-plugin</code> we've configured in our <code>pom.xml</code> above executes, it will see that a JDK t oolchain is set in the MavenSession and will thereby use that toolchain (that would be the JDK installed at <code>/path/to/jdk/1.5</code> for our example) to compile the sources.</p> -<p>Starting with <a href="/docs/3.3.1/release-notes.html">Maven 3.3.1</a> you can put the <code>toolchains.xml</code> file wherever you like by using the <code>--global-toolchains file</code> option but it is recommended to locate it into <code>${user.home}/.m2/</code>.</p> - -<div class="source"><pre class="prettyprint linenums"><code><?xml version="1.0" encoding="UTF-8"?> +</plugins></pre></div> +<p>As you can see in the example above, a JDK toolchain with <code><version></code> "1.5" and <code><vendor></code> "sun" is to be used. Now how does the plugin know where this JDK is installed? This is where the <code>toolchains.xml</code> file comes in.</p> +<p>The <code>toolchains.xml</code> file (see below) is the configuration file where you set the installation paths of your toolchains. This file should be put in your <code>${user.home}/.m2</code> directory. When the <code>maven-toolchains-plugin</code> executes, it looks for the <code>toolchains.xml</code> file, reads it and looks for a toolchain matching the toolchains requirements configured in the plugin. In our example, that would be a JDK toolchain with <code><version></code> "1.5" and <code><vendor></code> "sun". Once a match is found, the plugin then stores the toolchain to be used in the MavenSession. As you can see in our <code>toolchains.xml</code> below, there is indeed a JDK toolchain with <code><version></code> "1.5" and <code><vendor></code> "sun" configured. So when the <code>maven-compiler-plugin</code> we've configured in our <code>pom.xml</code> above executes, it will see that a JDK toolchain is set in the MavenSession and will thereby use that toolchain (that would be the JDK installed at <code>/path/to/jdk/1.5</code> for our example) to compile the sources.</p> +<p>Starting with <a href="/docs/3.3.1/release-notes.html">Maven 3.3.1</a> you can put the <code>toolchains.xml</code> file wherever you like by using the <code>--global-toolchains file</code> option but it is recommended to locate it into <code>${user.home}/.m2/</code>. </p> +<div class="source"><pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> <toolchains> <!-- JDK toolchains --> <toolchain> @@ -319,9 +298,8 @@ under the License. <installDir>/path/to/netbeans/5.5</installDir> </configuration> </toolchain> -</toolchains> -</code></pre></div> -<p>Note that you can configure as many toolchains as you want in your <code>toolchains.xml</code> file.</p></section></section></section> +</toolchains></pre></div> +<p>Note that you can configure as many toolchains as you want in your <code>toolchains.xml</code> file.</p></section></section> </main> </div> </div>
Modified: maven/website/content/guides/mini/guide-wagon-providers.html ============================================================================== --- maven/website/content/guides/mini/guide-wagon-providers.html (original) +++ maven/website/content/guides/mini/guide-wagon-providers.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-wagon-providers.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-wagon-providers.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Selecting Alternative Wagon Providers <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-wagon-providers.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Selecting Alternative Wagon Providers <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-wagon-providers.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -152,40 +152,20 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide to Selecting Alternative Wagon Providers</h2> +<section> +<h1>Guide to Selecting Alternative Wagon Providers</h1> <p>By default, Maven uses the <code>java.net.URLConnection</code> (<code>HttpURLConnection</code>) classes provided with the JDK to access repositories that use the HTTP/HTTPs protocols. Unfortunately, since this implementation contains certain bugs, Maven users may find themselves unable to connect to servers that demand some configurations. A couple examples of weird behavior include line-wrapping the Authorization header's Base64 value when passwords are long, and using cached values in preemptive authentication for successive connections to the same server.</p> <p>Maven 2.2.0 attempted to amend this problem by switching over to a Wagon implementation that's based on Apache HttpClient. Unfortunately, it soon became apparent that HttpClient doesn't support NTLM (at least, version 2), which effectively means users behind NTLMv2 proxies cannot use Maven 2.2.0.</p> <p>To hopefully resolve this once and for all, Maven 2.2.1 will contain support for specifying which Wagon provider you want to use for a given protocol during the build. The provider name will then be appended to the protocol using the format <code><protocol>-<provider></code> to form the component role-hint for the Wagon.</p> <p>As of Maven 2.2.1, there are two ways to specify which Wagon provider should be used: via the command line, or in the <code><server></code> configuration section of the <code>settings.xml</code>.</p><section> -<h3>Command-Line Configuration</h3> +<h2>Command-Line Configuration</h2> <p>To specify the Wagon provider from the command line, simply use the <code>-Dmaven.wagon.provider.<protocol>=<provider-name></code> command-line option, like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn -Dmaven.wagon.provider.http=httpclient clean install -</code></pre></div> +<div> +<pre>mvn -Dmaven.wagon.provider.http=httpclient clean install</pre></div> <p>This instructs Maven to use the HttpClient-based Wagon implementation for connections to HTTP repositories.</p></section><section> -<h3><code>settings.xml</code> Configuration</h3> +<h2><code>settings.xml</code> Configuration</h2> <p>To specify which Wagon provider to use for a particular server, modify your <code>settings.xml</code> file to add the <code><wagonProvider></code> configuration to your <code><server></code> entry, like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><settings> +<div class="source"><pre class="prettyprint linenums"><settings> [...] <servers> <server> @@ -194,19 +174,16 @@ under the License. <wagonProvider>httpclient</wagonProvider> [...] </configuration> - </server> -</code></pre></div></section><section> -<h3>Available Wagon Providers</h3> + </server></pre></div></section><section> +<h2>Available Wagon Providers</h2> <p>Maven 2.2.1 provides two providers for HTTP/HTTPS Wagons: <code>lightweight</code> and <code>httpclient</code>. If you add a new HTTP Wagon implementation via build extension, you'll need to make sure the extension binds its Wagon components to role-hints of the form <code><protocol>-<provider></code> in order to allow users to specify your alternative Wagon provider. For instance, the HttpClient HTTP Wagon component definition looks like this:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><component> +<div class="source"><pre class="prettyprint linenums"><component> <role>org.apache.maven.wagon.Wagon</role> <role-hint>http-httpclient</role-hint> <implementation>org.apache.maven.wagon.providers.http.HttpWagon</implementation> <instantiation-strategy>per-lookup</instantiation-strategy> -</component> -</code></pre></div> -<p><strong>NOTE:</strong> The default provider for HTTP/HTTPS Wagons is <code>lightweight</code>.</p></section></section></section> +</component></pre></div> +<p><b>NOTE:</b> The default provider for HTTP/HTTPS Wagons is <code>lightweight</code>.</p></section></section> </main> </div> </div> Modified: maven/website/content/guides/plugin/guide-java-plugin-development.html ============================================================================== --- maven/website/content/guides/plugin/guide-java-plugin-development.html (original) +++ maven/website/content/guides/plugin/guide-java-plugin-development.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/plugin/guide-java-plugin-development.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/plugin/guide-java-plugin-development.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,7 +10,9 @@ <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-M4" /> - <meta name="author" content="Bob Allison, Vincent Siveton, Olivier Lamy" /> + <meta name="author" content="Bob Allison +Vincent Siveton +Olivier Lamy" /> <meta name="date" content="2013-01-02" /> <title>Maven – Guide to Developing Java Plugins</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> @@ -48,7 +50,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Developing Java Plugins <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/plugin/guide-java-plugin-development.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Developing Java Plugins <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/plugin/guide-java-plugin-development.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -136,76 +138,40 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> <section> <h1>Introduction</h1> -<p>This guide is intended to assist users in developing Java plugins for Maven.</p><!-- TODO replace by TOC macro after https://issues.apache.org/jira/browse/DOXIA-696 --> - +<p>This guide is intended to assist users in developing Java plugins for Maven.</p> <ul> - -<li><a href="#important-notice-plugin-naming-convention-and-apache-maven-trade">Important Notice: Plugin Naming Convention and Apache Maven Trademark</a></li> -<li><a href="#your-first-plugin">Your First Plugin</a> +<li><a href="#Important_Notice:_Plugin_Naming_Convention_and_Apache_Maven_Trademark">Important Notice: Plugin Naming Convention and Apache Maven Trademark</a></li> +<li><a href="#Your_First_Plugin">Your First Plugin</a> <ul> - -<li><a href="#your-first-mojo">Your First Mojo</a></li> -<li><a href="#a-simple-mojo">A Simple Mojo</a></li> -<li><a href="#project-definition">Project Definition</a></li> -<li><a href="#building-a-plugin">Building a Plugin</a></li> -</ul></li> -<li><a href="#executing-your-first-mojo">Executing Your First Mojo</a> +<li><a href="#Your_First_Mojo">Your First Mojo</a> <ul> - -<li><a href="#shortening-the-command-line">Shortening the Command Line</a></li> -<li><a href="#attaching-the-mojo-to-the-build-lifecycle">Attaching the Mojo to the Build Lifecycle</a></li> -</ul></li> -<li><a href="#mojo-archetype">Mojo archetype</a></li> -<li><a href="#parameters">Parameters</a> +<li><a href="#A_Simple_Mojo">A Simple Mojo</a></li></ul></li> +<li><a href="#Project_Definition">Project Definition</a></li> +<li><a href="#Building_a_Plugin">Building a Plugin</a></li> +<li><a href="#Executing_Your_First_Mojo">Executing Your First Mojo</a> <ul> - -<li><a href="#defining-parameters-within-a-mojo">Defining Parameters Within a Mojo</a></li> -<li><a href="#configuring-parameters-in-a-project">Configuring Parameters in a Project</a></li> -</ul></li> -<li><a href="#using-setters">Using Setters</a></li> -<li><a href="#resources">Resources</a></li> -</ul><section> +<li><a href="#Shortening_the_Command_Line">Shortening the Command Line</a></li> +<li><a href="#Attaching_the_Mojo_to_the_Build_Lifecycle">Attaching the Mojo to the Build Lifecycle</a></li></ul></li></ul></li> +<li><a href="#Mojo_archetype">Mojo archetype</a></li> +<li><a href="#Parameters">Parameters</a> +<ul> +<li><a href="#Defining_Parameters_Within_a_Mojo">Defining Parameters Within a Mojo</a></li> +<li><a href="#Configuring_Parameters_in_a_Project">Configuring Parameters in a Project</a></li></ul></li> +<li><a href="#Using_Setters">Using Setters</a></li> +<li><a href="#Resources">Resources</a></li></ul><section> <h2>Important Notice: <a href="../mini/guide-naming-conventions.html">Plugin Naming Convention and Apache Maven Trademark</a></h2> <p>You will typically name your plugin <code><yourplugin>-maven-plugin</code>.</p> -<p>Calling it <code>maven-<yourplugin>-plugin</code> (note “Maven” is at the beginning of the plugin name) -is <strong>strongly discouraged</strong> since it's a <strong>reserved naming pattern for official Apache Maven plugins maintained by the Apache Maven team</strong> -with groupId <code>org.apache.maven.plugins</code>.</p> -<p>Using this naming pattern is an infringement of the Apache Maven Trademark.</p></section><section> +<p>Calling it <code>maven-<yourplugin>-plugin</code> (note "Maven" is at the beginning of the plugin name) is <b>strongly discouraged</b> since it's a <b>reserved naming pattern for official Apache Maven plugins maintained by the Apache Maven team</b> with groupId <code>org.apache.maven.plugins</code>. Using this naming pattern is an infringement of the Apache Maven Trademark.</p></section><section> <h2>Your First Plugin</h2> -<p>In this section we will build a simple plugin with one goal which takes no parameters and simply displays a message on the screen when run. -Along the way, we will cover the basics of setting up a project to create a plugin, the minimal contents of a Java mojo which will define goal code, -and a couple ways to execute the mojo.</p><section> +<p>In this section we will build a simple plugin with one goal which takes no parameters and simply displays a message on the screen when run. Along the way, we will cover the basics of setting up a project to create a plugin, the minimal contents of a Java mojo which will define goal code, and a couple ways to execute the mojo.</p><section> <h3>Your First Mojo</h3> -<p>At its simplest, a Java mojo consists simply of a single class representing one plugin's goal. -There is no requirement for multiple classes like EJBs, although a plugin which contains a number of similar mojos is likely to use an abstract superclass -for the mojos to consolidate code common to all mojos.</p> -<p>When processing the source tree to find mojos, <a href="/plugin-tools/"><code>plugin-tools</code></a> looks for classes with either <code>@Mojo</code> annotation. -Any class with this annotation are included in the plugin configuration file.</p></section><section> -<h3>A Simple Mojo</h3> -<p>Listed below is a simple mojo class which has no parameters. This is about as simple as a mojo can be. -After the listing is a description of the various parts of the source.</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-java">package sample.plugin; +<p>At its simplest, a Java mojo consists simply of a single class representing one plugin's goal. There is no requirement for multiple classes like EJBs, although a plugin which contains a number of similar mojos is likely to use an abstract superclass for the mojos to consolidate code common to all mojos.</p> +<p>When processing the source tree to find mojos, <a href="/plugin-tools/"> <code>plugin-tools</code></a> looks for classes with either <code>@Mojo</code> Java 5 annotation or "<code>goal</code>" javadoc annotation. Any class with this annotation are included in the plugin configuration file.</p><section> +<h4>A Simple Mojo</h4> +<p>Listed below is a simple mojo class which has no parameters. This is about as simple as a mojo can be. After the listing is a description of the various parts of the source.</p> +<div class="source"><pre class="prettyprint linenums">package sample.plugin; import org.apache.maven.plugin.AbstractMojo; import org.apache.maven.plugin.MojoExecutionException; @@ -215,54 +181,43 @@ import org.apache.maven.plugins.annotati * Says "Hi" to the user. * */ -@Mojo(name = "sayhi") -public class GreetingMojo extends AbstractMojo { - - public void execute() throws MojoExecutionException { +@Mojo( name = "sayhi") +public class GreetingMojo extends AbstractMojo +{ + public void execute() throws MojoExecutionException + { getLog().info( "Hello, world." ); } -} -</code></pre></div> +}</pre></div> <ul> - <li>The class <code>org.apache.maven.plugin.AbstractMojo</code> provides most of the infrastructure required to implement a mojo except for the <code>execute</code> method.</li> -<li>The annotation “<code>@Mojo</code>” is required and control how and when the mojo is executed.</li> -<li>The <code>execute</code> method can throw an exception: +<li>The annotation "<code>@Mojo</code>" is required and control how and when the mojo is executed.</li> +<li>The <code>execute</code> method can throw two exceptions: <ul> - -<li><code>org.apache.maven.plugin.MojoExecutionException</code> if an unexpected problem occurs. Throwing this exception causes a “BUILD FAILURE” message to be displayed.</li> -</ul></li> -<li>The <code>getLog</code> method (defined in <code>AbstractMojo</code>) returns a log4j-like logger object which allows plugins to create messages at levels of “debug”, “info”, “warn”, and “error”. -This logger is the accepted means to display information to the user. Please have a look at the section <a href="../../plugin-developers/common-bugs.html#retrieving-the-mojo-logger">Retrieving the Mojo Logger</a> for a hint on its proper usage.</li> -</ul> -<p>All Mojo annotations are described by the <a href="../../developers/mojo-api-specification.html#The_Descriptor_and_Annotations">Mojo API Specification</a>.</p></section><section> +<li><code>org.apache.maven.plugin.MojoExecutionException</code> if an unexpected problem occurs. Throwing this exception causes a "BUILD ERROR" message to be displayed.</li> +<li><code>org.apache.maven.plugin.MojoFailureException</code> if an expected problem (such as a compilation failure) occurs. Throwing this exception causes a "BUILD FAILURE" message to be displayed.</li></ul></li> +<li>The <code>getLog</code> method (defined in <code>AbstractMojo</code>) returns a log4j-like logger object which allows plugins to create messages at levels of "debug", "info", "warn", and "error". This logger is the accepted means to display information to the user. Please have a look at the section <a href="../../plugin-developers/common-bugs.html#Retrieving_the_Mojo_Logger">Retrieving the Mojo Logger</a> for a hint on its proper usage.</li></ul> +<p>All Mojo annotations are described by the <a href="../../developers/mojo-api-specification.html#The_Descriptor_and_Annotations">Mojo API Specification</a>.</p></section></section><section> <h3>Project Definition</h3> <p>Once the mojos have been written for the plugin, it is time to build the plugin. To do this properly, the project's descriptor needs to have a number of settings set properly:</p> -<table class="table table-striped"> -<thead> +<table class="bodyTable bodyTableBorder"> <tr class="a"> -<th> </th> -<th> </th></tr></thead><tbody> +<td style="text-align: left;"><code>groupId</code></td> +<td style="text-align: left;">This is the group ID for the plugin, and should match the common prefix to the packages used by the mojos</td></tr> <tr class="b"> -<td><code>groupId</code></td> -<td>This is the group ID for the plugin, and should match the common prefix to the packages used by the mojos</td></tr> +<td style="text-align: left;"><code>artifactId</code></td> +<td style="text-align: left;">This is the name of the plugin</td></tr> <tr class="a"> -<td><code>artifactId</code></td> -<td>This is the name of the plugin</td></tr> +<td style="text-align: left;"><code>version</code></td> +<td style="text-align: left;">This is the version of the plugin</td></tr> <tr class="b"> -<td><code>version</code></td> -<td>This is the version of the plugin</td></tr> +<td style="text-align: left;"><code>packaging</code></td> +<td style="text-align: left;">This should be set to "<code>maven-plugin</code>"</td></tr> <tr class="a"> -<td><code>packaging</code></td> -<td>This must be set to “<code>maven-plugin</code>”</td></tr> -<tr class="b"> -<td><code>dependencies</code></td> -<td>A dependency must be declared to the Maven Plugin Tools API to resolve “<code>AbstractMojo</code>” and related classes</td></tr></tbody> -</table> - +<td style="text-align: left;"><code>dependencies</code></td> +<td style="text-align: left;">A dependency must be declared to the Maven Plugin Tools API to resolve "<code>AbstractMojo</code>" and related classes</td></tr></table> <p>Listed below is an illustration of the sample mojo project's pom with the parameters set as described in the above table:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> <modelVersion>4.0.0</modelVersion> <groupId>sample.plugin</groupId> @@ -271,11 +226,7 @@ This logger is the accepted means to dis <packaging>maven-plugin</packaging> <name>Sample Parameter-less Maven Plugin</name> - - <properties> - <maven-plugin-tools.version>3.7.1</maven-plugin-tools.version> - </properties> - + <dependencies> <dependency> <groupId>org.apache.maven</groupId> @@ -288,65 +239,36 @@ This logger is the accepted means to dis <dependency> <groupId>org.apache.maven.plugin-tools</groupId> <artifactId>maven-plugin-annotations</artifactId> - <version>${maven-plugin-tools.version}</version> + <version>3.4</version> <scope>provided</scope> </dependency> </dependencies> - - <build> - <pluginManagement> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-plugin-plugin</artifactId> - <version>${maven-plugin-tools.version}</version> - <executions> - <execution> - <id>help-mojo</id> - <goals> - <!-- good practice is to generate help mojo for plugin --> - <goal>helpmojo</goal> - </goals> - </execution> - </executions> - </plugin> - </pluginManagement> - </build> -</project> -</code></pre></div></section><section> +</project></pre></div></section><section> <h3>Building a Plugin</h3> <p>There are few plugins goals bound to the standard build lifecycle defined with the <code>maven-plugin</code> packaging:</p> -<table class="table table-striped"> -<thead> +<table class="bodyTable bodyTableBorder"> <tr class="a"> -<th> </th> -<th> </th></tr></thead><tbody> +<td style="text-align: left;"><code>compile</code></td> +<td style="text-align: left;">Compiles the Java code for the plugin</td></tr> <tr class="b"> -<td><code>compile</code></td> -<td>Compiles the Java code for the plugin</td></tr> +<td style="text-align: left;"><code>process-classes</code></td> +<td style="text-align: left;">Extracts data to build the <a href="/ref/current/maven-plugin-api/plugin.html">plugin descriptor</a></td></tr> <tr class="a"> -<td><code>process-classes</code></td> -<td>Extracts data to build the <a href="/ref/current/maven-plugin-api/plugin.html">plugin descriptor</a></td></tr> +<td style="text-align: left;"><code>test</code></td> +<td style="text-align: left;">Runs the plugin's unit tests</td></tr> <tr class="b"> -<td><code>test</code></td> -<td>Runs the plugin's unit tests</td></tr> +<td style="text-align: left;"><code>package</code></td> +<td style="text-align: left;">Builds the plugin jar</td></tr> <tr class="a"> -<td><code>package</code></td> -<td>Builds the plugin jar</td></tr> +<td style="text-align: left;"><code>install</code></td> +<td style="text-align: left;">Installs the plugin jar in the local repository</td></tr> <tr class="b"> -<td><code>install</code></td> -<td>Installs the plugin jar in the local repository</td></tr> -<tr class="a"> -<td><code>deploy</code></td> -<td>Deploys the plugin jar to the remote repository</td></tr></tbody> -</table> - -<p>For more details, you can look at <a href="/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_maven-plugin_packaging">detailed bindings for <code>maven-plugin</code> packaging</a>.</p></section></section><section> -<h2>Executing Your First Mojo</h2> -<p>The most direct means of executing your new plugin is to specify the plugin goal directly on the command line. -To do this, you need to configure the <code>hello-maven-plugin</code> plugin in you project:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> -... +<td style="text-align: left;"><code>deploy</code></td> +<td style="text-align: left;">Deploys the plugin jar to the remote repository</td></tr></table> +<p>For more details, you can look at <a href="/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_maven-plugin_packaging"> detailed bindings for <code>maven-plugin</code> packaging</a>.</p></section><section> +<h3>Executing Your First Mojo</h3> +<p>The most direct means of executing your new plugin is to specify the plugin goal directly on the command line. To do this, you need to configure the <code>hello-maven-plugin</code> plugin in you project:</p> +<div class="source"><pre class="prettyprint linenums">... <build> <pluginManagement> <plugins> @@ -358,38 +280,25 @@ To do this, you need to configure the <c </plugins> </pluginManagement> </build> -... -</project> -</code></pre></div> +...</pre></div> <p>And, you need to specify a fully-qualified goal in the form of:</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn groupId:artifactId:version:goal -</code></pre></div> -<p>For example, to run the simple mojo in the sample plugin, you would enter “<code>mvn sample.plugin:hello-maven-plugin:1.0-SNAPSHOT:sayhi</code>” on the command line.</p> -<p><strong>Tips</strong>: <code>version</code> is not required to run a standalone goal.</p><section> -<h3>Shortening the Command Line</h3> +<div> +<pre>mvn groupId:artifactId:version:goal</pre></div> +<p>For example, to run the simple mojo in the sample plugin, you would enter "<code>mvn sample.plugin:hello-maven-plugin:1.0-SNAPSHOT:sayhi</code>" on the command line.</p> +<p><b>Tips</b>: <code>version</code> is not required to run a standalone goal.</p><section> +<h4>Shortening the Command Line</h4> <p>There are several ways to reduce the amount of required typing:</p> <ul> - -<li>If you need to run the latest version of a plugin installed in your local repository, you can omit its version number. -So just use “<code>mvn sample.plugin:hello-maven-plugin:sayhi</code>” to run your plugin.</li> -<li>You can assign a shortened prefix to your plugin, such as <code>mvn hello:sayhi</code>. -This is done automatically if you follow the convention of using <code>${prefix}-maven-plugin</code> -(or <code>maven-${prefix}-plugin</code> if the plugin is part of the Apache Maven project). -You may also assign one through additional configuration - for more information see <a href="../introduction/introduction-to-plugin-prefix-mapping.html">Introduction to Plugin Prefix Mapping</a>.</li> -<li>Finally, you can also add your plugin's groupId to the list of groupIds searched by default. -To do this, you need to add the following to your <code>${user.home}/.m2/settings.xml</code> file:</li> -</ul> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><pluginGroups> +<li>If you need to run the latest version of a plugin installed in your local repository, you can omit its version number. So just use "<code>mvn sample.plugin:hello-maven-plugin:sayhi</code>" to run your plugin.</li> +<li>You can assign a shortened prefix to your plugin, such as <code>mvn hello:sayhi</code>. This is done automatically if you follow the convention of using <code>${prefix}-maven-plugin</code> (or <code>maven-${prefix}-plugin</code> if the plugin is part of the Apache Maven project). You may also assign one through additional configuration - for more information see <a href="../introduction/introduction-to-plugin-prefix-mapping.html"> Introduction to Plugin Prefix Mapping</a>.</li> +<li>Finally, you can also add your plugin's groupId to the list of groupIds searched by default. To do this, you need to add the following to your <code>${user.home}/.m2/settings.xml</code> file: +<div class="source"><pre class="prettyprint linenums"><pluginGroups> <pluginGroup>sample.plugin</pluginGroup> -</pluginGroups> -</code></pre></div> -<p>At this point, you can run the mojo with <code>mvn hello:sayhi</code>.</p></section><section> -<h3>Attaching the Mojo to the Build Lifecycle</h3> +</pluginGroups></pre></div></li></ul> +<p>At this point, you can run the mojo with "<code>mvn hello:sayhi</code>".</p></section><section> +<h4>Attaching the Mojo to the Build Lifecycle</h4> <p>You can also configure your plugin to attach specific goals to a particular phase of the build lifecycle. Here is an example:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> <build> +<div class="source"><pre class="prettyprint linenums"> <build> <pluginManagement> <plugins> <plugin> @@ -413,108 +322,87 @@ To do this, you need to add the followin </executions> </plugin> </plugins> - </build> -</code></pre></div> -<p>This causes the simple mojo to be executed whenever Java code is compiled. For more information on binding a mojo to phases in the lifecycle, please refer to the <a href="../introduction/introduction-to-the-lifecycle.html">Build Lifecycle</a> document.</p></section></section><section> + </build></pre></div> +<p>This causes the simple mojo to be executed whenever Java code is compiled. For more information on binding a mojo to phases in the lifecycle, please refer to the <a href="../introduction/introduction-to-the-lifecycle.html">Build Lifecycle</a> document.</p></section></section></section><section> <h2>Mojo archetype</h2> <p>To create a new plugin project, you could using the Mojo <a href="../introduction/introduction-to-archetypes.html">archetype</a> with the following command line:</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn archetype:generate \ +<div> +<pre>mvn archetype:generate \ -DgroupId=sample.plugin \ -DartifactId=hello-maven-plugin \ -DarchetypeGroupId=org.apache.maven.archetypes \ - -DarchetypeArtifactId=maven-archetype-plugin -</code></pre></div></section><section> -<h2>Parameters</h2> + -DarchetypeArtifactId=maven-archetype-plugin</pre></div></section><section> +<h2><a id="Parameters">Parameters</a></h2> <p>It is unlikely that a mojo will be very useful without parameters. Parameters provide a few very important functions:</p> <ul> - <li>It provides hooks to allow the user to adjust the operation of the plugin to suit their needs.</li> -<li>It provides a means to easily extract the value of elements from the POM without the need to navigate the objects.</li> -</ul><section> +<li>It provides a means to easily extract the value of elements from the POM without the need to navigate the objects.</li></ul><section> <h3>Defining Parameters Within a Mojo</h3> -<p>Defining a parameter is as simple as creating an instance variable in the mojo and adding the proper annotations. -Listed below is an example of a parameter for the simple mojo:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-java"> /** +<p>Defining a parameter is as simple as creating an instance variable in the mojo and adding the proper annotations. Listed below is an example of a parameter for the simple mojo:</p> +<div class="source"><pre class="prettyprint linenums"> /** * The greeting to display. */ @Parameter( property = "sayhi.greeting", defaultValue = "Hello World!" ) - private String greeting; -</code></pre></div> -<p>The portion before the annotations is the description of the parameter.</p> -<p>The <code>@Parameter</code> annotation identifies the variable as a mojo parameter.</p> -<p>The <code>defaultValue</code> parameter of the annotation defines the default value for the variable. -This value can include expressions which reference the project, such as “<code>${project.version}</code>” -(more can be found in the <a href="/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html">“Parameter Expressions” document</a>).</p> -<p>The <code>property</code> parameter can be used to allow configuration of the mojo parameter from the command line by referencing a property that the user sets via the <code>-D</code> option.</p></section><section> + private String greeting;</pre></div> +<p>The portion before the annotations is the description of the parameter. The <code>parameter</code> annotation identifies the variable as a mojo parameter. The <code>defaultValue</code> parameter of the annotation defines the default value for the variable. This value can include expressions which reference the project, such as "<code>${project.version}</code>" (more can be found in the <a href="/ref/current/maven-core/apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html">"Parameter Expressions" document</a>). The <code>property</code> parameter can be used to allow configuration of the mojo parameter from the command line by referencing a system property that the user sets via the <code>-D</code> option.</p></section><section> <h3>Configuring Parameters in a Project</h3> -<p>Configuring the parameter values for a plugin is done in a Maven project within the <code>pom.xml</code> file as part of defining the plugin in the project. -An example of configuring a plugin:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><plugin> +<p>Configuring the parameter values for a plugin is done in a Maven project within the <code>pom.xml</code> file as part of defining the plugin in the project. An example of configuring a plugin:</p> +<div class="source"><pre class="prettyprint linenums"><plugin> <groupId>sample.plugin</groupId> <artifactId>hello-maven-plugin</artifactId> <version>1.0-SNAPSHOT</version> <configuration> <greeting>Welcome</greeting> </configuration> -</plugin> -</code></pre></div> -<p>In the configuration section, the element name (“<code>greeting</code>”) is the parameter name and the contents of the element (“<code>Welcome</code>”) is the value to be assigned to the parameter.</p> -<p><strong>Note</strong>: More details can be found in the <a href="../mini/guide-configuring-plugins.html">Guide to Configuring Plugins</a>.</p></section></section><section> +</plugin></pre></div> +<p>In the configuration section, the element name ("<code>greeting</code>") is the parameter name and the contents of the element ("<code>Welcome</code>") is the value to be assigned to the parameter.</p> +<p><b>Note</b>: More details can be found in the <a href="../mini/guide-configuring-plugins.html">Guide to Configuring Plugins</a>.</p></section></section><section> <h2>Using Setters</h2> -<p>You are not restricted to using private field mapping which is good if you are trying to make you Mojos reusable outside the context of Maven.</p> -<p>Using the example above we could define public setters methods that the configuration mapping mechanism can use.</p> -<p>You can also add <code>@Parameter</code> annotation on setter method (from version 3.7.0 of <code>plugin-tools</code>)</p> -<p>So our Mojo would look like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-java"> -public class MyQueryMojo extends AbstractMojo { - - // provide name for non matching field and setter name - @Parameter(name="url", property="url") +<p>You are not restricted to using private field mapping which is good if you are trying to make you Mojos resuable outside the context of Maven. Using the example above we could name our private fields using the underscore convention and provide setters that the configuration mapping mechanism can use. So our Mojo would look like the following:</p> +<div class="source"><pre class="prettyprint linenums"> +public class MyQueryMojo + extends AbstractMojo +{ + @Parameter(property="url") private String _url; @Parameter(property="timeout") - private int timeout; + private int _timeout; - private String option0; - private String option1; + @Parameter(property="options") + private String[] _options; - public void setUrl(String url) { + public void setUrl( String url ) + { _url = url; } - public void setTimeout(int timeout) { - this.timeout = timeout; + public void setTimeout( int timeout ) + { + _timeout = timeout; } - @Parameter(property="options") - public void setOptions(String[] options) { - // we can do something more with provided parameter - this.option0 = options[0]; - this.option1 = options[1]; + public void setOptions( String[] options ) + { + _options = options; } - public void execute() throws MojoExecutionException { + public void execute() + throws MojoExecutionException + { ... } } - -</code></pre></div> -<p>Note the specification of the property name for each parameter which tells Maven -what setter and getter to use when the field's name does not match the intended name of the parameter in the plugin configuration.</p></section><section> +</pre></div> +<p>Note the specification of the property name for each parameter which tells Maven what setter and getter to use when the field's name does not match the intended name of the parameter in the plugin configuration.</p></section><section> <h2>Resources</h2> <ol style="list-style-type: decimal"> - <li><a href="../../developers/mojo-api-specification.html">Mojo Documentation</a>: Mojo API, Mojo annotations</li> <li><a href="/shared/maven-plugin-testing-harness/">Maven Plugin Testing Harness</a>: Testing framework for your Mojos.</li> -<li><a href="https://codehaus-plexus.github.io/"; class="externalLink">Plexus</a>: The IoC container used by Maven.</li> -<li><a href="https://codehaus-plexus.github.io/plexus-utils/"; class="externalLink">Plexus Common Utilities</a>: Set of utilities classes useful for Mojo development.</li> -<li><a href="http://commons.apache.org/io/"; class="externalLink">Commons IO</a>: Set of utilities classes useful for file/path handling.</li> -<li><a href="../../plugin-developers/common-bugs.html">Common Bugs and Pitfalls</a>: Overview of problematic coding patterns.</li> -</ol></section></section> +<li><a class="externalLink" href="https://codehaus-plexus.github.io/";>Plexus</a>: The IoC container used by Maven.</li> +<li><a class="externalLink" href="https://codehaus-plexus.github.io/plexus-utils/";>Plexus Common Utilities</a>: Set of utilities classes useful for Mojo development.</li> +<li><a class="externalLink" href="http://commons.apache.org/io/";>Commons IO</a>: Set of utilities classes useful for file/path handling.</li> +<li><a href="../../plugin-developers/common-bugs.html">Common Bugs and Pitfalls</a>: Overview of problematic coding patterns.</li></ol></section></section> </main> </div> </div> Modified: maven/website/content/guides/plugin/guide-java-report-plugin-development.html ============================================================================== --- maven/website/content/guides/plugin/guide-java-report-plugin-development.html (original) +++ maven/website/content/guides/plugin/guide-java-report-plugin-development.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/plugin/guide-java-report-plugin-development.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/plugin/guide-java-report-plugin-development.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,7 +10,8 @@ <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-M4" /> - <meta name="author" content="Hervé Boutemy, Bertrand Martin" /> + <meta name="author" content="Hervé Boutemy +Bertrand Martin" /> <meta name="date" content="2018-01-21" /> <title>Maven – Guide to Developing Java Report Plugins</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> @@ -48,7 +49,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Developing Java Report Plugins <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/plugin/guide-java-report-plugin-development.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Developing Java Report Plugins <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/plugin/guide-java-report-plugin-development.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -136,34 +137,16 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Introduction</h2> +<section> +<h1>Introduction</h1> <p>This guide is intended to assist users in developing reporting plugins for Maven in Java, that will contribute to sites generated by <a href="/plugins/maven-site-plugin/"><code>maven-site-plugin</code></a> or site PDF documents generated by <a href="/plugins/maven-pdf-plugin/"><code>maven-pdf-site</code></a>.</p> -<p>First and foremost, a <em>report plugin</em> is a <em>Maven plugin</em> and it is strongly advised to first read the <a href="./guide-java-plugin-development.html">Guide to Developing Java Plugins</a> to properly understand its core mechanisms.</p> -<p>A plugin is actually not a <em>report plugin</em> in itself. But one (or several) of its goals or <em>Mojos</em> may be specialized to be invoked by <a href="/plugins/maven-site-plugin/"><code>maven-site-plugin</code></a>, typically during the <code>site</code> build life cycle.</p> -<p>A Maven plugin can therefore implement <em>regular</em> goals and <em>report</em> goals. The below details how to write a <em>Mojo</em> that will get invoked as a <em>report</em> by <a href="/plugins/maven-site-plugin/"><code>maven-site-plugin</code></a>.</p><section> -<h3>How It Works</h3> -<p>1 A regular Maven project usually invokes <em>reporting goals</em> of a plugin by declaring such plugin in the <a href="/plugins/maven-site-plugin/examples/configuring-reports.html"><code><reporting></code></a> section of its <code>pom.xml</code> as in the example below:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<p>First and foremost, a <i>report plugin</i> is a <i>Maven plugin</i> and it is strongly advised to first read the <a href="./guide-java-plugin-development.html">Guide to Developing Java Plugins</a> to properly understand its core mechanisms.</p> +<p>A plugin is actually not a <i>report plugin</i> in itself. But one (or several) of its goals or <i>Mojos</i> may be specialized to be invoked by <a href="/plugins/maven-site-plugin/"><code>maven-site-plugin</code></a>, typically during the <code>site</code> build life cycle.</p> +<p>A Maven plugin can therefore implement <i>regular</i> goals and <i>report</i> goals. The below details how to write a <i>Mojo</i> that will get invoked as a <i>report</i> by <a href="/plugins/maven-site-plugin/"><code>maven-site-plugin</code></a>.</p><section> +<h2>How It Works</h2> +<ol style="list-style-type: decimal"> +<li> A regular Maven project usually invokes <i>reporting goals</i> of a plugin by declaring such plugin in the <a href="/plugins/maven-site-plugin/examples/configuring-reports.html"><code><reporting></code></a> section of its <code>pom.xml</code> as in the example below: +<div class="source"><pre class="prettyprint linenums"><project> ... <reporting> <plugins> @@ -174,61 +157,39 @@ under the License. </plugin> </plugins> </reporting> - ... -</code></pre></div> -<p>1 When <a href="/plugins/maven-site-plugin/"><code>maven-site-plugin</code></a> is invoked (for example with the <code>mvn site</code> command), the specified plugins are loaded and the <code>generate()</code> method of each Mojo class that implements <a href="/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html"><code>MavenReport</code></a> is executed.</p> -<p>1 The <code>generate()</code> method generates a document through Maven's <a href="/doxia/doxia/doxia-sink-api/">Doxia Sink API</a>. This document is comprised of basic elements like title, headings, text, links, tables, etc. This is where you will put the logic of your report, assembling elements, based on the content of the Maven project.</p> -<p>1 These document elements are passed to Doxia to generate an HTML document, which itself gets wrapped into a <a href="/skins/">Maven Skin</a>, as specified in the projects <a href="/guides/mini/guide-site.html"><code>./src/site/site.xml</code></a>.</p> -<p>1 The result produces an HTML file in the <code>./target/site</code> directory of your project.</p> + ...</pre></div></li> +<li> When <a href="/plugins/maven-site-plugin/"><code>maven-site-plugin</code></a> is invoked (for example with the <code>mvn site</code> command), the specified plugins are loaded and the <code>generate()</code> method of each Mojo class that implements <a href="/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html"><code>MavenReport</code></a> is executed.</li> +<li> The <code>generate()</code> method generates a document through Maven's <a href="/doxia/doxia/doxia-sink-api/">Doxia Sink API</a>. This document is comprised of basic elements like title, headings, text, links, tables, etc. This is where you will put the logic of your report, assembling elements, based on the content of the Maven project.</li> +<li> These document elements are passed to Doxia to generate an HTML document, which itself gets wrapped into a <a href="/skins/">Maven Skin</a>, as specified in the projects <a href="/guides/mini/guide-site.html"><code>./src/site/site.xml</code></a>.</li> +<li> The result produces an HTML file in the <code>./target/site</code> directory of your project.</li></ol> <p><a href="/doxia/doxia-sitetools/doxia-site-renderer/">More details about Doxia Site Renderer</a></p></section><section> -<h3>Basic Requirements of a Report <em>Mojo</em></h3> -<p>Each goal or <em>Mojo</em> is implemented with a separate Java class. For a <em>Mojo</em> to become a <em>report Mojo</em>, it needs to implement <a href="/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html"><code>org.apache.maven.reporting.MavenReport</code></a> (in addition to <a href="/ref/current/apidocs/org/apache/maven/plugin/Mojo.html"><code>org.apache.maven.plugin.Mojo</code></a>).</p> -<p>An easy way to implement both <code>Mojo</code> and <code>MavenReport</code> interfaces is to extend the <a href="/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html"><code>org.apache.maven.reporting.AbstractMavenReport</code></a> class provided by <a href="/shared/maven-reporting-impl/"><code>maven-reporting-impl</code></a> (instead of <code>org.apache.maven.plugin.AbstractMojo</code> for a regular <em>Mojo</em>).</p> +<h2>Basic Requirements of a Report <i>Mojo</i></h2> +<p>Each goal or <i>Mojo</i> is implemented with a separate Java class. For a <i>Mojo</i> to become a <i>report Mojo</i>, it needs to implement <a href="/shared/maven-reporting-api/apidocs/org/apache/maven/reporting/MavenReport.html"><code>org.apache.maven.reporting.MavenReport</code></a> (in addition to <a href="/ref/current/apidocs/org/apache/maven/plugin/Mojo.html"><code>org.apache.maven.plugin.Mojo</code></a>).</p> +<p>An easy way to implement both <code>Mojo</code> and <code>MavenReport</code> interfaces is to extend the <a href="/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html"><code>org.apache.maven.reporting.AbstractMavenReport</code></a> class provided by <a href="/shared/maven-reporting-impl/"><code>maven-reporting-impl</code></a> (instead of <code>org.apache.maven.plugin.AbstractMojo</code> for a regular <i>Mojo</i>).</p> <p>The class will need to implement the following methods:</p> <ul> - -<li> -<p><code>public String getOutputName()</code>: returns the name of page that will be produced</p></li> -<li> -<p><code>public String getName(Locale locale)</code>: returns the display name of the report</p></li> -<li> -<p><code>public String getDescription(Locale locale)</code>: returns the description of the report</p></li> -<li> -<p><code>protected void executeReport(Locale locale) throws MavenReportException</code>: produces the actual report</p></li> -</ul> -<p>To build a Maven plugin that includes <em>report Mojos</em>, the <code>pom.xml</code> of your project will need declare the project as a regular plugin, and include specific dependencies required by the report <em>Mojos</em>:</p> +<li><code>public String getOutputName()</code>: returns the name of page that will be produced</li> +<li><code>public String getName(Locale locale)</code>: returns the display name of the report</li> +<li><code>public String getDescription(Locale locale)</code>: returns the description of the report</li> +<li><code>protected void executeReport(Locale locale) throws MavenReportException</code>: produces the actual report</li></ul> +<p>To build a Maven plugin that includes <i>report Mojos</i>, the <code>pom.xml</code> of your project will need declare the project as a regular plugin, and include specific dependencies required by the report <i>Mojos</i>:</p> <ul> - -<li> -<p><a href="/shared/maven-reporting-impl/dependency-info.html"><code>org.apache.maven.reporting:maven-reporting-impl</code></a></p></li> -<li> -<p><a href="/shared/maven-reporting-api/project-summary.html"><code>org.apache.maven.reporting:maven-reporting-api</code></a></p></li> -</ul></section><section> -<h3>A (Very) Simple Report</h3> -<p>Let's write a very simple <em>report Mojo</em> in a very simple Maven plugin:</p> +<li><a href="/shared/maven-reporting-impl/dependency-info.html"><code>org.apache.maven.reporting:maven-reporting-impl</code></a></li> +<li><a href="/shared/maven-reporting-api/project-summary.html"><code>org.apache.maven.reporting:maven-reporting-api</code></a></li></ul></section><section> +<h2>A (Very) Simple Report</h2> +<p>Let's write a very simple <i>report Mojo</i> in a very simple Maven plugin:</p> <ul> - -<li> -<p>Plugin's name: <strong>Simple Plugin</strong></p></li> -<li> -<p>Plugin's artifact coordinates: <code>com.mycompany.maven:simple-maven-plugin:1.0-SNAPSHOT</code></p></li> -<li> -<p>One goal: <strong>simple</strong></p></li> -<li> -<p>One result: <code>simple-report.html</code></p></li> -</ul> +<li>Plugin's name: <b>Simple Plugin</b></li> +<li>Plugin's artifact coordinates: <code>com.mycompany.maven:simple-maven-plugin:1.0-SNAPSHOT</code></li> +<li>One goal: <b>simple</b></li> +<li>One result: <code>simple-report.html</code></li></ul> <p>Our Maven plugin project has 2 files only:</p> <ul> - -<li> -<p><code>./pom.xml</code></p></li> -<li> -<p><code>./src/main/java/com/mycompany/maven/SimpleReport.java</code></p></li> -</ul> +<li><code>./pom.xml</code></li> +<li><code>./src/main/java/com/mycompany/maven/SimpleReport.java</code></li></ul> <p>The below examples can be copied and pasted as a template.</p><section> -<h4>./pom.xml</h4> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" +<h3>./pom.xml</h3> +<div class="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 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -326,11 +287,9 @@ under the License. </plugins> </build> -</project> -</code></pre></div></section><section> -<h4>./src/main/java/com/mycompany/maven/SimpleReport.java</h4> - -<div class="source"><pre class="prettyprint linenums"><code class="language-java">package com.mycompany.maven; +</project></pre></div></section><section> +<h3>./src/main/java/com/mycompany/maven/SimpleReport.java</h3> +<div class="source"><pre class="prettyprint linenums">package com.mycompany.maven; import java.util.Locale; @@ -427,26 +386,19 @@ public class SimpleReport extends Abstra } -} -</code></pre></div></section><section> -<h4>Building the Simple Plugin</h4> +}</pre></div></section><section> +<h3>Building the Simple Plugin</h3> <p>Building the plugin is done by executing the below command in the root directory of the plugin project:</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn install -</code></pre></div> +<div> +<pre>$ mvn install</pre></div> <p>This command will:</p> <ul> - -<li> -<p>compile your code</p></li> -<li> -<p>produces the plugin JAR artifact (<code>./target/simple-maven-plugin-1.0-SNAPSHOT.jar</code>)</p></li> -<li> -<p>copy the artifact to your local repository so that it can be “consumed” by other projects (which is the purpose of a plugin, right?).</p></li> -</ul> +<li>compile your code</li> +<li>produces the plugin JAR artifact (<code>./target/simple-maven-plugin-1.0-SNAPSHOT.jar</code>)</li> +<li>copy the artifact to your local repository so that it can be "consumed" by other projects (which is the purpose of a plugin, right?).</li></ul> <p>To make sure everything went well and is properly declared, you can now execute the below command in any other Maven project directory:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-bash">$ mvn com.mycompany.maven:simple-maven-plugin:1.0-SNAPSHOT:help +<div> +<pre>$ mvn com.mycompany.maven:simple-maven-plugin:1.0-SNAPSHOT:help [INFO] --- simple-maven-plugin:1.0-SNAPSHOT:help (default-cli) @ hardware-connectors --- [INFO] Simple Plugin 1.0-SNAPSHOT @@ -467,12 +419,10 @@ simple:simple [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS -[INFO] ------------------------------------------------------------------------ -</code></pre></div></section><section> -<h4>Invoking the Simple Plugin</h4> -<p>To invoke the <em>report Mojo</em> of our plugin in another Maven project, we just need to declare the plugin in the <a href="/plugins/maven-site-plugin/examples/configuring-reports.html"><code><reporting></code></a> section of its <code>pom.xml</code> as in the example below:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +[INFO] ------------------------------------------------------------------------</pre></div></section><section> +<h3>Invoking the Simple Plugin</h3> +<p>To invoke the <i>report Mojo</i> of our plugin in another Maven project, we just need to declare the plugin in the <a href="/plugins/maven-site-plugin/examples/configuring-reports.html"><code><reporting></code></a> section of its <code>pom.xml</code> as in the example below:</p> +<div class="source"><pre class="prettyprint linenums"><project> ... <reporting> <plugins> @@ -484,48 +434,32 @@ simple:simple </plugins> </reporting> ... -</project> -</code></pre></div> -<p>Note: When no specific report is specified, all of the <em>Mojos</em> in the plugin, that are declared as “reporting” will be executed. <a href="/plugins/maven-site-plugin/examples/configuring-reports.html">More information about configuring reports</a>.</p></section></section><section> -<h3>More Information</h3><section> -<h4>The Doxia Sink API</h4> +</project></pre></div> +<p>Note: When no specific report is specified, all of the <i>Mojos</i> in the plugin, that are declared as "reporting" will be executed. <a href="/plugins/maven-site-plugin/examples/configuring-reports.html">More information about configuring reports</a>.</p></section></section><section> +<h2>More Information</h2><section> +<h3>The Doxia Sink API</h3> <p>In your <code>executeReport()</code> method, you will leverage the <a href="/doxia/doxia/doxia-sink-api/">Doxia Sink API</a> to add elements to the report document.</p> <p>You will use the <a href="/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html"><code>Sink</code></a> object associated to the report:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-java">Sink sink = getSink(); -</code></pre></div> +<div class="source"><pre class="prettyprint linenums">Sink sink = getSink();</pre></div> <p>This object allows you to append new elements to the report document (initially empty). Unlike some DOM manipulation APIs, you cannot insert elements in already existing elements, or remove elements.</p> <p>The elements that you append to the document will look familiar if you have basic knowledge of HTML. Most of the elements have opening and closing tags, like <code>sink.body()</code> (opening) and <code>sink.body_()</code> (closing).</p> <ul> - -<li> -<p><code>sink.head()</code> and <code>sink.head_()</code></p></li> -<li> -<p><code>sink.paragraph()</code> and <code>sink.paragraph_()</code></p></li> -<li> -<p><code>sink.section1()</code> and <code>sink.section1_()</code></p></li> -<li> -<p><code>sink.bold()</code> and <code>sink.bold_()</code></p></li> -<li> -<p>etc.</p></li> -</ul> -<p><strong>Do not forget to close elements!</strong></p> +<li><code>sink.head()</code> and <code>sink.head_()</code></li> +<li><code>sink.paragraph()</code> and <code>sink.paragraph_()</code></li> +<li><code>sink.section1()</code> and <code>sink.section1_()</code></li> +<li><code>sink.bold()</code> and <code>sink.bold_()</code></li> +<li>etc.</li></ul> +<p><b>Do not forget to close elements!</b></p> <p>At the very least, a document should include the following:</p> <ul> - -<li> -<p>Head and title (<code>sink.head()</code> and <code>sink.title()</code>)</p></li> -<li> -<p>Body (<code>sink.body()</code>)</p></li> -<li> -<p>Section 1 with title (<code>sink.section1()</code> and <code>sink.sectionTitle1()</code>)</p></li> -</ul> -<p>The <a href="/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html"><code>Sink</code></a> object allows you to add raw text with the <em>rawText()</em> method. More precisely, it allows you to add raw HTML code into the document for full flexibility. However, you should limit the usage of this method as you may add elements that are not supported by non-HTML renderers (like <a href="/plugins/maven-pdf-plugin/"><code>maven-pdf-site</code></a>).</p> -<p>The Doxia Sink API allows you to specify <a href="/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/SinkEventAttributes.html"><em>SinkEventAttributes</em></a> to each element, i.e. HTML properties, notably the class and the ID of an object, which allows for easy customization with an appropriate CSS (either provided by the specified Maven Skin, or by the project itself).</p></section><section> -<h4>Creating more than one document</h4> -<p>You may need to create not just one HTML file, but several of them (like Javadoc produces one HTML file for each Java class). To do so, you will need to get a new <em>Sink</em> for each HTML file you need to produce. This is achieved by using the <a href="/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/SinkFactory.html"><code>SinkFactory</code></a> object that you can easily obtain with the <a href="/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html#getSinkFactory"><code>getSinkFactory()</code></a> method of your <a href="/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html"><code>AbstractMavenReport</code></a> instance, as in the example below.</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-java">public class SimpleReport extends AbstractMavenReport { +<li>Head and title (<code>sink.head()</code> and <code>sink.title()</code>)</li> +<li>Body (<code>sink.body()</code>)</li> +<li>Section 1 with title (<code>sink.section1()</code> and <code>sink.sectionTitle1()</code>)</li></ul> +<p>The <a href="/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html"><code>Sink</code></a> object allows you to add raw text with the <i>rawText()</i> method. More precisely, it allows you to add raw HTML code into the document for full flexibility. However, you should limit the usage of this method as you may add elements that are not supported by non-HTML renderers (like <a href="/plugins/maven-pdf-plugin/"><code>maven-pdf-site</code></a>).</p> +<p>The Doxia Sink API allows you to specify <a href="/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/SinkEventAttributes.html"><i>SinkEventAttributes</i></a> to each element, i.e. HTML properties, notably the class and the ID of an object, which allows for easy customization with an appropriate CSS (either provided by the specified Maven Skin, or by the project itself).</p></section><section> +<h3>Creating more than one document</h3> +<p>You may need to create not just one HTML file, but several of them (like Javadoc produces one HTML file for each Java class). To do so, you will need to get a new <i>Sink</i> for each HTML file you need to produce. This is achieved by using the <a href="/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/SinkFactory.html"><code>SinkFactory</code></a> object that you can easily obtain with the <a href="/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html#getSinkFactory"><code>getSinkFactory()</code></a> method of your <a href="/shared/maven-reporting-impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html"><code>AbstractMavenReport</code></a> instance, as in the example below.</p> +<div class="source"><pre class="prettyprint linenums">public class SimpleReport extends AbstractMavenReport { ... @@ -555,15 +489,15 @@ simple:simple otherSink.head(); otherSink.title(); otherSink.text("The Other Report"); - ... -</code></pre></div> + ...</pre></div> <p>The above example will create a <code>other-report.html</code> HTML file along with <code>simple-report.html</code>.</p> -<p>Note: Despite the fact that you will be creating additional HTML files, the Velocity variable <code>$currentFileName</code> passed to the <code>site.vm</code> script of the Maven Skin will keep the name of the original report (i.e. the result of your <em>getOutputName()</em> method). <a href="/doxia/doxia-sitetools/doxia-site-renderer/">More information about the Velocity variables</a>.</p></section></section><section> -<h3>Resources</h3> -<p>1 <a href="./guide-java-plugin-development.html">Guide to Developing Java Plugins</a>: Starting point, since a reporting plugin is a plugin…</p> -<p>1 <a href="/shared/maven-reporting-api/">Maven Reporting API</a>: The Reporting API to implement when a Mojo provides reporting for site.</p> -<p>1 <a href="/shared/maven-reporting-impl/">Maven Reporting Implementation</a>: Base implementation of both Reporting API and Plugin API.</p> -<p>1 <a href="/doxia/doxia/doxia-sink-api/">Doxia Sink API</a>: API to generate content.</p></section></section></section> +<p>Note: Despite the fact that you will be creating additional HTML files, the Velocity variable <code>$currentFileName</code> passed to the <code>site.vm</code> script of the Maven Skin will keep the name of the original report (i.e. the result of your <i>getOutputName()</i> method). <a href="/doxia/doxia-sitetools/doxia-site-renderer/">More information about the Velocity variables</a>.</p></section></section><section> +<h2>Resources</h2> +<ol style="list-style-type: decimal"> +<li><a href="./guide-java-plugin-development.html">Guide to Developing Java Plugins</a>: Starting point, since a reporting plugin is a plugin...</li> +<li><a href="/shared/maven-reporting-api/">Maven Reporting API</a>: The Reporting API to implement when a Mojo provides reporting for site.</li> +<li><a href="/shared/maven-reporting-impl/">Maven Reporting Implementation</a>: Base implementation of both Reporting API and Plugin API.</li> +<li><a href="/doxia/doxia/doxia-sink-api/">Doxia Sink API</a>: API to generate content.</li></ol></section></section> </main> </div> </div> Modified: maven/website/content/install.html ============================================================================== --- maven/website/content/install.html (original) +++ maven/website/content/install.html Sat Feb 18 20:40:58 2023 @@ -149,7 +149,7 @@ under the License. --> <p>The installation of Apache Maven is a simple process of extracting the archive -and adding the <code>bin</code> directory with the <code>mvn</code> command to the <code>PATH</code>.</p> +and adding the <code>bin</code> folder with the <code>mvn</code> command to the <code>PATH</code>.</p> <p>Detailed steps are:</p> <ul> Modified: maven/website/content/issue-management.html ============================================================================== --- maven/website/content/issue-management.html (original) +++ maven/website/content/issue-management.html Sat Feb 18 20:40:58 2023 @@ -143,7 +143,7 @@ under the License. <p>Maven projects use <a href="https://www.atlassian.com/software/jira"; class="externalLink">Jira</a> as issue tracking and project management application.</p></section><section> <h2>Issue Management</h2> -<p>Maven is composed of nearly <a href="/scm.html#maven-sources-overview">100 parts</a>, each one having its own Jira project or component: +<p>Maven is composed of nearly <a href="/scm.html#Maven_Sources_Overview">100 parts</a>, each one having its own Jira project or component: <strong>see the <a href="https://cwiki.apache.org/confluence/display/MAVEN/Maven+JIRA+issues+overview"; class="externalLink">Maven Jira issues overview</a> to get a summary of open issues</strong>.</p> <p>Issues, bugs, and feature requests should be submitted to the following issue management systems depending on which component is involved:</p>
