MPLUGIN-67: Document somewhere the minimum version of maven required by the plugin

MPLUGIN-11: add an introduction to plugin configuration in plugin report

o reformated report to include system requirements and usage parts
o added modello to generate requirements object
o updated i18n

git-svn-id: https://svn.apache.org/repos/asf/maven/plugin-tools/trunk@617684 13f79535-47bb-0310-9956-ffa450edef68

maven-plugin-plugin/pom.xml

@@ -210,6 +210,25 @@
       </plugin>
     </plugins>
     -->
+    <plugins>
+      <plugin>
+        <groupId>org.codehaus.modello</groupId>
+        <artifactId>modello-maven-plugin</artifactId>
+        <version>1.0-alpha-14</version>
+        <executions>
+          <execution>
+            <goals>
+              <goal>java</goal>
+            </goals>
+          </execution>
+        </executions>
+        <configuration>
+          <version>1.0.0</version>
+          <model>src/main/mdo/pluginRequirements.mdo</model>
+        </configuration>
+      </plugin>
+
+    </plugins>
   </build>
 
   <properties>
@@ -230,4 +249,8 @@
     <url>http://svn.apache.org/viewcvs.cgi/maven/plugin-tools/trunk/maven-plugin-plugin/</url>
   </scm>
 
+  <issueManagement>
+    <system>jira</system>
+    <url>http://jira.codehaus.org/browse/MPLUGIN</url>
+  </issueManagement>
 </project>

maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java

@@ -19,8 +19,17 @@ package org.apache.maven.plugin.plugin;
  * under the License.
  */
 
+import java.io.File;
+import java.io.IOException;
+import java.util.Iterator;
+import java.util.Locale;
+import java.util.Map;
+import java.util.ResourceBundle;
+
 import org.apache.maven.doxia.sink.Sink;
 import org.apache.maven.doxia.siterenderer.Renderer;
+import org.apache.maven.model.Plugin;
+import org.apache.maven.model.ReportPlugin;
 import org.apache.maven.plugin.descriptor.InvalidPluginDescriptorException;
 import org.apache.maven.plugin.descriptor.MojoDescriptor;
 import org.apache.maven.plugin.descriptor.PluginDescriptor;
@@ -29,17 +38,11 @@ import org.apache.maven.reporting.AbstractMavenReport;
 import org.apache.maven.reporting.AbstractMavenReportRenderer;
 import org.apache.maven.reporting.MavenReportException;
 import org.apache.maven.tools.plugin.extractor.ExtractionException;
-import org.apache.maven.tools.plugin.generator.Generator;
 import org.apache.maven.tools.plugin.generator.PluginXdocGenerator;
 import org.apache.maven.tools.plugin.scanner.MojoScanner;
 import org.apache.maven.tools.plugin.util.PluginUtils;
 import org.codehaus.plexus.util.StringUtils;
-
+import org.codehaus.plexus.util.xml.Xpp3Dom;
-import java.io.File;
-import java.io.IOException;
-import java.util.Iterator;
-import java.util.Locale;
-import java.util.ResourceBundle;
 
 /**
  * Generates the Plugin's documentation report.
@@ -83,6 +86,28 @@ public class PluginReport
      */
     protected MojoScanner mojoScanner;
 
+    /**
+     * Specify some requirements to execute this plugin.
+     * Example:
+     * <pre>
+     * &lt;requirements&gt;<br/>
+     *   &lt;maven&gt;2.0&lt;/maven&gt;<br/>
+     *   &lt;jdk&gt;1.4&lt;/jdk&gt;<br/>
+     *   &lt;memory&gt;256m&lt;/memory&gt;<br/>
+     *   &lt;diskSpace&gt;1m&lt;/diskSpace&gt;<br/>
+     *   &lt;others&gt;<br/>
+     *     &lt;property&gt;<br/>
+     *       &lt;name&gt;SVN&lt;/name&gt;<br/>
+     *       &lt;value&gt;1.4.6&lt;/value&gt;<br/>
+     *     &lt;/property&gt;<br/>
+     *   &lt;/others&gt;<br/>
+     * &lt;/requirements&gt;
+     * </pre>
+     *
+     * @parameter
+     */
+    private Requirements requirements;
+
     /** {@inheritDoc} */
     protected Renderer getSiteRenderer()
     {
@@ -133,7 +158,8 @@ public class PluginReport
             generatePluginDocumentation( pluginDescriptor );
 
             // Write the overview
-            PluginOverviewRenderer r = new PluginOverviewRenderer( getSink(), pluginDescriptor, locale );
+            PluginOverviewRenderer r = new PluginOverviewRenderer( project, requirements, getSink(), pluginDescriptor,
+                                                                   locale );
             r.render();
         }
         catch ( InvalidPluginDescriptorException e )
@@ -174,7 +200,7 @@ public class PluginReport
             File outputDir = new File( getOutputDirectory() );
             outputDir.mkdirs();
 
-            Generator generator = new PluginXdocGenerator();
+            PluginXdocGenerator generator = new PluginXdocGenerator();
             generator.execute( outputDir, pluginDescriptor );
         }
         catch ( IOException e )
@@ -196,14 +222,23 @@ public class PluginReport
     static class PluginOverviewRenderer
         extends AbstractMavenReportRenderer
     {
+        private final MavenProject project;
+
+        private final Requirements requirements;
+
         private final PluginDescriptor pluginDescriptor;
 
         private final Locale locale;
 
-        public PluginOverviewRenderer( Sink sink, PluginDescriptor pluginDescriptor, Locale locale )
+        public PluginOverviewRenderer( MavenProject project, Requirements requirements, Sink sink,
+                                       PluginDescriptor pluginDescriptor, Locale locale )
         {
             super( sink );
 
+            this.project = project;
+
+            this.requirements = ( requirements == null ? new Requirements() : requirements );
+
             this.pluginDescriptor = pluginDescriptor;
 
             this.locale = locale;
@@ -220,13 +255,14 @@ public class PluginReport
         {
             startSection( getTitle() );
 
+            if ( pluginDescriptor.getMojos() != null && pluginDescriptor.getMojos().size() > 0 )
+            {
                 paragraph( getBundle( locale ).getString( "report.plugin.goals.intro" ) );
 
                 startTable();
 
                 String goalColumnName = getBundle( locale ).getString( "report.plugin.goals.column.goal" );
                 String descriptionColumnName = getBundle( locale ).getString( "report.plugin.goals.column.description" );
-
                 tableHeader( new String[] { goalColumnName, descriptionColumnName } );
 
                 for ( Iterator i = pluginDescriptor.getMojos().iterator(); i.hasNext(); )
@@ -234,16 +270,17 @@ public class PluginReport
                     MojoDescriptor mojo = (MojoDescriptor) i.next();
 
                     String goalName = mojo.getFullGoalName();
+
                     /*
                      * Added ./ to define a relative path
                      * @see AbstractMavenReportRenderer#getValidHref(java.lang.String)
                      */
                     String goalDocumentationLink = "./" + mojo.getGoal() + "-mojo.html";
+
                     String description = mojo.getDescription();
                     if ( StringUtils.isEmpty( mojo.getDescription() ) )
                     {
                         description = getBundle( locale ).getString( "report.plugin.goal.nodescription" );
-
                     }
 
                     sink.tableRow();
@@ -253,8 +290,215 @@ public class PluginReport
                 }
 
                 endTable();
+            }
+            else
+            {
+                paragraph( getBundle( locale ).getString( "report.plugin.nogoal" ) );
+            }
+
+            endSection();
+
+            startSection( getBundle( locale ).getString( "report.plugin.systemrequirements" ) );
+
+            paragraph( getBundle( locale ).getString( "report.plugin.systemrequirements.intro" ) );
+
+            startTable();
+
+            String maven = discoverMavenRequirement( project, requirements );
+            sink.tableRow();
+            tableCell( getBundle( locale ).getString( "report.plugin.systemrequirements.maven" ) );
+            tableCell( ( maven != null ? maven : getBundle( locale )
+                .getString( "report.plugin.systemrequirements.nominimum" ) ) );
+            sink.tableRow_();
+
+            String jdk = discoverJdkRequirement( project, requirements );
+            sink.tableRow();
+            tableCell( getBundle( locale ).getString( "report.plugin.systemrequirements.jdk" ) );
+            tableCell( ( jdk != null ? jdk : getBundle( locale )
+                .getString( "report.plugin.systemrequirements.nominimum" ) ) );
+            sink.tableRow_();
+
+            sink.tableRow();
+            tableCell( getBundle( locale ).getString( "report.plugin.systemrequirements.memory" ) );
+            tableCell( ( StringUtils.isNotEmpty( requirements.getMemory() )
+                                                                           ? requirements.getMemory()
+                                                                           : getBundle( locale )
+                                                                               .getString(
+                                                                                           "report.plugin.systemrequirements.nominimum" ) ) );
+            sink.tableRow_();
+
+            sink.tableRow();
+            tableCell( getBundle( locale ).getString( "report.plugin.systemrequirements.diskspace" ) );
+            tableCell( ( StringUtils.isNotEmpty( requirements.getDiskSpace() )
+                                                                              ? requirements.getDiskSpace()
+                                                                              : getBundle( locale )
+                                                                                  .getString(
+                                                                                              "report.plugin.systemrequirements.nominimum" ) ) );
+            sink.tableRow_();
+
+            if ( requirements.getOthers() != null && requirements.getOthers().size() > 0 )
+            {
+                for ( Iterator it = requirements.getOthers().keySet().iterator(); it.hasNext(); )
+                {
+                    String key = it.next().toString();
+
+                    sink.tableRow();
+                    tableCell( key );
+                    tableCell( ( StringUtils.isNotEmpty( requirements.getOthers().getProperty( key ) ) ? requirements
+                        .getOthers().getProperty( key ) : getBundle( locale )
+                        .getString( "report.plugin.systemrequirements.nominimum" ) ) );
+                    sink.tableRow_();
+                }
+            }
+            endTable();
+
+            endSection();
+
+            startSection( getBundle( locale ).getString( "report.plugin.usage" ) );
+
+            // Configuration
+            sink.paragraph();
+            text( getBundle( locale ).getString( "report.plugin.usage.intro" ) );
+
+            StringBuffer sb = new StringBuffer();
+            sb.append( "<project>" ).append( '\n' );
+            sb.append( "  ..." ).append( '\n' );
+            sb.append( "  <build>" ).append( '\n' );
+            sb.append( "    <pluginManagement>" ).append( '\n' );
+            sb.append( "      <plugin>" ).append( '\n' );
+            sb.append( "        <groupId>" ).append( pluginDescriptor.getGroupId() ).append( "<groupId>" )
+                .append( '\n' );
+            sb.append( "        <artifactId>" ).append( pluginDescriptor.getArtifactId() ).append( "<artifactId>" )
+                .append( '\n' );
+            sb.append( "        <version>" ).append( pluginDescriptor.getVersion() ).append( "<version>" )
+                .append( '\n' );
+            sb.append( "      </plugin>" ).append( '\n' );
+            sb.append( "      ..." ).append( '\n' );
+            sb.append( "    </pluginManagement>" ).append( '\n' );
+            sb.append( "    <plugins>" ).append( '\n' );
+            sb.append( "      <plugin>" ).append( '\n' );
+            sb.append( "        <groupId>" ).append( pluginDescriptor.getGroupId() ).append( "<groupId>" )
+                .append( '\n' );
+            sb.append( "        <artifactId>" ).append( pluginDescriptor.getArtifactId() ).append( "<artifactId>" )
+                .append( '\n' );
+            sb.append( "      </plugin>" ).append( '\n' );
+            sb.append( "      ..." ).append( '\n' );
+            sb.append( "    </plugins>" ).append( '\n' );
+            sb.append( "  </build>" ).append( '\n' );
+            sb.append( "  ..." ).append( '\n' );
+            sb.append( "</project>" ).append( '\n' );
+
+            //mvn -U
+            verbatimText( sb.toString() );
+
+            sink.paragraph_();
 
             endSection();
         }
+
+        /**
+         * Try to lookup on the Maven prerequisites property.
+         * If not specified, uses the value defined by the user.
+         *
+         * @param project
+         * @param requirements
+         * @return the Maven version
+         */
+        private static String discoverMavenRequirement( MavenProject project, Requirements requirements )
+        {
+            String maven = requirements.getMaven();
+            if ( maven == null )
+            {
+                maven = ( project.getPrerequisites() != null ? project.getPrerequisites().getMaven() : null );
+            }
+
+            return maven;
+        }
+
+        /**
+         * Try to lookup on the <code>org.apache.maven.plugins:maven-compiler-plugin</code> plugin to
+         * find the value of the <code>target</code> option.
+         * If not specified, uses the value defined by the user.
+         * If not specified, uses the value of the system property <code>java.specification.version</code>.
+         *
+         * @param project
+         * @param requirements
+         * @return the JDK version
+         */
+        private static String discoverJdkRequirement( MavenProject project, Requirements requirements )
+        {
+            String jdk = requirements.getJdk();
+            if ( jdk == null )
+            {
+                if ( project.getPluginManagement() != null )
+                {
+                    jdk = discoverJdkRequirementFromPlugins( project.getPluginManagement().getPluginsAsMap() );
+                }
+            }
+            if ( jdk == null )
+            {
+                jdk = discoverJdkRequirementFromPlugins( project.getPluginArtifactMap() );
+            }
+            if ( jdk == null )
+            {
+                jdk = System.getProperty( "java.specification.version" );
+            }
+
+            return jdk;
+        }
+
+        /**
+         * @param pluginsAsMap
+         * @return the value of the <code>target</code> in the configuration of <code>maven-compiler-plugin</code>.
+         */
+        private static String discoverJdkRequirementFromPlugins( Map pluginsAsMap )
+        {
+            if ( pluginsAsMap == null )
+            {
+                return null;
+            }
+
+            String jdk = null;
+            for ( Iterator it = pluginsAsMap.keySet().iterator(); it.hasNext(); )
+            {
+                String key = it.next().toString();
+
+                if ( !key.equals( "org.apache.maven.plugins:maven-compiler-plugin" ) )
+                {
+                    continue;
+                }
+
+                Object value = pluginsAsMap.get( key );
+                Xpp3Dom pluginConf = null;
+
+                if ( value instanceof Plugin )
+                {
+                    Plugin plugin = (Plugin) value;
+
+                    pluginConf = (Xpp3Dom) plugin.getConfiguration();
+                }
+
+                if ( value instanceof ReportPlugin )
+                {
+                    ReportPlugin reportPlugin = (ReportPlugin) value;
+
+                    pluginConf = (Xpp3Dom) reportPlugin.getConfiguration();
+                }
+
+                if ( pluginConf == null )
+                {
+                    continue;
+                }
+
+                if ( pluginConf.getChild( "target" ) != null )
+                {
+                    continue;
+                }
+
+                jdk = pluginConf.getChild( "target" ).getValue();
+            }
+
+            return jdk;
+        }
     }
 }

maven-plugin-plugin/src/main/mdo/pluginRequirements.mdo

@@ -0,0 +1,78 @@
+<?xml version="1.0"?>
+
+<!--
+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.
+-->
+
+<model>
+  <id>pluginRequirements</id>
+  <name>PluginRequirements</name>
+  <description><![CDATA[Model to specify plugin requirements.]]></description>
+  <defaults>
+    <default>
+      <key>package</key>
+      <value>org.apache.maven.plugin.plugin</value>
+    </default>
+  </defaults>
+  <classes>
+    <class>
+      <name>Requirements</name>
+      <description>Plugin requirements.</description>
+      <version>1.0.0</version>
+      <fields>
+        <field>
+          <name>maven</name>
+          <description>The minimum version of Maven to run this plugin.</description>
+          <version>1.0.0</version>
+          <type>String</type>
+          <identifier>true</identifier>
+          <defaultValue>2.0</defaultValue>
+        </field>
+        <field>
+          <name>jdk</name>
+          <description>The minimum version of the JDK to run this plugin.</description>
+          <version>1.0.0</version>
+          <type>String</type>
+          <identifier>true</identifier>
+        </field>
+        <field>
+          <name>memory</name>
+          <description>The minimum memory needed to run this plugin.</description>
+          <version>1.0.0</version>
+          <type>String</type>
+        </field>
+        <field>
+          <name>diskSpace</name>
+          <description>The minimum diskSpace needed to run this plugin.</description>
+          <version>1.0.0</version>
+          <type>String</type>
+        </field>
+        <field>
+          <name>others</name>
+          <description>Others requirements properties.</description>
+          <version>1.0.0</version>
+          <type>Properties</type>
+          <association xml.mapStyle="inline">
+            <type>String</type>
+            <multiplicity>*</multiplicity>
+          </association>
+        </field>
+      </fields>
+    </class>
+  </classes>
+</model>

maven-plugin-plugin/src/main/resources/plugin-report.properties

@@ -21,7 +21,19 @@ report.plugin.name=Plugin documentation
 report.plugin.description=This report provides goals and parameters documentation of a plugin
 report.plugin.title=Plugin documentation
 
-report.plugin.goals.intro=Goals available:
+report.plugin.goals.nogoal=No goals available yet.
+report.plugin.goals.intro=Goals available for this plugin:
 report.plugin.goals.column.goal=Goal
 report.plugin.goals.column.description=Description
-report.plugin.goal.nodescription=No description
+report.plugin.goal.nodescription=No description.
+
+report.plugin.systemrequirements=System Requirements
+report.plugin.systemrequirements.intro=The following specifies the minimum requirements to run this Maven plugin:
+report.plugin.systemrequirements.nominimum= No minimum requirement.
+report.plugin.systemrequirements.maven=Maven
+report.plugin.systemrequirements.jdk=JDK
+report.plugin.systemrequirements.memory=Memory
+report.plugin.systemrequirements.diskspace=Disk Space
+
+report.plugin.usage=Usage
+report.plugin.usage.intro=You could run 'mvn -up' to get the latest version of this plugin, or specify the version in your project's plugin configuration:

maven-plugin-plugin/src/main/resources/plugin-report_en.properties

@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# NOTE:
+# This bundle is intentionally empty because English strings are provided by the base bundle via the parent chain. It
+# must be provided nevertheless such that a request for locale "en" will not errorneously pick up the bundle for the
+# JVM's default locale (which need not be "en"). See the method javadoc about
+#   ResourceBundle.getBundle(String, Locale, ClassLoader)
+# for a full description of the lookup strategy.

maven-plugin-plugin/src/main/resources/plugin-report_fr.properties

@@ -18,10 +18,22 @@
 #
 
 report.plugin.name=Documentation du plugin
-report.plugin.description=Ce rapport fournit de la documenations sur les goals et les paramètres d'un plugin
+report.plugin.description=Ce rapport fournit de la documentation sur les goals et les param\u00eatres d'un plugin
 report.plugin.title=Documentation du plugin
 
-report.plugin.goals.intro=Goals disponibles :
+report.plugin.goals.nogoal=Aucun goal disponible.
+report.plugin.goals.intro=Goals disponibles pour ce plugin:
 report.plugin.goals.column.goal=Goal
 report.plugin.goals.column.description=Description
-report.plugin.goal.nodescription=Pas de description
+report.plugin.goal.nodescription=Pas de description.
+
+report.plugin.systemrequirements=Exigences Syst\u00e8mes
+report.plugin.systemrequirements.intro=Ce qui suit sp\u00e9cifie les exigences minimales pour \u00e9x\u00e9cuter ce plugin Maven:
+report.plugin.systemrequirements.nominimum= Aucune \u00e9xigence minimale.
+report.plugin.systemrequirements.maven=Maven
+report.plugin.systemrequirements.jdk=JDK
+report.plugin.systemrequirements.memory=M\u00e9moire
+report.plugin.systemrequirements.diskspace=Espace Disque
+
+report.plugin.usage=Utilisation
+report.plugin.usage.intro=Vous pouvez appeler 'mvn -up' pour obtenir la derni\u00e8re version de ce plugin, ou sp\u00e9cifier la version dans la configuration de votre projet: