You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by Benson Margulies <bi...@gmail.com> on 2011/08/23 20:24:43 UTC
execute versus executeReport (was, as it were, JXR-93)
I am somewhat confused by the design of the site plugin with respect
to adding additional goals.
The new pattern is to move from 'aggregate' configuration property
booleans to more goals. However, goals have to be called out in
executions, and the reporting section can't spec an execution, and
we're moving away from the reporting section, anyway. So now you end
up with the same plugin called out as an ordinary plugin as well as in
a report, and it needs an execute method that does the same thing as
its executeReport, and both get called.
Is there anything written down about how all this is supposed to play?
Can the site plugin be told which goal to run executeReport for, or
are these additional executions actually needed.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: execute versus executeReport (was, as it were, JXR-93)
Posted by Benson Margulies <bi...@gmail.com>.
On Tue, Aug 23, 2011 at 6:14 PM, Hervé BOUTEMY <he...@free.fr> wrote:
> no
>
> IMHO, javadoc plugin documents both reporting and build tags [1]
It's the aggregate IT in javadoc that sent me off the rails. I'm better now.
>
> but only reporting should be used
>
> and it works perfectly for Maven core 3.0.4-SNAPSHOT: really, jxr aggregate
> support is fine actually when configured as reporting
>
> and we should promote reporting configuration only
>
> Regards,
>
> Hervé
>
> [1] http://maven.apache.org/plugins/maven-javadoc-plugin/examples/selective-
> javadocs-report.html
>
> Le mardi 23 août 2011, Benson Margulies a écrit :
>> On Tue, Aug 23, 2011 at 5:26 PM, Hervé BOUTEMY <he...@free.fr>
> wrote:
>> > I have been confused for a long time too, but finally had some
>> > explanations I can try to summary here: not sure it will give every
>> > answers, but at least I suppose it will help.
>>
>> Hervé,
>>
>> So far so good, and you can see that I cribbed an execute method from
>> javadoc into JXR this afternoon.
>>
>> I have some followup qualms. executeReport is called with a Locale.
>> execute is not. So, when we use execute in order to force the use of
>> a particular goal, we turn off all the multi-locale support. Further,
>> looks to me as if both execute and executeReport get called. In this
>> 'aggregate' pattern, execute ends up with the aggregate goal,
>> executeReport ends up with the plain goal. The site plugin config
>> inherits down, so, contra the doc, we end up with disaggregated
>> reports down below as well as the aggregated info on top.
>>
>> Maybe I just misunderstood the pattern in the javadoc tests; is the
>> right thing to put the aggregate goal in build/plugins and nothing in
>> the site plugin? But if I do that, how will the site plugin know to
>> link to the report?
>>
>> All in all, it seems to me that the site plugin
>> configuration/reportPlugins/plugin should include 'goals' in its valid
>> children, so that one could run a particular goal.
>>
>> Or, maybe I'm just missing the point of why the move from
>> configuration/aggregate to having another goal?
>>
>> --benson
>>
>> > It has to do with the difference in API between a maven plugin (execute
>> > method from plugin-api [1]) and a reporting plugin (essentially generate
>> > method from maven-reporting-api [2]) which is in fact a m-site-p plugin,
>> > not really a Maven core plugin.
>> >
>> > Usually, you write a reporting plugin that is a Maven plugin too, but
>> > AFAIK you can write a reporting plugin that is not a Maven plugin (I
>> > didn't really tried though).
>> > Usually, nobody does that because there are drawbacks:
>> > - you can't define it in pluginManagement section (yes, it's not a Maven
>> > plugin in this case...),
>> > - maven-plugin-plugin won't generate plugin descriptor for you
>> > - you won't be able to launch the report as a maven CLI invocation
>> > Then usually, every reporting plugin is a build plugin too: for example,
>> > even if m-project-info-report-p is announced as solely reporting plugin
>> > in our plugin list, it is a build plugin too.
>> >
>> > When the reporting tool does not use site-descriptor+skin (javadoc, jxr,
>> > surefire, ...), the execute method is quite simple then it is copied in
>> > every plugin: see javadoc [3] for example
>> >
>> > When the reporting tool requires skin, the plugin invocation is harder:
>> > maven- reporting-impl tries to implement an AbstractMavenReport class
>> > [4] containing the logic for dual execution (the execute method is
>> > implemented). A lot of reporting plugins extend AbstractMavenReport.
>> >
>> >
>> > This is the summary of my understanding when I worked on
>> > maven-reporting-impl and maven-reporting-api decoupling from core.
>> >
>> > Now the consequences on execute vs reportSets. If you intend to call
>> > multiple reports when generating site, it is a site phase feature then
>> > should be configured in reporting section with reportSets. Build plugins
>> > are for maven CLI invocation, without site phase lifecycle binding.
>> > Notice that while I'm writing this now, it's the furst time I'm really
>> > understanding it :)
>> >
>> > Regards,
>> >
>> > Hervé
>> >
>> > [1] http://maven.apache.org/ref/current/maven-plugin-api/
>> >
>> > [2] http://maven.apache.org/shared/maven-reporting-api/
>> >
>> > [3] http://maven.apache.org/plugins/maven-javadoc-
>> > plugin/xref/org/apache/maven/plugin/javadoc/JavadocReport.html#296
>> >
>> > [4] http://maven.apache.org/shared/maven-reporting-
>> > impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html
>> >
>> > Le mardi 23 août 2011, Benson Margulies a écrit :
>> >> I am somewhat confused by the design of the site plugin with respect
>> >> to adding additional goals.
>> >>
>> >> The new pattern is to move from 'aggregate' configuration property
>> >> booleans to more goals. However, goals have to be called out in
>> >> executions, and the reporting section can't spec an execution, and
>> >> we're moving away from the reporting section, anyway. So now you end
>> >> up with the same plugin called out as an ordinary plugin as well as in
>> >> a report, and it needs an execute method that does the same thing as
>> >> its executeReport, and both get called.
>> >>
>> >> Is there anything written down about how all this is supposed to play?
>> >> Can the site plugin be told which goal to run executeReport for, or
>> >> are these additional executions actually needed.
>> >>
>> >> ---------------------------------------------------------------------
>> >> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> >> For additional commands, e-mail: dev-help@maven.apache.org
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> > For additional commands, e-mail: dev-help@maven.apache.org
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: execute versus executeReport (was, as it were, JXR-93)
Posted by Hervé BOUTEMY <he...@free.fr>.
no
IMHO, javadoc plugin documents both reporting and build tags [1]
but only reporting should be used
and it works perfectly for Maven core 3.0.4-SNAPSHOT: really, jxr aggregate
support is fine actually when configured as reporting
and we should promote reporting configuration only
Regards,
Hervé
[1] http://maven.apache.org/plugins/maven-javadoc-plugin/examples/selective-
javadocs-report.html
Le mardi 23 août 2011, Benson Margulies a écrit :
> On Tue, Aug 23, 2011 at 5:26 PM, Hervé BOUTEMY <he...@free.fr>
wrote:
> > I have been confused for a long time too, but finally had some
> > explanations I can try to summary here: not sure it will give every
> > answers, but at least I suppose it will help.
>
> Hervé,
>
> So far so good, and you can see that I cribbed an execute method from
> javadoc into JXR this afternoon.
>
> I have some followup qualms. executeReport is called with a Locale.
> execute is not. So, when we use execute in order to force the use of
> a particular goal, we turn off all the multi-locale support. Further,
> looks to me as if both execute and executeReport get called. In this
> 'aggregate' pattern, execute ends up with the aggregate goal,
> executeReport ends up with the plain goal. The site plugin config
> inherits down, so, contra the doc, we end up with disaggregated
> reports down below as well as the aggregated info on top.
>
> Maybe I just misunderstood the pattern in the javadoc tests; is the
> right thing to put the aggregate goal in build/plugins and nothing in
> the site plugin? But if I do that, how will the site plugin know to
> link to the report?
>
> All in all, it seems to me that the site plugin
> configuration/reportPlugins/plugin should include 'goals' in its valid
> children, so that one could run a particular goal.
>
> Or, maybe I'm just missing the point of why the move from
> configuration/aggregate to having another goal?
>
> --benson
>
> > It has to do with the difference in API between a maven plugin (execute
> > method from plugin-api [1]) and a reporting plugin (essentially generate
> > method from maven-reporting-api [2]) which is in fact a m-site-p plugin,
> > not really a Maven core plugin.
> >
> > Usually, you write a reporting plugin that is a Maven plugin too, but
> > AFAIK you can write a reporting plugin that is not a Maven plugin (I
> > didn't really tried though).
> > Usually, nobody does that because there are drawbacks:
> > - you can't define it in pluginManagement section (yes, it's not a Maven
> > plugin in this case...),
> > - maven-plugin-plugin won't generate plugin descriptor for you
> > - you won't be able to launch the report as a maven CLI invocation
> > Then usually, every reporting plugin is a build plugin too: for example,
> > even if m-project-info-report-p is announced as solely reporting plugin
> > in our plugin list, it is a build plugin too.
> >
> > When the reporting tool does not use site-descriptor+skin (javadoc, jxr,
> > surefire, ...), the execute method is quite simple then it is copied in
> > every plugin: see javadoc [3] for example
> >
> > When the reporting tool requires skin, the plugin invocation is harder:
> > maven- reporting-impl tries to implement an AbstractMavenReport class
> > [4] containing the logic for dual execution (the execute method is
> > implemented). A lot of reporting plugins extend AbstractMavenReport.
> >
> >
> > This is the summary of my understanding when I worked on
> > maven-reporting-impl and maven-reporting-api decoupling from core.
> >
> > Now the consequences on execute vs reportSets. If you intend to call
> > multiple reports when generating site, it is a site phase feature then
> > should be configured in reporting section with reportSets. Build plugins
> > are for maven CLI invocation, without site phase lifecycle binding.
> > Notice that while I'm writing this now, it's the furst time I'm really
> > understanding it :)
> >
> > Regards,
> >
> > Hervé
> >
> > [1] http://maven.apache.org/ref/current/maven-plugin-api/
> >
> > [2] http://maven.apache.org/shared/maven-reporting-api/
> >
> > [3] http://maven.apache.org/plugins/maven-javadoc-
> > plugin/xref/org/apache/maven/plugin/javadoc/JavadocReport.html#296
> >
> > [4] http://maven.apache.org/shared/maven-reporting-
> > impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html
> >
> > Le mardi 23 août 2011, Benson Margulies a écrit :
> >> I am somewhat confused by the design of the site plugin with respect
> >> to adding additional goals.
> >>
> >> The new pattern is to move from 'aggregate' configuration property
> >> booleans to more goals. However, goals have to be called out in
> >> executions, and the reporting section can't spec an execution, and
> >> we're moving away from the reporting section, anyway. So now you end
> >> up with the same plugin called out as an ordinary plugin as well as in
> >> a report, and it needs an execute method that does the same thing as
> >> its executeReport, and both get called.
> >>
> >> Is there anything written down about how all this is supposed to play?
> >> Can the site plugin be told which goal to run executeReport for, or
> >> are these additional executions actually needed.
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> >> For additional commands, e-mail: dev-help@maven.apache.org
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> > For additional commands, e-mail: dev-help@maven.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: execute versus executeReport (was, as it were, JXR-93)
Posted by Benson Margulies <bi...@gmail.com>.
On Tue, Aug 23, 2011 at 5:26 PM, Hervé BOUTEMY <he...@free.fr> wrote:
> I have been confused for a long time too, but finally had some explanations I
> can try to summary here: not sure it will give every answers, but at least I
> suppose it will help.
Hervé,
So far so good, and you can see that I cribbed an execute method from
javadoc into JXR this afternoon.
I have some followup qualms. executeReport is called with a Locale.
execute is not. So, when we use execute in order to force the use of
a particular goal, we turn off all the multi-locale support. Further,
looks to me as if both execute and executeReport get called. In this
'aggregate' pattern, execute ends up with the aggregate goal,
executeReport ends up with the plain goal. The site plugin config
inherits down, so, contra the doc, we end up with disaggregated
reports down below as well as the aggregated info on top.
Maybe I just misunderstood the pattern in the javadoc tests; is the
right thing to put the aggregate goal in build/plugins and nothing in
the site plugin? But if I do that, how will the site plugin know to
link to the report?
All in all, it seems to me that the site plugin
configuration/reportPlugins/plugin should include 'goals' in its valid
children, so that one could run a particular goal.
Or, maybe I'm just missing the point of why the move from
configuration/aggregate to having another goal?
--benson
>
> It has to do with the difference in API between a maven plugin (execute method
> from plugin-api [1]) and a reporting plugin (essentially generate method from
> maven-reporting-api [2]) which is in fact a m-site-p plugin, not really a
> Maven core plugin.
>
> Usually, you write a reporting plugin that is a Maven plugin too, but AFAIK
> you can write a reporting plugin that is not a Maven plugin (I didn't really
> tried though).
> Usually, nobody does that because there are drawbacks:
> - you can't define it in pluginManagement section (yes, it's not a Maven plugin
> in this case...),
> - maven-plugin-plugin won't generate plugin descriptor for you
> - you won't be able to launch the report as a maven CLI invocation
> Then usually, every reporting plugin is a build plugin too: for example, even
> if m-project-info-report-p is announced as solely reporting plugin in our
> plugin list, it is a build plugin too.
>
> When the reporting tool does not use site-descriptor+skin (javadoc, jxr,
> surefire, ...), the execute method is quite simple then it is copied in every
> plugin: see javadoc [3] for example
>
> When the reporting tool requires skin, the plugin invocation is harder: maven-
> reporting-impl tries to implement an AbstractMavenReport class [4] containing
> the logic for dual execution (the execute method is implemented). A lot of
> reporting plugins extend AbstractMavenReport.
>
>
> This is the summary of my understanding when I worked on maven-reporting-impl
> and maven-reporting-api decoupling from core.
>
> Now the consequences on execute vs reportSets. If you intend to call multiple
> reports when generating site, it is a site phase feature then should be
> configured in reporting section with reportSets. Build plugins are for maven
> CLI invocation, without site phase lifecycle binding.
> Notice that while I'm writing this now, it's the furst time I'm really
> understanding it :)
>
> Regards,
>
> Hervé
>
> [1] http://maven.apache.org/ref/current/maven-plugin-api/
>
> [2] http://maven.apache.org/shared/maven-reporting-api/
>
> [3] http://maven.apache.org/plugins/maven-javadoc-
> plugin/xref/org/apache/maven/plugin/javadoc/JavadocReport.html#296
>
> [4] http://maven.apache.org/shared/maven-reporting-
> impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html
>
> Le mardi 23 août 2011, Benson Margulies a écrit :
>> I am somewhat confused by the design of the site plugin with respect
>> to adding additional goals.
>>
>> The new pattern is to move from 'aggregate' configuration property
>> booleans to more goals. However, goals have to be called out in
>> executions, and the reporting section can't spec an execution, and
>> we're moving away from the reporting section, anyway. So now you end
>> up with the same plugin called out as an ordinary plugin as well as in
>> a report, and it needs an execute method that does the same thing as
>> its executeReport, and both get called.
>>
>> Is there anything written down about how all this is supposed to play?
>> Can the site plugin be told which goal to run executeReport for, or
>> are these additional executions actually needed.
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
>> For additional commands, e-mail: dev-help@maven.apache.org
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org
Re: execute versus executeReport (was, as it were, JXR-93)
Posted by Hervé BOUTEMY <he...@free.fr>.
I have been confused for a long time too, but finally had some explanations I
can try to summary here: not sure it will give every answers, but at least I
suppose it will help.
It has to do with the difference in API between a maven plugin (execute method
from plugin-api [1]) and a reporting plugin (essentially generate method from
maven-reporting-api [2]) which is in fact a m-site-p plugin, not really a
Maven core plugin.
Usually, you write a reporting plugin that is a Maven plugin too, but AFAIK
you can write a reporting plugin that is not a Maven plugin (I didn't really
tried though).
Usually, nobody does that because there are drawbacks:
- you can't define it in pluginManagement section (yes, it's not a Maven plugin
in this case...),
- maven-plugin-plugin won't generate plugin descriptor for you
- you won't be able to launch the report as a maven CLI invocation
Then usually, every reporting plugin is a build plugin too: for example, even
if m-project-info-report-p is announced as solely reporting plugin in our
plugin list, it is a build plugin too.
When the reporting tool does not use site-descriptor+skin (javadoc, jxr,
surefire, ...), the execute method is quite simple then it is copied in every
plugin: see javadoc [3] for example
When the reporting tool requires skin, the plugin invocation is harder: maven-
reporting-impl tries to implement an AbstractMavenReport class [4] containing
the logic for dual execution (the execute method is implemented). A lot of
reporting plugins extend AbstractMavenReport.
This is the summary of my understanding when I worked on maven-reporting-impl
and maven-reporting-api decoupling from core.
Now the consequences on execute vs reportSets. If you intend to call multiple
reports when generating site, it is a site phase feature then should be
configured in reporting section with reportSets. Build plugins are for maven
CLI invocation, without site phase lifecycle binding.
Notice that while I'm writing this now, it's the furst time I'm really
understanding it :)
Regards,
Hervé
[1] http://maven.apache.org/ref/current/maven-plugin-api/
[2] http://maven.apache.org/shared/maven-reporting-api/
[3] http://maven.apache.org/plugins/maven-javadoc-
plugin/xref/org/apache/maven/plugin/javadoc/JavadocReport.html#296
[4] http://maven.apache.org/shared/maven-reporting-
impl/apidocs/org/apache/maven/reporting/AbstractMavenReport.html
Le mardi 23 août 2011, Benson Margulies a écrit :
> I am somewhat confused by the design of the site plugin with respect
> to adding additional goals.
>
> The new pattern is to move from 'aggregate' configuration property
> booleans to more goals. However, goals have to be called out in
> executions, and the reporting section can't spec an execution, and
> we're moving away from the reporting section, anyway. So now you end
> up with the same plugin called out as an ordinary plugin as well as in
> a report, and it needs an execute method that does the same thing as
> its executeReport, and both get called.
>
> Is there anything written down about how all this is supposed to play?
> Can the site plugin be told which goal to run executeReport for, or
> are these additional executions actually needed.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
> For additional commands, e-mail: dev-help@maven.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org