From c6276113ca51c1b09ac16aa620da52e7be090099 Mon Sep 17 00:00:00 2001 From: Vincent Siveton Date: Fri, 1 Feb 2008 22:38:22 +0000 Subject: [PATCH] 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 | 23 ++ .../maven/plugin/plugin/PluginReport.java | 310 ++++++++++++++++-- .../src/main/mdo/pluginRequirements.mdo | 78 +++++ .../main/resources/plugin-report.properties | 16 +- .../resources/plugin-report_en.properties | 23 ++ .../resources/plugin-report_fr.properties | 18 +- 6 files changed, 430 insertions(+), 38 deletions(-) create mode 100644 maven-plugin-plugin/src/main/mdo/pluginRequirements.mdo create mode 100644 maven-plugin-plugin/src/main/resources/plugin-report_en.properties diff --git a/maven-plugin-plugin/pom.xml b/maven-plugin-plugin/pom.xml index 131ed2a..e48e1e2 100644 --- a/maven-plugin-plugin/pom.xml +++ b/maven-plugin-plugin/pom.xml @@ -210,6 +210,25 @@ --> + + + org.codehaus.modello + modello-maven-plugin + 1.0-alpha-14 + + + + java + + + + + 1.0.0 + src/main/mdo/pluginRequirements.mdo + + + + @@ -230,4 +249,8 @@ http://svn.apache.org/viewcvs.cgi/maven/plugin-tools/trunk/maven-plugin-plugin/ + + jira + http://jira.codehaus.org/browse/MPLUGIN + diff --git a/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java b/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java index 999bdaa..453889f 100644 --- a/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java +++ b/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,24 +38,18 @@ 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 java.io.File; -import java.io.IOException; -import java.util.Iterator; -import java.util.Locale; -import java.util.ResourceBundle; +import org.codehaus.plexus.util.xml.Xpp3Dom; /** * Generates the Plugin's documentation report. * * @author Stephane Nicoll * @author Vincent Siveton - * @version $Id $ + * @version $Id$ * @goal report */ public class PluginReport @@ -83,6 +86,28 @@ public class PluginReport */ protected MojoScanner mojoScanner; + /** + * Specify some requirements to execute this plugin. + * Example: + * 
+     * <requirements>

+     *   <maven>2.0</maven>

+     *   <jdk>1.4</jdk>

+     *   <memory>256m</memory>

+     *   <diskSpace>1m</diskSpace>

+     *   <others>

+     *     <property>

+     *       <name>SVN</name>

+     *       <value>1.4.6</value>

+     *     </property>

+     *   </others>

+     * </requirements>
+     *
+ * + * @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,41 +255,250 @@ public class PluginReport { startSection( getTitle() ); - paragraph( getBundle( locale ).getString( "report.plugin.goals.intro" ) ); + 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(); ) + { + 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(); + tableCell( createLinkPatternedText( goalName, goalDocumentationLink ) ); + tableCell( description, true ); + sink.tableRow_(); + } + + 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 goalColumnName = getBundle( locale ).getString( "report.plugin.goals.column.goal" ); - String descriptionColumnName = getBundle( locale ).getString( "report.plugin.goals.column.description" ); + 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_(); - tableHeader( new String[]{goalColumnName, descriptionColumnName} ); + 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_(); - for ( Iterator i = pluginDescriptor.getMojos().iterator(); i.hasNext(); ) + 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 ) { - 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() ) ) + for ( Iterator it = requirements.getOthers().keySet().iterator(); it.hasNext(); ) { - description = getBundle( locale ).getString( "report.plugin.goal.nodescription" ); + 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_(); } - - sink.tableRow(); - tableCell( createLinkPatternedText( goalName, goalDocumentationLink ) ); - tableCell( description, true ); - 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( "" ).append( '\n' ); + sb.append( " ..." ).append( '\n' ); + sb.append( " " ).append( '\n' ); + sb.append( " " ).append( '\n' ); + sb.append( " " ).append( '\n' ); + sb.append( " " ).append( pluginDescriptor.getGroupId() ).append( "" ) + .append( '\n' ); + sb.append( " " ).append( pluginDescriptor.getArtifactId() ).append( "" ) + .append( '\n' ); + sb.append( " " ).append( pluginDescriptor.getVersion() ).append( "" ) + .append( '\n' ); + sb.append( " " ).append( '\n' ); + sb.append( " ..." ).append( '\n' ); + sb.append( " " ).append( '\n' ); + sb.append( " " ).append( '\n' ); + sb.append( " " ).append( '\n' ); + sb.append( " " ).append( pluginDescriptor.getGroupId() ).append( "" ) + .append( '\n' ); + sb.append( " " ).append( pluginDescriptor.getArtifactId() ).append( "" ) + .append( '\n' ); + sb.append( " " ).append( '\n' ); + sb.append( " ..." ).append( '\n' ); + sb.append( " " ).append( '\n' ); + sb.append( " " ).append( '\n' ); + sb.append( " ..." ).append( '\n' ); + sb.append( "" ).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 org.apache.maven.plugins:maven-compiler-plugin plugin to + * find the value of the target option. + * If not specified, uses the value defined by the user. + * If not specified, uses the value of the system property java.specification.version. + * + * @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 target in the configuration of maven-compiler-plugin. + */ + 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; } } } diff --git a/maven-plugin-plugin/src/main/mdo/pluginRequirements.mdo b/maven-plugin-plugin/src/main/mdo/pluginRequirements.mdo new file mode 100644 index 0000000..55bef68 --- /dev/null +++ b/maven-plugin-plugin/src/main/mdo/pluginRequirements.mdo @@ -0,0 +1,78 @@ + + + + + + pluginRequirements + PluginRequirements + + + + package + org.apache.maven.plugin.plugin + + + + + Requirements + Plugin requirements. + 1.0.0 + + + maven + The minimum version of Maven to run this plugin. + 1.0.0 + String + true + 2.0 + + + jdk + The minimum version of the JDK to run this plugin. + 1.0.0 + String + true + + + memory + The minimum memory needed to run this plugin. + 1.0.0 + String + + + diskSpace + The minimum diskSpace needed to run this plugin. + 1.0.0 + String + + + others + Others requirements properties. + 1.0.0 + Properties + + String + * + + + + + + diff --git a/maven-plugin-plugin/src/main/resources/plugin-report.properties b/maven-plugin-plugin/src/main/resources/plugin-report.properties index fda6135..262d0b3 100644 --- a/maven-plugin-plugin/src/main/resources/plugin-report.properties +++ b/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 \ No newline at end of file +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: diff --git a/maven-plugin-plugin/src/main/resources/plugin-report_en.properties b/maven-plugin-plugin/src/main/resources/plugin-report_en.properties new file mode 100644 index 0000000..96cf407 --- /dev/null +++ b/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. diff --git a/maven-plugin-plugin/src/main/resources/plugin-report_fr.properties b/maven-plugin-plugin/src/main/resources/plugin-report_fr.properties index 83987f7..b61e526 100644 --- a/maven-plugin-plugin/src/main/resources/plugin-report_fr.properties +++ b/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 \ No newline at end of file +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: