You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by be...@apache.org on 2009/02/28 19:08:04 UTC
svn commit: r748895 - in /maven/site/trunk/src/site/apt/guides:
mini/guide-configuring-plugins.apt plugin/guide-java-plugin-development.apt
Author: bentmann
Date: Sat Feb 28 18:08:03 2009
New Revision: 748895
URL: http://svn.apache.org/viewvc?rev=748895&view=rev
Log:
o Clarified plugin configuration
Modified:
maven/site/trunk/src/site/apt/guides/mini/guide-configuring-plugins.apt
maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt
Modified: maven/site/trunk/src/site/apt/guides/mini/guide-configuring-plugins.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-configuring-plugins.apt?rev=748895&r1=748894&r2=748895&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-configuring-plugins.apt (original)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-configuring-plugins.apt Sat Feb 28 18:08:03 2009
@@ -29,8 +29,22 @@
Guide to Configuring Plug-ins
- In Maven plug-ins are configured by specifying a <<<configuration>>> element where the child elements of the
- <<<configuration>>> element are mapped to fields, or setters, inside your Mojo (remember that a plug-in consists of
+ [[1]] {{{Mapping_Complex_Objects}Mapping Complex Objects}}
+
+ [[2]] {{{Mapping_Collections}Mapping Collections}}
+
+ [[1]] {{{Mapping_Lists}Mapping Lists}}
+
+ [[2]] {{{Mapping_Maps}Mapping Maps}}
+
+ [[3]] {{{Mapping_Properties}Mapping Properties}}
+
+ [[3]] {{{Using_Setters}Using Setters}}
+
+ [[4]] {{{Using_the_executions_Tag}Using the <<<\<executions\>>>> Tag}}
+
+ In Maven plug-ins are configured by specifying a <<<\<configuration\>>>> element where the child elements of the
+ <<<\<configuration\>>>> element are mapped to fields, or setters, inside your Mojo (remember that a plug-in consists of
one or more Mojos where a Mojo maps to a goal). Say, for example, we had a Mojo that performed a query against
a particular URL, with a specified timeout and list of options. The Mojo might look like the following:
@@ -100,10 +114,10 @@
the type of the field and determining if a suitable mapping is possible.
-* Mapping complex objects
+* {Mapping Complex Objects}
Mapping complex types is also fairly straight forward in Maven so let's look at a simple example where we
- are trying to map a configuration for Person object. The <<<configuration>>> element might look like the
+ are trying to map a configuration for Person object. The <<<\<configuration\>>>> element might look like the
following:
+----+
@@ -122,7 +136,7 @@
The rules for mapping complex objects are as follows:
* There must be a private field that corresponds to name of the element being mapped. So in our case the
- <<<person>>> element must map to a <<<person>>> field.
+ <<<person>>> element must map to a <<<person>>> field in the mojo.
* The object instantiated must be in the same package as the Mojo itself. So if your mojo is in
<<<com.mycompany.mojo.query>>> then the mapping mechanism will look in that package for an
@@ -148,12 +162,12 @@
+----+
-* Mapping to collections
+* {Mapping Collections}
The configuration mapping mechanism can easily deal with most collections so let's go through a few examples
to show you how it's done:
-** Mapping lists
+** {Mapping Lists}
Mapping lists works in much the same way as mapping to arrays where you a list of elements will be
mapped to the List. So if you have a mojo like the following:
@@ -203,10 +217,21 @@
+----+
- Where each of the animals listed would be entries in the <<<animals>>> field. If there is no <<<Animal>>> class
- present then the field is assume to be of type <<<java.lang.String>>>.
+ Where each of the animals listed would be entries in the <<<animals>>> field. Unlike arrays, collections have no
+ specific component type. In order to derive the type of a list item, the following strategy is used:
+
+ [[1]] If the XML element contains an <<<implementation>>> hint attribute, that is used
+
+ [[2]] If the XML tag contains a <<<.>>>, try that as a fully qualified class name
+
+ [[3]] Try the XML tag (with capitalized first letter) as a class in the same package as the mojo/object being
+ configured
-** Mapping maps
+ [[4]] If the element has no children, assume its type is <<<String>>>. Otherwise, the configuration will fail.
+
+ []
+
+** {Mapping Maps}
In the same way, you could define maps like the following:
@@ -232,7 +257,7 @@
...
+-----+
-** Mapping properties
+** {Mapping Properties}
Properties should be defined like the following:
@@ -264,7 +289,7 @@
...
+-----+
-* Using setters
+* {Using Setters}
You are not restricted to using private field mapping which is good if you are trying to make you Mojos resuable
outside the context of Maven. Using the example above we could name our private fields using the underscore
@@ -291,11 +316,20 @@
*/
private String[] _options;
- public void setUrl( String url ){ _url = url; }
+ public void setUrl( String url )
+ {
+ _url = url;
+ }
- public void setTimeout( int timeout ){ _timeout = timeout; }
+ public void setTimeout( int timeout )
+ {
+ _timeout = timeout;
+ }
- public void setOptions( String[] options ){ _options = options; }
+ public void setOptions( String[] options )
+ {
+ _options = options;
+ }
public void execute()
throws MojoExecutionException
@@ -306,12 +340,12 @@
+----+
- Note the specification of the property name which tells Maven what setter and getter to use when the field
- is not accessed directly.
+ Note the specification of the property name for each parameter which tells Maven what setter and getter to use when
+ the field's name does not match the intended name of the parameter in the plugin configuration.
-* Using the executions tag
+* {Using the <<<\<executions\>>>> Tag}
- You can also configure a mojo using the executions tag. Using MyQueryMojo
+ You can also configure a mojo using the <<<\<executions\>>>> tag. Using <<<MyQueryMojo>>>
as an example, you may have something that will look like:
+----+
@@ -357,11 +391,11 @@
+----+
The first execution with id "execution1" binds this configuration to the test
- phase. Some goals can have default phases. The second execution does not have
- a <phase> tag, how do you think will the execution behave? If the goal is
- binded to a phase then it will execute to that phase. But if the goal is
- not binded to any lifecycle phases then it will be executed without executing
- any phases(as if it was executed in the CLI).
+ phase. Some goals can have default phase bindings. The second execution does not have
+ a <<<\<phase\>>>> tag, how do you think will the execution behave? If the goal is
+ bound to a phase then it will execute in that phase. But if the goal is
+ not bound to any lifecycle phase then it will be executed without executing
+ any phases (as if it was executed in the CLI).
Note that execution id's don't have to be unique. Executions of the same id
are merged.
@@ -410,10 +444,12 @@
and <<<execution2>>> will be executed applying the configuration setup when
the build phase is already in install.
- Now, Let us have another mojo example which is binded to a lifecycle phase.
+ Now, let us have another mojo example which is bound to a lifecycle phase.
+----+
-@phase package
+/**
+ * @phase package
+ */
public class MyBindedQueryMojo
extends AbstractMojo
{
@@ -440,10 +476,10 @@
}
+----+
- From the above mojo example, MyBindedQueryMojo is binded to package phase
- (see the "@phase" notation). But if we want to execute this mojo to install
- phase not with package we can rebind this mojo into a new lifecycle phase
- using the \<phase\> tag under \<executions\>.
+ From the above mojo example, <<<MyBindedQueryMojo>>> is bound to package phase
+ (see the <<<...@phase>>> notation). But if we want to execute this mojo during the install
+ phase and not with package we can rebind this mojo into a new lifecycle phase
+ using the <<<\<phase\>>>> tag under <<<\<execution\>>>>.
+----+
<project>
@@ -475,11 +511,11 @@
</project>
+----+
- Now, MyBindedQueryMojo default phase which is package has been overrided by
+ Now, <<<MyBindedQueryMojo>>> default phase which is package has been overrided by
install phase.
- Configurations inside the <executions> tag differ from those that are outside
- <executions> in that they cannot be used from a direct command line
+ <<Note:>> Configurations inside the <<<\<executions\>>>> tag differ from those that are outside
+ <<<\<executions\>>>> in that they cannot be used from a direct command line
invocation. Instead they are only applied when the lifecycle phase they are
bound to are invoked. Alternatively, if you move a configuration section
outside of the executions section, it will apply globally to all invocations
Modified: maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt?rev=748895&r1=748894&r2=748895&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt (original)
+++ maven/site/trunk/src/site/apt/guides/plugin/guide-java-plugin-development.apt Sat Feb 28 18:08:03 2009
@@ -504,18 +504,20 @@
value) is determined as follows (the first step which yields a valid class
is used):
- [[1]] If the XML contains an <<<implementation>>> hint, that is used
+ [[1]] If the XML element contains an <<<implementation>>> hint attribute, that is used
- [[2]] If the XML tag contains a <<<.>>>, try that as a class name
+ [[2]] If the XML tag contains a <<<.>>>, try that as a fully qualified class name
- [[3]] Try the XML tag as a class in the same package as the object being
+ [[3]] Try the XML tag (with capitalized first letter) as a class in the same package as the mojo/object being
configured
- [[4]] For arrays, use the class of the array (for example, use <<<String>>>
+ [[4]] For arrays, use the component type of the array (for example, use <<<String>>>
for a <<<String[]>>> parameter); for collections and maps, use the
class specified in the mojo configuration for the collection or map;
use <<<String>>> for entries in a collection and values in a map
+ []
+
Once the type for the element is defined, the text in the XML file is
converted to the appropriate type of object
@@ -562,6 +564,9 @@
</myList>
+-----+
+ For details on the mapping of the individual collection elements, see
+ {{{../mini/guide-configuring-plugins.html#Mapping_Lists}Mapping Lists}}.
+
*** Maps
This category covers any class which implements <<<java.util.Map>>>
@@ -625,13 +630,18 @@
*
* @parameter
*/
- private Object myObject;
+ private MyObject myObject;
+-----+
+-----+
-<myObject>test</myObject>
+<myObject>
+ <myField>test</myField>
+</myObject>
+-----+
+ Please see {{{../mini/guide-configuring-plugins.html#Mapping_Complex_Objects}Mapping Complex Objects}} for details
+ on the strategy used to configure those kind of parameters.
+
* Resources