[M1] RFC on doco - subject is: Setting or getting the value of plugin variables from a plugin context

[Andy Glick <an...@acm.org>]

All,

This is a preliminary reworking of the information that Brett entered into 
Maven-1656. I wanted to let everyone have a look at what I'd cooked up and 
to ask a couple of questions about things that are not clear to me.


Q1) Brett's writeup didn't mention including the namespace for the artifact 
plugin, but in the M1.1b1 examples that I have worked through, the 
inclusion of the namespace is mandatory. So I've added it but enclosed it 
in braces with a note as this poses a potential problem. I've no longer got 
M1 1.0.2 or M1 1.1B1 configured on my development machine, just M1 1.1B2. 
It (M1 1.1B2) doesn't require the artifact namespace, but I did experience 
situations with M1 1.1B1 where it was required. I'm not sure how to go 
about constructing testcases for all of the cases, since they would have to 
vary by Maven version and then by maven.xml file contents and I can't test 
them on my Windows box.


Q2) Maven-1620 has the following text:


Setting a plugin property within a goal before attaining a goal for that 
plugin fails. Whenever it is put in a preGoal it does work correctly.


So it isn't clear to me that method b be can be used to set plugin 
variables as Brett stated in the writeup. It clearly will initialize a 
plugin, but that's not the issue. I've taken the liberty of removing the 
reference to b as a method for setting/getting variable values.


Q3) Are there cases in which none of this will work for whatever reason? 
That isn't clear. Brett and VMassol have both claimed that this is a 
non-deterministic mess, so 1 possibility is that there really are cases in 
which it won't work.


You'll note that I reference some JIRA issues, is that OK in project level 
documentation?  Will people have to register to get read access to the 
pages? You'll also note that I reference "Why We Rewrote Maven". I intend 
to start on that when this is put to bed.


I assume that this should be an entry in the M1 FAQ?


Andy





Setting or getting the value of plugin variables from a plugin context


If the plugin's logic does not determine if the variable that you are 
setting has already been set and it has unconditional logic to set the 
value of the variable, read overwrite your settings, then none of the 
techniques described here will work. So please read the plugin.jelly file. 
All of the plugins are expanded by default into ${user.home}/.maven/cache.


Plugin variables are only visible in the the Jelly execution context of the 
plugin in which they are declared  and only for during the plugin's 
lifecycle. This context is created when the plugin is initialized, read 
first loaded, and is destroyed when the plugin execution completes.


The plugin is initialised when any of the following occur:


a) the executing goal is a preGoal on a goal from that plugin


b) attainGoal has been called for that plugin


c) you have a namespace dependency on the plugin and it only works if you 
reference a tag from the
plugin. This could be done using the <define:taglib uri="test"> syntax, but 
this approach proved to be unrealiable and has been deprecated.


Unfortunately, maven:set does not initialize the plugin context, as the 
Maven developers had at first expected. Plugin initialization, read context 
creation, occurs only as described above, and Jelly code executing in an 
arbitrary maven goal context cannot determine the context in which the 
plugin will run. So, to set or get the value of a plugin variable apply the 
trial and error method as follows:

Number 1 is not necessary for M1 1.1B2, but may be necessary for M1 1.0.2 
and/or 1.1B1 - see above
[1) insert the namespace for the artifact plugin into the local maven.xml 
file's <project> tag, xmlns:artifact="artifact". This binds the artifact 
plugin to the maven context and in some cases it is required.]


2a) if appropriate, set a preGoal on the target plugin coupled with the 
desired maven:set/get statements.


2b) if 2a doesn't work or you know the plugin will not have been 
initialized and you need to set a variable, you should try j:set without a 
scope.


2c) if neither 2a or 2b works then try j:set with a scope of parent as a 
last resort that will work in most but not all situations. [see the initial 
disclaimer]


When 1st recognized, the developers thought that this issue regarding the 
setting/getting of plugin variables could be fixed [see Jira Maven-1467] 
But note Brett's comments about the issue, the fix caused other problems 
which would have required backwards compatibility issues. Given that the 
final conclusion was reached in May of 2005, when Maven 2 was scheduled for 
delivery in only a few months, you can see that this was a non-starter.


This and similar issues with Jelly as an inappropriate execution 
environment were major factors in the development team's decision to 
rewrite Maven, which was reached a long time ago, in 2003. [see URL for Why 
We Rewrote Maven]


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org