This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to annotated tag maven-help-plugin-2.0
in repository https://gitbox.apache.org/repos/asf/maven-help-plugin.git
commit 288f17530a5b9d3cc3e9b7f892c1755eb60e4d5a
Author: John Dennis Casey <jdca...@apache.org>
AuthorDate: Wed Oct 12 20:15:45 2005 +0000
Resolving: MNG-698, MNG-1081
Describe mojo is finished. Just need to finish documenting the projecthelp
plugin.
git-svn-id:
https://svn.apache.org/repos/asf/maven/components/trunk/maven-plugins/maven-projecthelp-plugin@315022
13f79535-47bb-0310-9956-ffa450edef68
---
pom.xml | 8 +
.../maven/plugins/projecthelp/DescribeMojo.java | 334 ++++++++++++++++++---
2 files changed, 299 insertions(+), 43 deletions(-)
diff --git a/pom.xml b/pom.xml
index b649dd1..40ed46b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -11,6 +11,14 @@
<version>2.0-beta-2-SNAPSHOT</version>
<inceptionYear>2001</inceptionYear>
+ <description>
+ Provides mojos aimed at helping the user to make sense out of
+ the build environment. It includes mojos to view the effective
+ POM and settings files, after inheritance and active profiles
+ have been applied, as well as a 'describe' mojo to give the
+ user information about how to use a plugin.
+ </description>
+
<prerequisites>
<maven>2.0-beta-4-SNAPSHOT</maven>
</prerequisites>
diff --git
a/src/main/java/org/apache/maven/plugins/projecthelp/DescribeMojo.java
b/src/main/java/org/apache/maven/plugins/projecthelp/DescribeMojo.java
index 303181b..2e89f23 100644
--- a/src/main/java/org/apache/maven/plugins/projecthelp/DescribeMojo.java
+++ b/src/main/java/org/apache/maven/plugins/projecthelp/DescribeMojo.java
@@ -11,10 +11,14 @@ import org.apache.maven.plugin.MojoFailureException;
import org.apache.maven.plugin.PluginManager;
import org.apache.maven.plugin.PluginManagerException;
import org.apache.maven.plugin.descriptor.MojoDescriptor;
+import org.apache.maven.plugin.descriptor.Parameter;
import org.apache.maven.plugin.descriptor.PluginDescriptor;
import org.apache.maven.plugin.version.PluginVersionResolutionException;
import org.apache.maven.project.MavenProject;
+import org.apache.maven.project.MavenProjectBuilder;
+import org.apache.maven.project.ProjectBuildingException;
import org.apache.maven.settings.Settings;
+import org.codehaus.plexus.component.repository.ComponentRequirement;
import java.io.File;
import java.io.FileWriter;
@@ -24,7 +28,10 @@ import java.util.Iterator;
import java.util.List;
/**
+ * Describes the attributes of a plugin and/or plugin mojo.
+ *
* @goal describe
+ * @requiresProject false
* @aggregator
*/
public class DescribeMojo
@@ -32,43 +39,91 @@ public class DescribeMojo
{
/**
- * @parameter expression="${plugin}"
+ * The plugin/mojo to describe. This must be specified in one of three
ways:
+ *
+ * 1. plugin-prefix
+ * 2. groupId:artifactId
+ * 3. groupId:artifactId:version
+ *
+ * @parameter expression="${plugin}" alias="prefix"
*/
private String plugin;
/**
- * @parameter
+ * The plugin groupId to describe.
+ * <br/>
+ * (Used with artifactId specification).
+ *
+ * @parameter expression="${groupId}"
*/
private String groupId;
/**
- * @parameter
+ * The plugin artifactId to describe.
+ * <br/>
+ * (Used with groupId specification).
+ *
+ * @parameter expression="${artifactId}"
*/
private String artifactId;
/**
- * @parameter
+ * The plugin version to describe.
+ * <br/>
+ * (Used with groupId/artifactId specification).
+ *
+ * @parameter expression="${version}"
*/
private String version;
/**
- * @parameter
+ * The goal name of a mojo to describe within the specified plugin.
+ * <br/>
+ * If this parameter is specified, only the corresponding mojo will
+ * <br/>
+ * be described, rather than the whole plugin.
+ *
+ * @parameter expression="${mojo}"
*/
private String mojo;
/**
+ * The plugin manager instance used to resolve plugin descriptors.
+ *
* @component role="org.apache.maven.plugin.PluginManager"
*/
private PluginManager pluginManager;
/**
+ * The project builder instance used to retrieve the super-project instance
+ * <br/>
+ * in the event there is no current MavenProject instance. Some
MavenProject
+ * <br/>
+ * instance has to be present to use in the plugin manager APIs.
+ *
+ * @component role="org.apache.maven.project.MavenProjectBuilder"
+ */
+ private MavenProjectBuilder projectBuilder;
+
+ /**
+ * The current project, if there is one. This is listed as optional, since
+ * <br/>
+ * the projecthelp plugin should be able to function on its own. If this
+ * <br/>
+ * parameter is empty at execution time, this mojo will instead use the
+ * <br/>
+ * super-project.
+ *
* @parameter expression="${project}"
- * @required
* @readonly
*/
private MavenProject project;
/**
+ * The current user system settings for use in Maven. This is used for
+ * <br/>
+ * plugin manager API calls.
+ *
* @parameter expression="${settings}"
* @required
* @readonly
@@ -76,6 +131,10 @@ public class DescribeMojo
private Settings settings;
/**
+ * The current build session instance. This is used for
+ * <br/>
+ * plugin manager API calls.
+ *
* @parameter expression="${session}"
* @required
* @readonly
@@ -83,6 +142,10 @@ public class DescribeMojo
private MavenSession session;
/**
+ * The local repository ArtifactRepository instance. This is used
+ * <br/>
+ * for plugin manager API calls.
+ *
* @parameter expression="${localRepository}"
* @required
* @readonly
@@ -90,13 +153,38 @@ public class DescribeMojo
private ArtifactRepository localRepository;
/**
- * @parameter
+ * If specified, this parameter will cause the plugin/mojo descriptions
+ * <br/>
+ * to be written to the path specified, instead of writing to the console.
+ *
+ * @parameter expression="${output}"
*/
private File output;
+
+ /**
+ * This flag specifies that full (verbose) information should be
+ * <br/>
+ * given. Use true/false.
+ *
+ * @parameter expression="${full}" default-value="false"
+ */
+ private boolean full;
public void execute()
throws MojoExecutionException, MojoFailureException
{
+ if ( project == null )
+ {
+ try
+ {
+ project = projectBuilder.buildStandaloneSuperProject(
localRepository );
+ }
+ catch ( ProjectBuildingException e )
+ {
+ throw new MojoExecutionException( "Error while retrieving the
super-project.", e );
+ }
+ }
+
PluginInfo pi = new PluginInfo();
parsePluginLookupInfo( pi );
@@ -148,6 +236,8 @@ public class DescribeMojo
}
}
}
+
+ getLog().info( "Wrote descriptions to: " + output );
}
else
{
@@ -275,42 +365,91 @@ public class DescribeMojo
private void describePlugin( PluginDescriptor pd, StringBuffer buffer )
{
- buffer.append( "Plugin: \'" ).append( pd.getName() ).append( '\'' );
+ String name = pd.getName();
+ if ( name == null )
+ {
+ name = pd.getId();
+ }
+
+ buffer.append( "Plugin: \'" ).append( name ).append( '\'' );
buffer.append( "\n-----------------------------------------------" );
buffer.append( "\nGroup Id: " ).append( pd.getGroupId() );
buffer.append( "\nArtifact Id: " ).append( pd.getArtifactId() );
buffer.append( "\nVersion: " ).append( pd.getVersion() );
buffer.append( "\nGoal Prefix: " ).append( pd.getGoalPrefix() );
- buffer.append( "\nDescription:\n\n" ).append( pd.getDescription()
).append( "\n" );
- buffer.append( "\nMojos:\n" );
-
- for ( Iterator it = pd.getMojos().iterator(); it.hasNext(); )
+
+ buffer.append( "\nDescription:\n\n" );
+ prettyAppend( formatDescription( pd.getDescription() ), buffer );
+ buffer.append( "\n" );
+
+ if ( full )
{
- MojoDescriptor md = (MojoDescriptor) it.next();
+ buffer.append( "\nMojos:\n" );
- buffer.append( "\nGoal: \'" ).append( md.getGoal() ).append( '\''
);
- buffer.append( "\n========================================" );
-
- describeMojoGuts( md, buffer );
+ String line = "\n===============================================";
- buffer.append( "\n\n" );
+ for ( Iterator it = pd.getMojos().iterator(); it.hasNext(); )
+ {
+ MojoDescriptor md = (MojoDescriptor) it.next();
+
+ buffer.append( line );
+ buffer.append( "\nGoal: \'" ).append( md.getGoal() ).append(
'\'' );
+ buffer.append( line );
+
+ describeMojoGuts( md, buffer, true );
+
+ buffer.append( line );
+ buffer.append( "\n\n" );
+ }
+ }
+ }
+
+ private String formatDescription( String description )
+ {
+ if ( description == null )
+ {
+ return null;
+ }
+
+ String result = description.replaceAll( " ?\\<br\\/?\\> ?", "\n" );
+
+ result = result.replaceAll(" ?\\<p\\> ?", "" );
+ result = result.replaceAll(" ?\\</p\\> ?", "\n\n" );
+
+ return result;
+ }
+
+ private void prettyAppend( String messagePart, StringBuffer buffer )
+ {
+ if ( messagePart != null && messagePart.length() > 0 )
+ {
+ buffer.append( messagePart );
+ }
+ else
+ {
+ buffer.append( "Unknown" );
}
}
private void describeMojo( MojoDescriptor md, StringBuffer buffer )
{
+ String line = "\n===============================================";
+
buffer.append( "Mojo: \'" ).append( md.getFullGoalName() ).append(
'\'' );
- buffer.append( "\n-----------------------------------------------" );
+ buffer.append( line );
buffer.append( "\nGoal: \'" ).append( md.getGoal() ).append( "\'" );
- describeMojoGuts( md, buffer );
+ describeMojoGuts( md, buffer, full );
+ buffer.append( line );
buffer.append( "\n\n" );
}
- private void describeMojoGuts( MojoDescriptor md, StringBuffer buffer )
+ private void describeMojoGuts( MojoDescriptor md, StringBuffer buffer,
boolean fullDescription )
{
- buffer.append( "\nDescription:\n\n" ).append( md.getDescription()
).append( "\n" );
+ buffer.append( "\nDescription:\n\n" );
+ prettyAppend( formatDescription( md.getDescription() ), buffer );
+ buffer.append( "\n" );
String deprecation = md.getDeprecated();
@@ -319,42 +458,151 @@ public class DescribeMojo
buffer.append( "\n\nNOTE: This mojo is deprecated.\n" ).append(
deprecation ).append( "\n" );
}
- buffer.append( "\nImplementation: " ).append( md.getImplementation() );
- buffer.append( "\nLanguage: " ).append( md.getLanguage() );
-
- String phase = md.getPhase();
- if ( phase != null )
+ if ( fullDescription )
{
- buffer.append( "\nBound to Phase: " ).append( phase );
+ buffer.append( "\nImplementation: " ).append(
md.getImplementation() );
+ buffer.append( "\nLanguage: " ).append( md.getLanguage() );
+
+ String phase = md.getPhase();
+ if ( phase != null )
+ {
+ buffer.append( "\nBound to Phase: " ).append( phase );
+ }
+
+ String eGoal = md.getExecuteGoal();
+ String eLife = md.getExecuteLifecycle();
+ String ePhase = md.getExecutePhase();
+
+ if ( eGoal != null || ePhase != null )
+ {
+ buffer.append( "\n\nBefore this mojo executes, it will
call:\n" );
+
+ if ( eGoal != null )
+ {
+ buffer.append( "\nSingle mojo: \'" ).append( eGoal
).append( "\'" );
+ }
+
+ if ( ePhase != null )
+ {
+ buffer.append( "\nPhase: \'" ).append( ePhase ).append(
"\'" );
+
+ if ( eLife != null )
+ {
+ buffer.append( " in Lifecycle Overlay: \'" ).append(
eLife ).append( "\'" );
+ }
+ }
+ }
+
+ describeMojoParameters( md, buffer );
+
+ describeMojoRequirements( md, buffer );
}
+ }
+
+ private void describeMojoRequirements( MojoDescriptor md, StringBuffer
buffer )
+ {
+ buffer.append( "\n" );
- String eGoal = md.getExecuteGoal();
- String eLife = md.getExecuteLifecycle();
- String ePhase = md.getExecutePhase();
+ List reqs = md.getRequirements();
- if ( eGoal != null || ePhase != null )
+ if ( reqs == null || reqs.isEmpty() )
{
- buffer.append( "\n\nBefore this mojo executes, it will call:\n" );
+ buffer.append( "\nThis mojo doesn't have any component
requirements." );
+ }
+ else
+ {
+ buffer.append( "\nComponent Requirements:\n" );
- if ( eGoal != null )
- {
- buffer.append( "\nSingle mojo: \'" ).append( eGoal ).append(
"\'" );
- }
+ String line = "\n-----------------------------------------------";
- if ( ePhase != null )
+ int idx = 0;
+ for ( Iterator it = reqs.iterator(); it.hasNext(); )
{
- buffer.append( "\nPhase: \'" ).append( ePhase ).append( "\'" );
+ ComponentRequirement req = (ComponentRequirement) it.next();
+
+ buffer.append( line );
+
+ buffer.append( "\n[" ).append( idx++ ).append( "] " );
+ buffer.append( "Role: " ).append( req.getRole() );
- if ( eLife != null )
+ String hint = req.getRoleHint();
+ if ( hint != null )
{
- buffer.append( " in Lifecycle Overlay: \'" ).append( eLife
).append( "\'" );
+ buffer.append( "\nRole-Hint: " ).append( hint );
}
+
+ buffer.append( "\n" );
}
+
+ buffer.append( line );
}
+ }
+
+ private void describeMojoParameters( MojoDescriptor md, StringBuffer
buffer )
+ {
+ buffer.append( "\n" );
- List parameters = md.getParameters();
+ List params = md.getParameters();
- List requirements = md.getRequirements();
+ if ( params == null || params.isEmpty() )
+ {
+ buffer.append( "\nThis mojo doesn't use any parameters." );
+ }
+ else
+ {
+ buffer.append( "\nParameters:" );
+
+ String line = "\n-----------------------------------------------";
+
+ int idx = 0;
+ for ( Iterator it = params.iterator(); it.hasNext(); )
+ {
+ Parameter parameter = (Parameter) it.next();
+
+ buffer.append( line );
+ buffer.append( "\n\n[" ).append( idx++ ).append( "] " );
+ buffer.append( "Name: " );
+ prettyAppend( parameter.getName(), buffer );
+
+ String alias = parameter.getAlias();
+ if ( alias != null )
+ {
+ buffer.append( " (Alias: " ).append( alias ).append( ")" );
+ }
+
+ buffer.append( "\nType: " );
+ prettyAppend( parameter.getType(), buffer );
+
+ String expression = parameter.getExpression();
+ if ( expression != null )
+ {
+ buffer.append( "\nExpression: " ).append( expression );
+ }
+
+ String defaultVal = parameter.getDefaultValue();
+ if ( defaultVal != null )
+ {
+ buffer.append( "\nDefault value: \'" ).append( defaultVal
);
+ }
+
+ buffer.append( "\nRequired: " ).append( parameter.isRequired()
);
+ buffer.append( "\nDirectly editable: " ).append(
parameter.isEditable() );
+
+ buffer.append( "\nDescription:\n\n" );
+ prettyAppend( formatDescription( parameter.getDescription() ),
buffer );
+
+ String deprecation = parameter.getDeprecated();
+
+ if ( deprecation != null )
+ {
+ buffer.append( "\n\nNOTE: This parameter is deprecated.\n"
).append( deprecation ).append( "\n" );
+ }
+
+ buffer.append( "\n" );
+ }
+
+ buffer.append( line );
+ }
}
public final String getPlugin()
--
To stop receiving notification emails like this one, please contact
"commits@maven.apache.org" <commits@maven.apache.org>.
