You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by lt...@apache.org on 2008/02/07 15:39:56 UTC
svn commit: r619428 -
/maven/site/trunk/src/site/xdoc/developers/mojo-api-specification.xml
Author: ltheussl
Date: Thu Feb 7 06:39:53 2008
New Revision: 619428
URL: http://svn.apache.org/viewvc?rev=619428&view=rev
Log:
Fix invalid xhtml output
Modified:
maven/site/trunk/src/site/xdoc/developers/mojo-api-specification.xml
Modified: maven/site/trunk/src/site/xdoc/developers/mojo-api-specification.xml
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/xdoc/developers/mojo-api-specification.xml?rev=619428&r1=619427&r2=619428&view=diff
==============================================================================
--- maven/site/trunk/src/site/xdoc/developers/mojo-api-specification.xml (original)
+++ maven/site/trunk/src/site/xdoc/developers/mojo-api-specification.xml Thu Feb 7 06:39:53 2008
@@ -102,46 +102,38 @@
logging mechanism which will allow the Mojo to communicate to the
outside world through standard Maven channels.
</p>
- <p>
- <ul>
- <lt>
- <b>Method Summary:</b>
- </lt>
- <li>
- <code>
- void setLog( org.apache.maven.monitor.logging.Log )
- </code>
- <p>Inject a standard Maven logging mechanism to allow this Mojo
- to communicate events and feedback to the user.</p>
- </li>
- <li>
- <code>
- void execute() throws org.apache.maven.plugin.MojoExecutionException
- </code>
- <p>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 fatal errors by throwing an
- instance of
- <code>MojoExecutionException</code>
- .
- </p>
- <p>The
- <code>MojoExecutionException</code>
- (and all error
- conditions inside the Mojo) should be handled very carefully.
- The simple wrapping of lower-level exceptions without providing
- any indication of a user-friendly probable cause is strictly
- discouraged. In fact, a much better course of action is to
- provide error handling code (try/catch stanzas) for each
- coherent step within the Mojo's execution. Developers are then
- in a much better position to diagnose the cause of any error,
- and provide user-friendly feedback in the message of the
- <code>MojoExecutionException</code>
- .
- </p>
- </li>
- </ul>
- </p>
+ <h6>Method Summary:</h6>
+ <ul>
+ <li>
+ <code>
+ void setLog( org.apache.maven.monitor.logging.Log )
+ </code>
+ <p>Inject a standard Maven logging mechanism to allow this Mojo
+ to communicate events and feedback to the user.</p>
+ </li>
+ <li>
+ <code>
+ void execute() throws org.apache.maven.plugin.MojoExecutionException
+ </code>
+ <p>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 fatal errors by throwing an
+ instance of <code>MojoExecutionException</code>.
+ </p>
+ <p>The
+ <code>MojoExecutionException</code> (and all error
+ conditions inside the Mojo) should be handled very carefully.
+ The simple wrapping of lower-level exceptions without providing
+ any indication of a user-friendly probable cause is strictly
+ discouraged. In fact, a much better course of action is to
+ provide error handling code (try/catch stanzas) for each
+ coherent step within the Mojo's execution. Developers are then
+ in a much better position to diagnose the cause of any error,
+ and provide user-friendly feedback in the message of the
+ <code>MojoExecutionException</code>.
+ </p>
+ </li>
+ </ul>
</subsection>
<subsection name="org.apache.maven.plugin.AbstractMojo">
<p>Currently, this abstract base class simply takes care of managing
@@ -153,45 +145,41 @@
,
to furnish Log access to these concrete implementations.
</p>
- <p>
- <ul>
- <lt>
- <b>Method Summary:</b>
- </lt>
- <li>
- <code>
- public void setLog( org.apache.maven.monitor.logging.Log )
- </code>
- <p>
- <b>[IMPLEMENTED]</b>
- </p>
- <p>Inject a standard Maven logging mechanism to allow this Mojo
- to communicate events and feedback to the user.</p>
- </li>
- <li>
- <code>protected Log getLog()</code>
- <p>
- <b>[IMPLEMENTED]</b>
- </p>
- <p>Furnish access to the standard Maven logging mechanism which
- is managed in this base class.</p>
- </li>
- <li>
- <code>
- void execute() throws org.apache.maven.plugin.MojoExecutionException
- </code>
- <p>
- <b>[ABSTRACT]</b>
- </p>
- <p>Perform whatever build-process behavior this Mojo implements.
- See the documentation for
- <code>Mojo</code>
- above for more
- information.
- </p>
- </li>
- </ul>
- </p>
+ <h6>Method Summary:</h6>
+ <ul>
+ <li>
+ <code>
+ public void setLog( org.apache.maven.monitor.logging.Log )
+ </code>
+ <p>
+ <b>[IMPLEMENTED]</b>
+ </p>
+ <p>Inject a standard Maven logging mechanism to allow this Mojo
+ to communicate events and feedback to the user.</p>
+ </li>
+ <li>
+ <code>protected Log getLog()</code>
+ <p>
+ <b>[IMPLEMENTED]</b>
+ </p>
+ <p>Furnish access to the standard Maven logging mechanism which
+ is managed in this base class.</p>
+ </li>
+ <li>
+ <code>
+ void execute() throws org.apache.maven.plugin.MojoExecutionException
+ </code>
+ <p>
+ <b>[ABSTRACT]</b>
+ </p>
+ <p>Perform whatever build-process behavior this Mojo implements.
+ See the documentation for
+ <code>Mojo</code>
+ above for more
+ information.
+ </p>
+ </li>
+ </ul>
</subsection>
<subsection name="org.apache.maven.monitor.logging.Log">
<p>This interface supplies the API for providing feedback to the user
@@ -208,117 +196,113 @@
<code>toString()</code>
.
</p>
- <p>
- <ul>
- <lt>
- <b>Method Summary:</b>
- </lt>
- <li>
- <code>void debug( java.lang.CharSequence )</code>
- <p>Send a message to the user in the
- <b>debug</b>
- error level.
- </p>
- </li>
- <li>
- <code>
- void debug( java.lang.CharSequence, java.lang.Throwable )
- </code>
- <p>Send a message (and accompanying exception) to the user in the
- <b>debug</b>
- error level. The error's stacktrace will be output
- when this error level is enabled.
- </p>
- </li>
- <li>
- <code>void debug( java.lang.Throwable )</code>
- <p>Send an exception to the user in the
- <b>debug</b>
- error level.
- The stack trace for this exception will be output when this
- error level is enabled.
- </p>
- </li>
- <li>
- <code>void info( java.lang.CharSequence )</code>
- <p>Send a message to the user in the
- <b>info</b>
- error level.
- </p>
- </li>
- <li>
- <code>
- void info( java.lang.CharSequence, java.lang.Throwable )
- </code>
- <p>Send a message (and accompanying exception) to the user in the
- <b>info</b>
- error level. The error's stacktrace will be output
- when this error level is enabled.
- </p>
- </li>
- <li>
- <code>void info( java.lang.CharSequence )</code>
- <p>Send an exception to the user in the
- <b>info</b>
- error level.
- The stack trace for this exception will be output when this
- error level is enabled.
- </p>
- </li>
- <li>
- <code>void warn( java.lang.CharSequence )</code>
- <p>Send a message to the user in the
- <b>warn</b>
- error level.
- </p>
- </li>
- <li>
- <code>
- void warn( java.lang.CharSequence, java.lang.Throwable )
- </code>
- <p>Send a message (and accompanying exception) to the user in the
- <b>warn</b>
- error level. The error's stacktrace will be output
- when this error level is enabled.
- </p>
- </li>
- <li>
- <code>void warn( java.lang.CharSequence )</code>
- <p>Send an exception to the user in the
- <b>warn</b>
- error level.
- The stack trace for this exception will be output when this
- error level is enabled.
- </p>
- </li>
- <li>
- <code>void error( java.lang.CharSequence )</code>
- <p>Send a message to the user in the
- <b>error</b>
- error level.
- </p>
- </li>
- <li>
- <code>
- void error( java.lang.CharSequence, java.lang.Throwable )
- </code>
- <p>Send a message (and accompanying exception) to the user in the
- <b>error</b>
- error level. The error's stacktrace will be output
- when this error level is enabled.
- </p>
- </li>
- <li>
- <code>void error( java.lang.CharSequence )</code>
- <p>Send an exception to the user in the
- <b>error</b>
- error level.
- The stack trace for this exception will be output when this
- error level is enabled.
- </p>
- </li>
- </ul>
- </p>
+ <h6>Method Summary:</h6>
+ <ul>
+ <li>
+ <code>void debug( java.lang.CharSequence )</code>
+ <p>Send a message to the user in the
+ <b>debug</b>
+ error level.
+ </p>
+ </li>
+ <li>
+ <code>
+ void debug( java.lang.CharSequence, java.lang.Throwable )
+ </code>
+ <p>Send a message (and accompanying exception) to the user in the
+ <b>debug</b>
+ error level. The error's stacktrace will be output
+ when this error level is enabled.
+ </p>
+ </li>
+ <li>
+ <code>void debug( java.lang.Throwable )</code>
+ <p>Send an exception to the user in the
+ <b>debug</b>
+ error level.
+ The stack trace for this exception will be output when this
+ error level is enabled.
+ </p>
+ </li>
+ <li>
+ <code>void info( java.lang.CharSequence )</code>
+ <p>Send a message to the user in the
+ <b>info</b>
+ error level.
+ </p>
+ </li>
+ <li>
+ <code>
+ void info( java.lang.CharSequence, java.lang.Throwable )
+ </code>
+ <p>Send a message (and accompanying exception) to the user in the
+ <b>info</b>
+ error level. The error's stacktrace will be output
+ when this error level is enabled.
+ </p>
+ </li>
+ <li>
+ <code>void info( java.lang.CharSequence )</code>
+ <p>Send an exception to the user in the
+ <b>info</b>
+ error level.
+ The stack trace for this exception will be output when this
+ error level is enabled.
+ </p>
+ </li>
+ <li>
+ <code>void warn( java.lang.CharSequence )</code>
+ <p>Send a message to the user in the
+ <b>warn</b>
+ error level.
+ </p>
+ </li>
+ <li>
+ <code>
+ void warn( java.lang.CharSequence, java.lang.Throwable )
+ </code>
+ <p>Send a message (and accompanying exception) to the user in the
+ <b>warn</b>
+ error level. The error's stacktrace will be output
+ when this error level is enabled.
+ </p>
+ </li>
+ <li>
+ <code>void warn( java.lang.CharSequence )</code>
+ <p>Send an exception to the user in the
+ <b>warn</b>
+ error level.
+ The stack trace for this exception will be output when this
+ error level is enabled.
+ </p>
+ </li>
+ <li>
+ <code>void error( java.lang.CharSequence )</code>
+ <p>Send a message to the user in the
+ <b>error</b>
+ error level.
+ </p>
+ </li>
+ <li>
+ <code>
+ void error( java.lang.CharSequence, java.lang.Throwable )
+ </code>
+ <p>Send a message (and accompanying exception) to the user in the
+ <b>error</b>
+ error level. The error's stacktrace will be output
+ when this error level is enabled.
+ </p>
+ </li>
+ <li>
+ <code>void error( java.lang.CharSequence )</code>
+ <p>Send an exception to the user in the
+ <b>error</b>
+ error level.
+ The stack trace for this exception will be output when this
+ error level is enabled.
+ </p>
+ </li>
+ </ul>
</subsection>
</section>
<section name="The Descriptor and Annotations">
@@ -346,176 +330,172 @@
, and it must contain the
following:
</p>
- <p>
- <table>
- <tr>
- <th>Descriptor Element</th>
- <th>Required?</th>
- <th>Notes</th>
- </tr>
- <tr>
- <td>mojos</td>
- <td>Yes</td>
- <td>Descriptors for each Mojo provided by the plugin, each inside a
- <b>mojo</b>
- sub-element. Mojo descriptors are covered in detail
- below. Obviously, a plugin without any declared Mojos doesn't
- make sense, so the
- <b>mojos</b>
- element is required, along with
- at least one
- <b>mojo</b>
- sub-element.
- </td>
- </tr>
- <tr>
- <td>dependencies</td>
- <td>Yes</td>
- <td>A set of dependencies which the plugin requires in order to
- function. Each dependency is provided inside a
- <b>dependency</b>
- sub-element. Dependency specifications are covered below. Since
- all plugins must have a dependency on
- <code>maven-plugin-api</code>
- , this element is effectively
- required.
- <i>Using the plugin toolset, these dependencies can be
- extracted from the POM's dependencies.</i>
- </td>
- </tr>
- </table>
- </p>
+ <table>
+ <tr>
+ <th>Descriptor Element</th>
+ <th>Required?</th>
+ <th>Notes</th>
+ </tr>
+ <tr>
+ <td>mojos</td>
+ <td>Yes</td>
+ <td>Descriptors for each Mojo provided by the plugin, each inside a
+ <b>mojo</b>
+ sub-element. Mojo descriptors are covered in detail
+ below. Obviously, a plugin without any declared Mojos doesn't
+ make sense, so the
+ <b>mojos</b>
+ element is required, along with
+ at least one
+ <b>mojo</b>
+ sub-element.
+ </td>
+ </tr>
+ <tr>
+ <td>dependencies</td>
+ <td>Yes</td>
+ <td>A set of dependencies which the plugin requires in order to
+ function. Each dependency is provided inside a
+ <b>dependency</b>
+ sub-element. Dependency specifications are covered below. Since
+ all plugins must have a dependency on
+ <code>maven-plugin-api</code>
+ , this element is effectively
+ required.
+ <i>Using the plugin toolset, these dependencies can be
+ extracted from the POM's dependencies.</i>
+ </td>
+ </tr>
+ </table>
<p>Each Mojo specified inside a plugin descriptor must provide the
following (annotations specified here are at the class level):</p>
- <p>
- <table>
- <tr>
- <th>Descriptor Element</th>
- <th>Annotation</th>
- <th>Required?</th>
- <th>Notes</th>
- </tr>
- <tr>
- <td>goal</td>
- <td>@goal <goalName></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 <roleHint></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.
- <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 <phaseName></td>
- <td>No</td>
- <td>Binds this Mojo to a particular phase of the standard build
- lifecycle, if specified.
- <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><ul>
- <li>@execute phase="<phaseName>" lifecycle="<lifecycleId>"</li>
- <li>@execute phase="<phaseName>"</li>
- <li>@execute goal="<goalName>"</li>
- </ul>
- </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="../guides/introduction/introduction-to-the-lifecycle.html">build lifecycle</a>
- .
- </td>
- </tr>
- <tr>
- <td>requiresDependencyResolution</td>
- <td>@requiresDependencyResolution <requiredScope></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.
- <i>NOTE: Currently supports
- <b>compile</b>
- ,
- <b>runtime</b>
- , and
- <b>test</b>
- scopes.
- </i>
- </td>
- </tr>
- <tr>
- <td>requiresProject</td>
- <td>@requiresProject</td>
- <td>No. Default: true</td>
- <td>Flags this Mojo to run inside of a project.</td>
- </tr>
- <tr>
- <td>aggregator</td>
- <td>@aggregator</td>
- <td>No</td>
- <td>Flags this Mojo to run it in a multi module way, i.e. aggregate the build with the
- set of projects listed as modules.</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. 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.</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.
- <i>NOTE: Parameters are discussed in more detail below.</i>
- </td>
- </tr>
- </table>
- </p>
+ <table>
+ <tr>
+ <th>Descriptor Element</th>
+ <th>Annotation</th>
+ <th>Required?</th>
+ <th>Notes</th>
+ </tr>
+ <tr>
+ <td>goal</td>
+ <td>@goal <goalName></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 <roleHint></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.
+ <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 <phaseName></td>
+ <td>No</td>
+ <td>Binds this Mojo to a particular phase of the standard build
+ lifecycle, if specified.
+ <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><ul>
+ <li>@execute phase="<phaseName>" lifecycle="<lifecycleId>"</li>
+ <li>@execute phase="<phaseName>"</li>
+ <li>@execute goal="<goalName>"</li>
+ </ul>
+ </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="../guides/introduction/introduction-to-the-lifecycle.html">build lifecycle</a>
+ .
+ </td>
+ </tr>
+ <tr>
+ <td>requiresDependencyResolution</td>
+ <td>@requiresDependencyResolution <requiredScope></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.
+ <i>NOTE: Currently supports
+ <b>compile</b>
+ ,
+ <b>runtime</b>
+ , and
+ <b>test</b>
+ scopes.
+ </i>
+ </td>
+ </tr>
+ <tr>
+ <td>requiresProject</td>
+ <td>@requiresProject</td>
+ <td>No. Default: true</td>
+ <td>Flags this Mojo to run inside of a project.</td>
+ </tr>
+ <tr>
+ <td>aggregator</td>
+ <td>@aggregator</td>
+ <td>No</td>
+ <td>Flags this Mojo to run it in a multi module way, i.e. aggregate the build with the
+ set of projects listed as modules.</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. 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.</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.
+ <i>NOTE: Parameters are discussed in more detail below.</i>
+ </td>
+ </tr>
+ </table>
<p>Each Mojo specifies the parameters that it expects in order to work.
These parameters are the Mojo's link to the outside world, and
will be satisfied through a combination of POM/project values, plugin
@@ -533,132 +513,130 @@
</p>
<p>Each parameter for a Mojo must be specified in the
plugin descriptor as follows:</p>
- <p>
- <table>
- <tr>
- <th>Descriptor Element</th>
- <th>Annotation</th>
- <th>Required?</th>
- <th>Notes</th>
- </tr>
- <tr>
- <td>name</td>
- <td>none (detected)</td>
- <td>Yes</td>
- <td>The name of the parameter, to be used in configuring this
- parameter from the Mojo's declared defaults (discussed below) or
- from the POM.
- <i>Using the toolset, this is detected as the
- Java field name.</i>
- </td>
- </tr>
- <tr>
- <td>alias</td>
- <td>@parameter alias="myAlias"</td>
- <td>No</td>
- <td>Specifies an alias which can be used to configure this
- parameter from the POM. This is primarily useful to improve
- user-friendliness, where Mojo field names are not intuitive to
- the user or are otherwise not conducive to configuration via
- the POM.</td>
- </tr>
- <tr>
- <td>type</td>
- <td>none (detected)</td>
- <td>Yes</td>
- <td>The Java type for this parameter. This is used to validate the
- result of any expressions used to calculate the value which
- should be injected into the Mojo for this parameter.
- <i>Using the
- toolset, this is detected as the class of the Java field
- corresponding to this parameter.</i>
- </td>
- </tr>
- <tr>
- <td>required</td>
- <td>@required</td>
- <td>No</td>
- <td>Whether this parameter is required for the Mojo to function.
- This is used to validate the configuration for a Mojo before it
- is injected, and before the Mojo is executed from some
- half-state.
- <i>NOTE: Specification of this annotation flags
- the parameter as required; there is no true/false value.</i>
- </td>
- </tr>
- <tr>
- <td>editable</td>
- <td>@readonly</td>
- <td>No</td>
- <td>Specifies that this parameter cannot be configured directly by
- the user (as in the case of POM-specified configuration). This is
- useful when you want to force the user to use common POM elements
- rather than plugin configurations, as in the case where you want
- to use the artifact's final name as a parameter. In this case,
- you want the user to modify
- <build><finalName/></build> rather than
- specifying a value for finalName directly in the plugin
- configuration section. It is also useful to ensure that - for
- example - a List-typed parameter which expects items of type
- Artifact doesn't get a List full of Strings.
- <i>NOTE:
- Specification of this annotation flags the parameter as
- non-editable; there is no true/false value.</i>
- </td>
- </tr>
- <tr>
- <td>description</td>
- <td>none (detected)</td>
- <td>No</td>
- <td>The description of this parameter's use inside the Mojo.
- <i>Using the toolset, this is detected as the Javadoc description
- for the field. NOTE: While this is not a required part of the
- parameter specification, it SHOULD be provided to enable future
- tool support for browsing, etc. and for clarity.</i>
- </td>
- </tr>
- <tr>
- <td>configuration</td>
- <td>@parameter expression="${someExpression}" default-value="value"</td>
- <td>No</td>
- <td>Specifies the expression used to calculate the value to be
- injected into this parameter of the Mojo at buildtime. This is
- commonly used to refer to specific elements in the POM, such as
- ${project.build.resources}, which refers to the List of resources
- meant to accompany the classes in the resulting jar file.
- The default value is used when the expression evaluates to
- <code>null</code>
- .
- <i>NOTE: If not specified, an expression of ${<name>} is
- assumed, which can only be satisfied from POM configuration or
- System properties. The use of '${' and '}' is required to delimit
- actual expressions which may be evaluated.</i>
- </td>
- </tr>
- <tr>
- <td>configuration</td>
- <td>@component</td>
- <td>No</td>
- <td>
- Populates the field with an instance of a Plexus component. This is like declaring a <i>requirement</i> in a Plexus component.
- The default requirement will have a role equal to the declared type of the field, and will use the default role hint. You can customise either of these by providing a <code>role</code> and/or <code>roleHint</code> parameter.
+ <table>
+ <tr>
+ <th>Descriptor Element</th>
+ <th>Annotation</th>
+ <th>Required?</th>
+ <th>Notes</th>
+ </tr>
+ <tr>
+ <td>name</td>
+ <td>none (detected)</td>
+ <td>Yes</td>
+ <td>The name of the parameter, to be used in configuring this
+ parameter from the Mojo's declared defaults (discussed below) or
+ from the POM.
+ <i>Using the toolset, this is detected as the
+ Java field name.</i>
+ </td>
+ </tr>
+ <tr>
+ <td>alias</td>
+ <td>@parameter alias="myAlias"</td>
+ <td>No</td>
+ <td>Specifies an alias which can be used to configure this
+ parameter from the POM. This is primarily useful to improve
+ user-friendliness, where Mojo field names are not intuitive to
+ the user or are otherwise not conducive to configuration via
+ the POM.</td>
+ </tr>
+ <tr>
+ <td>type</td>
+ <td>none (detected)</td>
+ <td>Yes</td>
+ <td>The Java type for this parameter. This is used to validate the
+ result of any expressions used to calculate the value which
+ should be injected into the Mojo for this parameter.
+ <i>Using the
+ toolset, this is detected as the class of the Java field
+ corresponding to this parameter.</i>
+ </td>
+ </tr>
+ <tr>
+ <td>required</td>
+ <td>@required</td>
+ <td>No</td>
+ <td>Whether this parameter is required for the Mojo to function.
+ This is used to validate the configuration for a Mojo before it
+ is injected, and before the Mojo is executed from some
+ half-state.
+ <i>NOTE: Specification of this annotation flags
+ the parameter as required; there is no true/false value.</i>
+ </td>
+ </tr>
+ <tr>
+ <td>editable</td>
+ <td>@readonly</td>
+ <td>No</td>
+ <td>Specifies that this parameter cannot be configured directly by
+ the user (as in the case of POM-specified configuration). This is
+ useful when you want to force the user to use common POM elements
+ rather than plugin configurations, as in the case where you want
+ to use the artifact's final name as a parameter. In this case,
+ you want the user to modify
+ <build><finalName/></build> rather than
+ specifying a value for finalName directly in the plugin
+ configuration section. It is also useful to ensure that - for
+ example - a List-typed parameter which expects items of type
+ Artifact doesn't get a List full of Strings.
+ <i>NOTE:
+ Specification of this annotation flags the parameter as
+ non-editable; there is no true/false value.</i>
+ </td>
+ </tr>
+ <tr>
+ <td>description</td>
+ <td>none (detected)</td>
+ <td>No</td>
+ <td>The description of this parameter's use inside the Mojo.
+ <i>Using the toolset, this is detected as the Javadoc description
+ for the field. NOTE: While this is not a required part of the
+ parameter specification, it SHOULD be provided to enable future
+ tool support for browsing, etc. and for clarity.</i>
+ </td>
+ </tr>
+ <tr>
+ <td>configuration</td>
+ <td>@parameter expression="${someExpression}" default-value="value"</td>
+ <td>No</td>
+ <td>Specifies the expression used to calculate the value to be
+ injected into this parameter of the Mojo at buildtime. This is
+ commonly used to refer to specific elements in the POM, such as
+ ${project.build.resources}, which refers to the List of resources
+ meant to accompany the classes in the resulting jar file.
+ The default value is used when the expression evaluates to
+ <code>null</code>
+ .
+ <i>NOTE: If not specified, an expression of ${<name>} is
+ assumed, which can only be satisfied from POM configuration or
+ System properties. The use of '${' and '}' is required to delimit
+ actual expressions which may be evaluated.</i>
+ </td>
+ </tr>
+ <tr>
+ <td>configuration</td>
+ <td>@component</td>
+ <td>No</td>
+ <td>
+ Populates the field with an instance of a Plexus component. This is like declaring a <i>requirement</i> in a Plexus component.
+ The default requirement will have a role equal to the declared type of the field, and will use the default role hint. You can customise either of these by providing a <code>role</code> and/or <code>roleHint</code> parameter.
- <i>e.g.</i> <code>@component role="org.apache.maven.artifact.ArtifactHandler" roleHint="ear"</code>
+ <i>e.g.</i> <code>@component role="org.apache.maven.artifact.ArtifactHandler" roleHint="ear"</code>
- <b>Note:</b> This is identical to the deprecated form of parameter: <code>@parameter expression="${component.yourpackage.YourComponentClass}"</code>.
- </td>
- </tr>
- <tr>
- <td>deprecated</td>
- <td>@deprecated</td>
- <td>No</td>
- <td>Marks a parameter as deprecated. The rules on deprecation are
- the same as normal Java with language elements. This will trigger
- a warning when a user tries to configure a parameter marked as
- deprecated.</td>
- </tr>
- </table>
- </p>
+ <b>Note:</b> This is identical to the deprecated form of parameter: <code>@parameter expression="${component.yourpackage.YourComponentClass}"</code>.
+ </td>
+ </tr>
+ <tr>
+ <td>deprecated</td>
+ <td>@deprecated</td>
+ <td>No</td>
+ <td>Marks a parameter as deprecated. The rules on deprecation are
+ the same as normal Java with language elements. This will trigger
+ a warning when a user tries to configure a parameter marked as
+ deprecated.</td>
+ </tr>
+ </table>
<p>The final component of a plugin descriptor is the dependencies. This
enables the plugin to function independently of its POM (or at least
to declare the libraries it needs to run). Dependencies are taken from
@@ -690,47 +668,46 @@
project. For pure Java plugins, the differences are even smaller than
for script-based plugins. The following details the POM elements
which are necessary to build a Maven plugin artifact.</p>
+ <table>
+ <tr>
+ <th>POM Element</th>
+ <th>Required for Java Mojos?</th>
+ <th>Sample Declaration</th>
+ <th>Notes</th>
+ </tr>
+ <tr>
+ <td>packaging</td>
+ <td>Yes</td>
+ <td>
+ <code><packaging>
+ maven-plugin
+ </packaging></code>
+ </td>
+ <td>The POM must declare a packaging element which describes this
+ project as a Maven plugin project.</td>
+ </tr>
+ <tr>
+ <td>scriptSourceDirectory</td>
+ <td>No</td>
+ <td>
+ <code><scriptSourceDirectory>
+ src/main/scripts
+ </scriptSourceDirectory></code>
+ </td>
+ <td>In the case of script-based Mojos (which are not covered in
+ detail within this document), the POM must include an additional
+ element to distinguish script sources from (optional) Java
+ supporting classes. This element is <code>scriptSourceDirectory</code>,
+ inside the <code>build</code> section. This directory is included in the list
+ of resources which accompany any compiled code in the resulting
+ artifact. It is specified separately from the resources in the
+ build section to denote its special status as an alternate source
+ directory for scripts.</td>
+ </tr>
+ </table>
+ <p>After making the changes above, the developer can simply call</p>
+ <source>mvn install</source>
<p>
- <table>
- <tr>
- <th>POM Element</th>
- <th>Required for Java Mojos?</th>
- <th>Sample Declaration</th>
- <th>Notes</th>
- </tr>
- <tr>
- <td>packaging</td>
- <td>Yes</td>
- <td>
- <code><packaging>
- maven-plugin
- </packaging></code>
- </td>
- <td>The POM must declare a packaging element which describes this
- project as a Maven plugin project.</td>
- </tr>
- <tr>
- <td>scriptSourceDirectory</td>
- <td>No</td>
- <td>
- <code><scriptSourceDirectory>
- src/main/scripts
- </scriptSourceDirectory></code>
- </td>
- <td>In the case of script-based Mojos (which are not covered in
- detail within this document), the POM must include an additional
- element to distinguish script sources from (optional) Java
- supporting classes. This element is <code>scriptSourceDirectory</code>,
- inside the <code>build</code> section. This directory is included in the list
- of resources which accompany any compiled code in the resulting
- artifact. It is specified separately from the resources in the
- build section to denote its special status as an alternate source
- directory for scripts.</td>
- </tr>
- </table>
- </p>
- <p>After making the changes above, the developer can simply call
- <div class="source"><pre>mvn install</pre></div>
to install the plugin to
the local repository. (Any of the other standard lifecycle targets like
package, deploy, etc. are also available in like fashion.)
@@ -740,37 +717,33 @@
<p>If you're using JetBrains IntelliJ IDEA to develop your plugin,
you can use the following to configure the javadoc annotations as live
templates.</p>
- <p>
- <ol>
- <li>Download <a href="./maven.xml">this file</a>,
- and place it in $USER_HOME/.IntelliJIdea/config/templates</li>
- <li>(re)startup IntelliJ IDEA (templates are loaded on startup)</li>
- <li>add the following list to Settings -> IDE -> Errors -> General
- -> Unknown javadoc tags -> Additional javadoc tags
- <ul>
- <li>aggregator, execute, goal, phase, requiresDirectInvocation,
- requiresProject, requiresReports, requiresOnline, parameter,
- component, required, readonly</li>
- </ul>
- </li>
- </ol>
- </p>
+ <ol>
+ <li>Download <a href="./maven.xml">this file</a>,
+ and place it in $USER_HOME/.IntelliJIdea/config/templates</li>
+ <li>(re)startup IntelliJ IDEA (templates are loaded on startup)</li>
+ <li>add the following list to Settings -> IDE -> Errors -> General
+ -> Unknown javadoc tags -> Additional javadoc tags
+ <ul>
+ <li>aggregator, execute, goal, phase, requiresDirectInvocation,
+ requiresProject, requiresReports, requiresOnline, parameter,
+ component, required, readonly</li>
+ </ul>
+ </li>
+ </ol>
</section>
<section name="Resources">
<p>This section simply gives a listing of pointers for more
information.</p>
- <p>
- <ul>
- <li>QDox Project (Javadoc annotations) [
- <a href="http://qdox.codehaus.org">link</a>
- ]
- </li>
- <li>Plexus Project (Plexus container) [
- <a href="http://plexus.codehaus.org">link</a>
- ]
- </li>
- </ul>
- </p>
+ <ul>
+ <li>QDox Project (Javadoc annotations) [
+ <a href="http://qdox.codehaus.org">link</a>
+ ]
+ </li>
+ <li>Plexus Project (Plexus container) [
+ <a href="http://plexus.codehaus.org">link</a>
+ ]
+ </li>
+ </ul>
</section>
</body>
</document>