From 64aef4d0997081e8a748787c86d13a140b703472 Mon Sep 17 00:00:00 2001 From: Vincent Siveton Date: Sat, 21 Oct 2006 15:06:42 +0000 Subject: [PATCH] MNG-2461: Write JavaDoc documentation o added Javadoc git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@466408 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/maven/plugin/AbstractMojo.java | 134 +++++++++++++++++- .../apache/maven/plugin/ContextEnabled.java | 37 ++++- .../java/org/apache/maven/plugin/Mojo.java | 36 ++++- .../maven/plugin/MojoExecutionException.java | 37 ++++- .../maven/plugin/MojoFailureException.java | 17 ++- .../org/apache/maven/plugin/logging/Log.java | 111 ++++++++++++++- .../maven/plugin/logging/SystemStreamLog.java | 97 +++++++++---- 7 files changed, 427 insertions(+), 42 deletions(-) diff --git a/maven-plugin-api/src/main/java/org/apache/maven/plugin/AbstractMojo.java b/maven-plugin-api/src/main/java/org/apache/maven/plugin/AbstractMojo.java index a270efac8a..d465d33654 100644 --- a/maven-plugin-api/src/main/java/org/apache/maven/plugin/AbstractMojo.java +++ b/maven-plugin-api/src/main/java/org/apache/maven/plugin/AbstractMojo.java @@ -1,7 +1,7 @@ package org.apache.maven.plugin; /* - * Copyright 2001-2005 The Apache Software Foundation. + * Copyright 2005-2006 The Apache Software Foundation. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -22,19 +22,144 @@ import org.apache.maven.plugin.logging.SystemStreamLog; import java.util.Map; /** + * Abstract class to provide most of the infrastructure required to implement a Mojo except for + * the execute method. + *
+ * The implementation should have a goal annotation in the class-level javadoc annotation: + * 
+ * /**
+ *  * @goal goalName
+ *  */
+ *
+ * + * There are also a number of class-level javadoc annotations which can be used to control how and when the + * Mojo is executed: + *
+ *
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Descriptor ElementAnnotationRequired?Notes
goal@goal <goalName>YesThe name for the Mojo that users will reference from the command line to execute the Mojo directly, + * or inside a POM in order to provide Mojo-specific configuration.
implementationnone (detected)YesThe Mojo's fully-qualified class name (or script path in the case of non-Java Mojos).
languagenone (detected)No. Default: javaThe implementation language for this Mojo (Java, beanshell, etc.).
configurator@configurator <roleHint>NoThe configurator type to use when injecting parameter values into this Mojo. The value is normally + * deduced from the Mojo's implementation language, but can be specified to allow a custom + * ComponentConfigurator implementation to be used. + *
+ * NOTE: This will only be used in very special cases, using a highly controlled vocabulary of possible + * values. (Elements like this are why it's a good idea to use the descriptor tools.) + *
phase@phase <phaseName>NoBinds this Mojo to a particular phase of the standard build lifecycle, if specified. + *
+ * NOTE: This is only required if this Mojo is to participate in the standard build process. + *
execute@execute [phase=<phaseName>|goal=<goalName>] [lifecycle=<lifecycleId>]NoWhen this goal is invoked, it will first invoke a parallel lifecycle, ending at the given phase. + * If a goal is provided instead of a phase, that goal will be executed in isolation. + * The execution of either will not affect the current project, but instead make available the + * ${executedProject} expression if required. An alternate lifecycle can also be provided: + * for more information see the documentation on the + * build lifecycle. + *
requiresDependencyResolution@requiresDependencyResolution <requiredScope>NoFlags this Mojo as requiring the dependencies in the specified scope (or an implied scope) to be + * resolved before it can execute. + *
+ * NOTE: Currently supports compile, runtime, and test scopes. + *
descriptionnone (detected)NoThe description of this Mojo's functionality. Using the toolset, this will be the class-level + * Javadoc description provided. + *
+ * NOTE: While this is not a required part of the Mojo specification, it SHOULD be provided to + * enable future tool support for browsing, etc. and for clarity. + *
parametersN/ANoSpecifications for the parameters which this Mojo uses will be provided in parameter sub-elements + * in this section. + *
+ * NOTE: Parameters are discussed in more detail below. + *
+ * + * @see Guide to Developing Java Plugins + * @see Guide to Configuring Plug-ins + * @see Mojo API Specification + * + * @author Brett Porter + * @author jdcasey + * @author Vincent Siveton * @version $Id$ */ public abstract class AbstractMojo implements Mojo, ContextEnabled { + /** Instance logger */ private Log log; + + /** Plugin container context */ private Map pluginContext; + /** + * @see org.apache.maven.plugin.Mojo#setLog(org.apache.maven.plugin.logging.Log) + */ public void setLog( Log log ) { this.log = log; } + /** + * By default, return a SystemStreamLog logger. + * + * @see org.apache.maven.plugin.Mojo#getLog() + */ public Log getLog() { if ( log == null ) @@ -45,14 +170,19 @@ public abstract class AbstractMojo return log; } + /** + * @see org.apache.maven.plugin.ContextEnabled#getPluginContext() + */ public Map getPluginContext() { return pluginContext; } + /** + * @see org.apache.maven.plugin.ContextEnabled#setPluginContext(java.util.Map) + */ public void setPluginContext( Map pluginContext ) { this.pluginContext = pluginContext; } - } diff --git a/maven-plugin-api/src/main/java/org/apache/maven/plugin/ContextEnabled.java b/maven-plugin-api/src/main/java/org/apache/maven/plugin/ContextEnabled.java index ec0f51027b..dccd7e6777 100644 --- a/maven-plugin-api/src/main/java/org/apache/maven/plugin/ContextEnabled.java +++ b/maven-plugin-api/src/main/java/org/apache/maven/plugin/ContextEnabled.java @@ -1,12 +1,43 @@ package org.apache.maven.plugin; +/* + * Copyright 2005-2006 The Apache Software Foundation. + * + * Licensed 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. + */ + import java.util.Map; +/** + * Interface to allow Mojos to communicate with each others Mojos, other than + * project's source root and project's attachment. + *
+ * The plugin manager would pull the context out of the plugin container context, and populate it into the Mojo. + * + * @author jdcasey + * @version $Id$ + */ public interface ContextEnabled { - + /** + * Set a new shared context Map to a mojo before executing it. + * + * @param pluginContext a new Map + */ void setPluginContext( Map pluginContext ); - - Map getPluginContext(); + /** + * @return a Map stored in the plugin container's context. + */ + Map getPluginContext(); } diff --git a/maven-plugin-api/src/main/java/org/apache/maven/plugin/Mojo.java b/maven-plugin-api/src/main/java/org/apache/maven/plugin/Mojo.java index 0ddd0aee40..501135f2db 100755 --- a/maven-plugin-api/src/main/java/org/apache/maven/plugin/Mojo.java +++ b/maven-plugin-api/src/main/java/org/apache/maven/plugin/Mojo.java @@ -1,7 +1,7 @@ package org.apache.maven.plugin; /* - * Copyright 2001-2004 The Apache Software Foundation. + * Copyright 2005-2006 The Apache Software Foundation. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -19,18 +19,52 @@ package org.apache.maven.plugin; import org.apache.maven.plugin.logging.Log; /** + * This interface forms the contract required for Mojos to interact with the Maven + * infrastructure. + *
+ * It features an execute() method, which triggers the Mojo's build-process behavior, and can throw + * a MojoExecutionException or MojoFailureException if error conditions occur. + *
+ * Also included is the setLog(...) method, which simply allows Maven to inject a logging mechanism which will + * allow the Mojo to communicate to the outside world through standard Maven channels. + * * @author Jason van Zyl * @version $Id$ */ public interface Mojo { + /** The component role hint for Plexus container */ String ROLE = Mojo.class.getName(); + /** + * Perform whatever build-process behavior this Mojo implements. + *
+ * This is the main trigger for the Mojo inside the Maven system, and allows + * the Mojo to communicate errors. + * + * @throws MojoExecutionException if an unexpected problem occurs. + * Throwing this exception causes a "BUILD ERROR" message to be displayed. + * @throws MojoFailureException if an expected problem (such as a compilation failure) occurs. + * Throwing this exception causes a "BUILD FAILURE" message to be displayed. + */ void execute() throws MojoExecutionException, MojoFailureException; + /** + * Inject a standard Maven logging mechanism to allow this Mojo to communicate events + * and feedback to the user. + * + * @param log a new logger + */ // TODO: not sure about this here, and may want a getLog on here as well/instead void setLog( Log log ); + /** + * Furnish access to the standard Maven logging mechanism which is managed in this base class. + * + * @return 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. + */ Log getLog(); } diff --git a/maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoExecutionException.java b/maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoExecutionException.java index c29f97fdce..9a6ce25fe0 100755 --- a/maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoExecutionException.java +++ b/maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoExecutionException.java @@ -1,14 +1,14 @@ package org.apache.maven.plugin; /* - * Copyright 2001-2005 The Apache Software Foundation. - * + * Copyright 2005-2006 The Apache Software Foundation. + * * Licensed 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. @@ -18,6 +18,8 @@ package org.apache.maven.plugin; /** * An exception occuring during the execution of a plugin. + *
+ * Throwing this exception causes a "BUILD ERROR" message to be displayed. * * @author Brett Porter * @version $Id$ @@ -25,6 +27,13 @@ package org.apache.maven.plugin; public class MojoExecutionException extends AbstractMojoExecutionException { + /** + * Construct a new MojoExecutionException exception providing the source and a short and long message. + * + * @param source + * @param shortMessage + * @param longMessage + */ public MojoExecutionException( Object source, String shortMessage, String longMessage ) { super( shortMessage ); @@ -32,19 +41,37 @@ public class MojoExecutionException this.longMessage = longMessage; } + /** + * Construct a new MojoExecutionException exception wrapping an underlying Exception + * and providing a message. + * + * @param message + * @param cause + */ public MojoExecutionException( String message, Exception cause ) { super( message, cause ); } + /** + * Construct a new MojoExecutionException exception wrapping an underlying Throwable + * and providing a message. + * + * @param message + * @param cause + */ public MojoExecutionException( String message, Throwable cause ) { super( message, cause ); } + /** + * Construct a new MojoExecutionException exception providing a message. + * + * @param message + */ public MojoExecutionException( String message ) { super( message ); } - } diff --git a/maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoFailureException.java b/maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoFailureException.java index b32549fbef..ec9c8dd2be 100644 --- a/maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoFailureException.java +++ b/maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoFailureException.java @@ -17,7 +17,9 @@ package org.apache.maven.plugin; */ /** - * An exception occuring during the execution of a plugin. + * An exception occuring during the execution of a plugin (such as a compilation failure). + *
+ * Throwing this exception causes a "BUILD FAILURE" message to be displayed. * * @author Brett Porter * @version $Id$ @@ -25,6 +27,13 @@ package org.apache.maven.plugin; public class MojoFailureException extends AbstractMojoExecutionException { + /** + * Construct a new MojoFailureException exception providing the source and a short and long message. + * + * @param source + * @param shortMessage + * @param longMessage + */ public MojoFailureException( Object source, String shortMessage, String longMessage ) { super( shortMessage ); @@ -32,9 +41,13 @@ public class MojoFailureException this.longMessage = longMessage; } + /** + * Construct a new MojoFailureException exception providing a message. + * + * @param message + */ public MojoFailureException( String message ) { super( message ); } - } diff --git a/maven-plugin-api/src/main/java/org/apache/maven/plugin/logging/Log.java b/maven-plugin-api/src/main/java/org/apache/maven/plugin/logging/Log.java index f8a56dff46..2c7c796fc9 100644 --- a/maven-plugin-api/src/main/java/org/apache/maven/plugin/logging/Log.java +++ b/maven-plugin-api/src/main/java/org/apache/maven/plugin/logging/Log.java @@ -1,7 +1,7 @@ package org.apache.maven.plugin.logging; /* - * Copyright 2001-2005 The Apache Software Foundation. + * Copyright 2005-2006 The Apache Software Foundation. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -17,39 +17,140 @@ package org.apache.maven.plugin.logging; */ /** + * This interface supplies the API for providing feedback to the user from the Mojo, using standard + * Maven channels. + *
+ * There should be no big surprises here, although you may notice that the methods accept + * java.lang.CharSequence rather than java.lang.String. This is provided mainly as a + * convenience, to enable developers to pass things like java.lang.StringBuffer directly into the logger, + * rather than formatting first by calling toString(). + * * @author jdcasey + * @version $Id$ */ public interface Log { + /** + * @return true if the debug error level is enabled + */ boolean isDebugEnabled(); - + + /** + * Send a message to the user in the debug error level. + * + * @param content + */ void debug( CharSequence content ); + /** + * Send a message (and accompanying exception) to the user in the debug error level. + *
+ * The error's stacktrace will be output when this error level is enabled. + * + * @param content + * @param error + */ void debug( CharSequence content, Throwable error ); + /** + * Send an exception to the user in the debug error level. + *
+ * The stack trace for this exception will be output when this error level is enabled. + * + * @param error + */ void debug( Throwable error ); + /** + * @return true if the info error level is enabled + */ boolean isInfoEnabled(); - + + /** + * Send a message to the user in the info error level. + * + * @param content + */ void info( CharSequence content ); + /** + * Send a message (and accompanying exception) to the user in the info error level. + *
+ * The error's stacktrace will be output when this error level is enabled. + * + * @param content + * @param error + */ void info( CharSequence content, Throwable error ); + /** + * Send an exception to the user in the info error level. + *
+ * The stack trace for this exception will be output when this error level is enabled. + * + * @param error + */ void info( Throwable error ); + /** + * @return true if the warn error level is enabled + */ boolean isWarnEnabled(); - + + /** + * Send a message to the user in the warn error level. + * + * @param content + */ void warn( CharSequence content ); + /** + * Send a message (and accompanying exception) to the user in the warn error level. + *
+ * The error's stacktrace will be output when this error level is enabled. + * + * @param content + * @param error + */ void warn( CharSequence content, Throwable error ); + /** + * Send an exception to the user in the warn error level. + *
+ * The stack trace for this exception will be output when this error level is enabled. + * + * @param error + */ void warn( Throwable error ); + /** + * @return true if the error error level is enabled + */ boolean isErrorEnabled(); - + + /** + * Send a message to the user in the error error level. + * + * @param content + */ void error( CharSequence content ); + /** + * Send a message (and accompanying exception) to the user in the error error level. + *
+ * The error's stacktrace will be output when this error level is enabled. + * + * @param content + * @param error + */ void error( CharSequence content, Throwable error ); + /** + * Send an exception to the user in the error error level. + *
+ * The stack trace for this exception will be output when this error level is enabled. + * + * @param error + */ void error( Throwable error ); } \ No newline at end of file diff --git a/maven-plugin-api/src/main/java/org/apache/maven/plugin/logging/SystemStreamLog.java b/maven-plugin-api/src/main/java/org/apache/maven/plugin/logging/SystemStreamLog.java index f91155c0a3..6198c5ef8f 100644 --- a/maven-plugin-api/src/main/java/org/apache/maven/plugin/logging/SystemStreamLog.java +++ b/maven-plugin-api/src/main/java/org/apache/maven/plugin/logging/SystemStreamLog.java @@ -1,7 +1,7 @@ package org.apache.maven.plugin.logging; /* - * Copyright 2001-2005 The Apache Software Foundation. + * Copyright 2005-2006 The Apache Software Foundation. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -20,62 +20,97 @@ import java.io.PrintWriter; import java.io.StringWriter; /** + * Logger with "standard" output and error output stream. + * * @author jdcasey + * @version $Id$ */ public class SystemStreamLog implements Log { - + /** + * @see org.apache.maven.plugin.logging.Log#debug(java.lang.CharSequence) + */ public void debug( CharSequence content ) { print( "debug", content ); } + /** + * @see org.apache.maven.plugin.logging.Log#debug(java.lang.CharSequence, java.lang.Throwable) + */ public void debug( CharSequence content, Throwable error ) { print( "debug", content, error ); } + /** + * @see org.apache.maven.plugin.logging.Log#debug(java.lang.Throwable) + */ public void debug( Throwable error ) { print( "debug", error ); } + /** + * @see org.apache.maven.plugin.logging.Log#info(java.lang.CharSequence) + */ public void info( CharSequence content ) { print( "info", content ); } + /** + * @see org.apache.maven.plugin.logging.Log#info(java.lang.CharSequence, java.lang.Throwable) + */ public void info( CharSequence content, Throwable error ) { print( "info", content, error ); } + /** + * @see org.apache.maven.plugin.logging.Log#info(java.lang.Throwable) + */ public void info( Throwable error ) { print( "info", error ); } + /** + * @see org.apache.maven.plugin.logging.Log#warn(java.lang.CharSequence) + */ public void warn( CharSequence content ) { print( "warn", content ); } + /** + * @see org.apache.maven.plugin.logging.Log#warn(java.lang.CharSequence, java.lang.Throwable) + */ public void warn( CharSequence content, Throwable error ) { print( "warn", content, error ); } + /** + * @see org.apache.maven.plugin.logging.Log#warn(java.lang.Throwable) + */ public void warn( Throwable error ) { print( "warn", error ); } + /** + * @see org.apache.maven.plugin.logging.Log#error(java.lang.CharSequence) + */ public void error( CharSequence content ) { System.err.println( "[error] " + content.toString() ); } + /** + * @see org.apache.maven.plugin.logging.Log#error(java.lang.CharSequence, java.lang.Throwable) + */ public void error( CharSequence content, Throwable error ) { StringWriter sWriter = new StringWriter(); @@ -86,6 +121,9 @@ public class SystemStreamLog System.err.println( "[error] " + content.toString() + "\n\n" + sWriter.toString() ); } + /** + * @see org.apache.maven.plugin.logging.Log#error(java.lang.Throwable) + */ public void error( Throwable error ) { StringWriter sWriter = new StringWriter(); @@ -96,6 +134,39 @@ public class SystemStreamLog System.err.println( "[error] " + sWriter.toString() ); } + /** + * @see org.apache.maven.plugin.logging.Log#isDebugEnabled() + */ + public boolean isDebugEnabled() + { + // TODO: Not sure how best to set these for this implementation... + return false; + } + + /** + * @see org.apache.maven.plugin.logging.Log#isInfoEnabled() + */ + public boolean isInfoEnabled() + { + return true; + } + + /** + * @see org.apache.maven.plugin.logging.Log#isWarnEnabled() + */ + public boolean isWarnEnabled() + { + return true; + } + + /** + * @see org.apache.maven.plugin.logging.Log#isErrorEnabled() + */ + public boolean isErrorEnabled() + { + return true; + } + private void print( String prefix, CharSequence content ) { System.out.println( "[" + prefix + "] " + content.toString() ); @@ -120,26 +191,4 @@ public class SystemStreamLog System.out.println( "[" + prefix + "] " + content.toString() + "\n\n" + sWriter.toString() ); } - - public boolean isDebugEnabled() - { - // TODO: Not sure how best to set these for this implementation... - return false; - } - - public boolean isInfoEnabled() - { - return true; - } - - public boolean isWarnEnabled() - { - return true; - } - - public boolean isErrorEnabled() - { - return true; - } - } \ No newline at end of file