Apache
/
maven
mirror of https://github.com/apache/maven.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
Vincent Siveton 2006-10-21 15:06:42 +00:00
parent c14a969d3f
commit 64aef4d099
7 changed files with 427 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
maven-plugin-api/src/main/java/org/apache/maven/plugin/AbstractMojo.java
View File

@ -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 java.util.Map;
/**
* Abstract class to provide most of the infrastructure required to implement a <code>Mojo</code> except for
* the execute method.
* <br/>
* The implementation should have a <code>goal</code> annotation in the class-level javadoc annotation:
* <pre>
* &#47;&#42;&#42;
* &#42; &#64;goal goalName
* &#42;&#47;
* </pre>
*
* There are also a number of class-level javadoc annotations which can be used to control how and when the
* <code>Mojo</code> is executed:
* <br/>
* <br/>
*
* <table border="1">
* <tr bgcolor="#CCCCCC">
* <th>Descriptor Element</th>
* <th>Annotation</th>
* <th>Required?</th>
* <th>Notes</th>
* </tr>
* <tr>
* <td>goal</td>
* <td>@goal &lt;goalName&gt;</td>
* <td>Yes</td>
* <td>The 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.</td>
* </tr>
* <tr>
* <td>implementation</td>
* <td>none (detected)</td>
* <td>Yes</td>
* <td>The Mojo's fully-qualified class name (or script path in the case of non-Java Mojos).</td>
* </tr>
* <tr>
* <td>language</td>
* <td>none (detected)</td>
* <td>No. Default: <code>java</code></td>
* <td>The implementation language for this Mojo (Java, beanshell, etc.).</td>
* </tr>
* <tr>
* <td>configurator</td>
* <td>@configurator &lt;roleHint&gt;</td>
* <td>No</td>
* <td>The 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.
* <br/>
* <i>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.)</i>
* </td>
* </tr>
* <tr>
* <td>phase</td>
* <td>@phase &lt;phaseName&gt;</td>
* <td>No</td>
* <td>Binds this Mojo to a particular phase of the standard build lifecycle, if specified.
* <br/>
* <i>NOTE: This is only required if this Mojo is to participate in the standard build process.</i>
* </td>
* </tr>
* <tr>
* <td>execute</td>
* <td>@execute [phase=&lt;phaseName&gt;|goal=&lt;goalName&gt;] [lifecycle=&lt;lifecycleId&gt;]</td>
* <td>No</td>
* <td>When 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
* <code>${executedProject}</code> expression if required. An alternate lifecycle can also be provided:
* for more information see the documentation on the
* <a href="http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html" target="_blank">build lifecycle</a>.
* </td>
* </tr>
* <tr>
* <td>requiresDependencyResolution</td>
* <td>@requiresDependencyResolution &lt;requiredScope&gt;</td>
* <td>No</td>
* <td>Flags this Mojo as requiring the dependencies in the specified scope (or an implied scope) to be
* resolved before it can execute.
* <br/>
* <i>NOTE: Currently supports <b>compile</b>, <b>runtime</b>, and <b>test</b> scopes.</i>
* </td>
* </tr>
* <tr>
* <td>description</td>
* <td>none (detected)</td>
* <td>No</td>
* <td>The description of this Mojo's functionality. <i>Using the toolset, this will be the class-level
* Javadoc description provided.
* <br/>
* <i>NOTE: While this is not a required part of the Mojo specification, it <b>SHOULD</b> be provided to
* enable future tool support for browsing, etc. and for clarity.</i>
* </td>
* </tr>
* <tr>
* <td>parameters</td>
* <td>N/A</td>
* <td>No</td>
* <td>Specifications for the parameters which this Mojo uses will be provided in <b>parameter</b> sub-elements
* in this section.
* <br/>
* <i>NOTE: Parameters are discussed in more detail below.</i>
* </td>
* </tr>
* </table>
*
* @see <a href="http://maven.apache.org/guides/plugin/guide-java-plugin-development.html" target="_blank">Guide to Developing Java Plugins</a>
* @see <a href="http://maven.apache.org/guides/mini/guide-configuring-plugins.html" target="_blank">Guide to Configuring Plug-ins</a>
* @see <a href="http://maven.apache.org/developers/mojo-api-specification.html" target="_blank">Mojo API Specification</a>
*
* @author <a href="mailto:brett@apache.org">Brett Porter</a>
* @author jdcasey
* @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
* @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 <code>SystemStreamLog</code> logger.
*
* @see org.apache.maven.plugin.Mojo#getLog()
*/
public Log getLog()
{
if ( log == null )
@ -45,14 +170,19 @@ public Log getLog()
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;
}
}

35
maven-plugin-api/src/main/java/org/apache/maven/plugin/ContextEnabled.java
View File

@ -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 <code>Mojos</code> to communicate with each others <code>Mojos</code>, other than
* project's source root and project's attachment.
* <br/>
* 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 <code>Map</code> to a mojo before executing it.
*
* @param pluginContext a new <code>Map</code>
*/
void setPluginContext( Map pluginContext );
/**
* @return a <code>Map</code> stored in the plugin container's context.
*/
Map getPluginContext();
}

36
maven-plugin-api/src/main/java/org/apache/maven/plugin/Mojo.java
View File

@ -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 @@
import org.apache.maven.plugin.logging.Log;
/**
* This interface forms the contract required for <code>Mojos</code> to interact with the <code>Maven</code>
* infrastructure.
* <br/>
* It features an <code>execute()</code> method, which triggers the Mojo's build-process behavior, and can throw
* a MojoExecutionException or MojoFailureException if error conditions occur.
* <br/>
* Also included is the <code>setLog(...)</code> 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 <a href="mailto:jason@maven.org">Jason van Zyl</a>
* @version $Id$
*/
public interface Mojo
{
/** The component <code>role</code> hint for Plexus container */
String ROLE = Mojo.class.getName();
/**
* Perform whatever build-process behavior this <code>Mojo</code> implements.
* <br/>
* This is the main trigger for the <code>Mojo</code> inside the <code>Maven</code> system, and allows
* the <code>Mojo</code> 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 <code>Maven</code> logging mechanism to allow this <code>Mojo</code> 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 <code>"debug"</code>,
* <code>"info"</code>, <code>"warn"</code>, and <code>"error"</code>. This logger is the accepted means to display
* information to the user.
*/
Log getLog();
}

31
maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoExecutionException.java
View File

@ -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.
@ -18,6 +18,8 @@
/**
* An exception occuring during the execution of a plugin.
* <br/>
* Throwing this exception causes a "BUILD ERROR" message to be displayed.
*
* @author Brett Porter
* @version $Id$
@ -25,6 +27,13 @@
public class MojoExecutionException
extends AbstractMojoExecutionException
{
/**
* Construct a new <code>MojoExecutionException</code> 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 MojoExecutionException( Object source, String shortMessage, String longMe
this.longMessage = longMessage;
}
/**
* Construct a new <code>MojoExecutionException</code> exception wrapping an underlying <code>Exception</code>
* and providing a <code>message</code>.
*
* @param message
* @param cause
*/
public MojoExecutionException( String message, Exception cause )
{
super( message, cause );
}
/**
* Construct a new <code>MojoExecutionException</code> exception wrapping an underlying <code>Throwable</code>
* and providing a <code>message</code>.
*
* @param message
* @param cause
*/
public MojoExecutionException( String message, Throwable cause )
{
super( message, cause );
}
/**
* Construct a new <code>MojoExecutionException</code> exception providing a <code>message</code>.
*
* @param message
*/
public MojoExecutionException( String message )
{
super( message );
}
}

17
maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoFailureException.java
View File

@ -17,7 +17,9 @@
*/
/**
* An exception occuring during the execution of a plugin.
* An exception occuring during the execution of a plugin (such as a compilation failure).
* <br/>
* Throwing this exception causes a "BUILD FAILURE" message to be displayed.
*
* @author Brett Porter
* @version $Id$
@ -25,6 +27,13 @@
public class MojoFailureException
extends AbstractMojoExecutionException
{
/**
* Construct a new <code>MojoFailureException</code> 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 MojoFailureException( Object source, String shortMessage, String longMess
this.longMessage = longMessage;
}
/**
* Construct a new <code>MojoFailureException</code> exception providing a message.
*
* @param message
*/
public MojoFailureException( String message )
{
super( message );
}
}

103
maven-plugin-api/src/main/java/org/apache/maven/plugin/logging/Log.java
View File

@ -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 @@
*/
/**
* This interface supplies the API for providing feedback to the user from the <code>Mojo</code>, using standard
* <code>Maven</code> channels.
* <br/>
* There should be no big surprises here, although you may notice that the methods accept
* <code>java.lang.CharSequence</code> rather than <code>java.lang.String</code>. This is provided mainly as a
* convenience, to enable developers to pass things like <code>java.lang.StringBuffer</code> directly into the logger,
* rather than formatting first by calling <code>toString()</code>.
*
* @author jdcasey
* @version $Id$
*/
public interface Log
{
/**
* @return true if the <b>debug</b> error level is enabled
*/
boolean isDebugEnabled();
/**
* Send a message to the user in the <b>debug</b> error level.
*
* @param content
*/
void debug( CharSequence content );
/**
* Send a message (and accompanying exception) to the user in the <b>debug</b> error level.
* <br/>
* 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 <b>debug</b> error level.
* <br/>
* 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 <b>info</b> error level is enabled
*/
boolean isInfoEnabled();
/**
* Send a message to the user in the <b>info</b> error level.
*
* @param content
*/
void info( CharSequence content );
/**
* Send a message (and accompanying exception) to the user in the <b>info</b> error level.
* <br/>
* 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 <b>info</b> error level.
* <br/>
* 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 <b>warn</b> error level is enabled
*/
boolean isWarnEnabled();
/**
* Send a message to the user in the <b>warn</b> error level.
*
* @param content
*/
void warn( CharSequence content );
/**
* Send a message (and accompanying exception) to the user in the <b>warn</b> error level.
* <br/>
* 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 <b>warn</b> error level.
* <br/>
* 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 <b>error</b> error level is enabled
*/
boolean isErrorEnabled();
/**
* Send a message to the user in the <b>error</b> error level.
*
* @param content
*/
void error( CharSequence content );
/**
* Send a message (and accompanying exception) to the user in the <b>error</b> error level.
* <br/>
* 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 <b>error</b> error level.
* <br/>
* The stack trace for this exception will be output when this error level is enabled.
*
* @param error
*/
void error( Throwable error );
}

97
maven-plugin-api/src/main/java/org/apache/maven/plugin/logging/SystemStreamLog.java
View File

@ -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.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 void error( CharSequence content, Throwable error )
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 void error( Throwable error )
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 @@ private void print( String prefix, CharSequence content, Throwable error )
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;
}
}