Maven 2.x Resources Plugin

Proposal for improved resource filtering

Details

  • Type: Improvement Improvement
  • Status: Closed Closed
  • Priority: Major Major
  • Resolution: Fixed
  • Affects Version/s: None
  • Fix Version/s: None
  • Component/s: None
  • Labels:
    None
  • Number of attachments :
    0

Description

The current resource filtering has to be configured at the resource plugin configuration. This issue is about making resource filtering more user-friendly.

There are the following requirements:

1) being able to split resources up into two groups: the filtered-on-copy
group and the 'just-copy' group.

2) being able to specify multiple properties files / having a default file
so users can override. Much like project.properties/build.properties
in maven1.

3) being able to specify different filter properties using profiles

The last item 3) is already working, so this is about 1) and 2).

What about adding the following XML to the resource section of the POM:
<filtering>
<filterIncludes/>
<filterExcludes/>
</filtering>

And this configuration to the resource plugin
<configuration>
<filterPropertyFiles>
<filterPropertyFile>src/build.properties.sample</filterPropertyFile>
<filterPropertyFile failOnError="false">src/build.properties</filterPropertyFile>
</filterProptertyFiles>
</configuration>

From the following list a) and b) address item 1) while c) addresses item 2):

a) As soon as a filtering section is available on a resource, it is filtered.

b) Usually you have in a single resource directory resources that you want to filter and resources that shouldn't be filtered like images etc. One solution to address this is to specify two resource sets in the POM with different include and exlucde filters and turn on/off filtering accordingly.
I think a more elegant way is to say, this is my resource set and filter only these files in this resource set. That's why I added the filterIncludes and filterExcludes section. We can also define default filterExcludes like images etc. On the one hand this is imho a more natural way of defining filtering and on the other hand, this should increase performance. The resource tree has only to be scanned once. With two resources, the tree is scanned twice. Especially if you have big resource trees (e.g. for webapps) this should increase performance noticeably.

c) You can specify several property files at the resource plugin. This files are read in the order of appearance and if a token is defined twice, the last definition read wins. In addition you can set the failOnError flag on a property file, so if this file is missing no error occurs.

I could imagine these optional additions:

4) Defining the tokens in the pom so the plugin
could check which ones are missing and you have an overview of
all the configuration settings used in all the resource files
(the latter being more important).
So, we could add this XML to the filtering section in the POM:
<filterTokens>
<token>tokenname</token>
<token>anothertokenname</token>
</filtertokens>
If the section is missing all tokens are replaced by default.

5) Define properties directly without a property file.
We could add this to the resource plugin configuration:
<filterProperties>
<filterProperty>
<name>aToken</name>
<value>someValue</value>
</filterProperty>
...
</filterProperties>

Issue Links

is depended upon by

Improvement - An improvement or enhancement to an existing feature or task. MWAR-12 Add resource filtering to war plugin

  • Major - Major loss of function.
  • Closed - The issue is considered finished, the resolution is correct. Issues which are not closed can be reopened.

Activity

Ascending order - Click to sort in descending order
Hide
Permalink
Kenney Westerhof added a comment -

hmm, pasting my mail text huh?

Thinking about your <resource> section modification, I first had
an objection to having 2 include/exclude mechanisms in the same resource section
(why add another when a resource section already has that functionality available?),
which would complicate the code and possibly lose some transparency about what was
copied/filtered (the filter in/excludes would have to apply to the results of the normal in/excludes),
but it's the cleanest solution which will usually require the least number of resource sections
in the pom, so +1 for <resource> section modification.

About the multiple property file definition: is that really necessary? What I meant in 2) is that
we could use the maven 1 mechanism: a project.properties that goes with the project (stored in
a version control system), and a build.properties that the user has to supply (with an optional
build.properties.sample file also stored in the repository for convenience.
Required tokens could be specified in the pom as said in 4).

Having multiple property files is nice for specifying project defaults and letting the user
override some settings (or force them to configure some settings using the tokens in 4)),
so users can edit a property file without having to modify a file under source control if they
just want to build the project.

I don't see why someone would specify more than 2 property files that just complete/override
each other as you described. 2 should suffice. Maintenance wise, property files can have comments
to split it up into sections, describing things, so no need for multiple files there.

So in short, modification of 4): specify tokens that have to be defined in one of the 2 property files.
Typical usage: specify configuration options. Which leads to the next idea: allow a description
of those tokens. Ideally something like <token name="smtp.port" description="The port of the smtp server"/>
(but mavenized as to not use attributes, of course (sigh)).

and modification of 3), the property files:
The plugin first reads project.properties. It then overrides those settings with values from the
users active profiles (in his settings.xml) and finally reads build.properties and overrides any
previous setting.
The plugin config files read are configurable in the plugin as '(system|project)PropertyFile' and '(user|build)PropertyFile'
(naming?)

Ad 5): +1, of course (btw, in attribute notation this is:
<filterProperties>
<filterProperty token="aToken">someValue</filterProperty>
</filterProperties>)

But: this is what a default 'project.properties' would do too. So not sure about this. It also
kind of duplicates 4). A possible alternative for both 4 and 5:

<filterProperties>
<filterProperty>
<token>aToken</token>
<description>a description of the configuration property 'aToken'</description>
<!-- optional: a default value for the token, overridable by build.properties/user profile -->
<value>aValue</value>
</filterProperty>
</fitlerProperties>

but.... you don't want to specify the description on each project profile, just in the global plugin config,
and just specify the values in (either execution) or project profiles. (assuming they merge/inherit/override propertly).

just some more thoughts..

Show
Kenney Westerhof added a comment - hmm, pasting my mail text huh? Thinking about your <resource> section modification, I first had an objection to having 2 include/exclude mechanisms in the same resource section (why add another when a resource section already has that functionality available?), which would complicate the code and possibly lose some transparency about what was copied/filtered (the filter in/excludes would have to apply to the results of the normal in/excludes), but it's the cleanest solution which will usually require the least number of resource sections in the pom, so +1 for <resource> section modification. About the multiple property file definition: is that really necessary? What I meant in 2) is that we could use the maven 1 mechanism: a project.properties that goes with the project (stored in a version control system), and a build.properties that the user has to supply (with an optional build.properties.sample file also stored in the repository for convenience. Required tokens could be specified in the pom as said in 4). Having multiple property files is nice for specifying project defaults and letting the user override some settings (or force them to configure some settings using the tokens in 4)), so users can edit a property file without having to modify a file under source control if they just want to build the project. I don't see why someone would specify more than 2 property files that just complete/override each other as you described. 2 should suffice. Maintenance wise, property files can have comments to split it up into sections, describing things, so no need for multiple files there. So in short, modification of 4): specify tokens that have to be defined in one of the 2 property files. Typical usage: specify configuration options. Which leads to the next idea: allow a description of those tokens. Ideally something like <token name="smtp.port" description="The port of the smtp server"/> (but mavenized as to not use attributes, of course (sigh)). and modification of 3), the property files: The plugin first reads project.properties. It then overrides those settings with values from the users active profiles (in his settings.xml) and finally reads build.properties and overrides any previous setting. The plugin config files read are configurable in the plugin as '(system|project)PropertyFile' and '(user|build)PropertyFile' (naming?) Ad 5): +1, of course (btw, in attribute notation this is: <filterProperties> <filterProperty token="aToken">someValue</filterProperty> </filterProperties>) But: this is what a default 'project.properties' would do too. So not sure about this. It also kind of duplicates 4). A possible alternative for both 4 and 5: <filterProperties> <filterProperty> <token>aToken</token> <description>a description of the configuration property 'aToken'</description> <!-- optional: a default value for the token, overridable by build.properties/user profile --> <value>aValue</value> </filterProperty> </fitlerProperties> but.... you don't want to specify the description on each project profile, just in the global plugin config, and just specify the values in (either execution) or project profiles. (assuming they merge/inherit/override propertly). just some more thoughts..
Hide
Permalink
Carsten Ziegeler added a comment -

Your description was very good, so copying it was the ideal solution (it's open source, so copying is allowed)

Thinking about your solution wrt property files, I agree with you. Let's define a fixed set of files (project, build, build.samples) and that's it. +1
I like the description idea - this could be added by the site plugin into the docs for example.

Actually, I'm not sure about your last points either - I think we should start simple and implement the first parts where we are sure and then see how the rest fits.

Show
Carsten Ziegeler added a comment - Your description was very good, so copying it was the ideal solution (it's open source, so copying is allowed) Thinking about your solution wrt property files, I agree with you. Let's define a fixed set of files (project, build, build.samples) and that's it. +1 I like the description idea - this could be added by the site plugin into the docs for example. Actually, I'm not sure about your last points either - I think we should start simple and implement the first parts where we are sure and then see how the rest fits.
Hide
Permalink
Brett Porter added a comment -

I think we are going backwards here (maybe we should have continued to work through this on the list...)

things I definitely disagree with:

  • automatic filenames, especially with names that might cause confusion with maven 1 files.
  • filterIncludes/excludes, I don't agree that this is simpler than splitting it into 2 sets of resources
  • I think you need > 2 filter files in some situations, especially wrt profiles so that you can select just the mysql database filters, for example

I think I should go with my gut and hearken back to this I filed 2 years ago when I was a new user... MAVEN-514. However, I'll simplify it a bit.

so in build:
<filters>
<filter>filename.properties</filter>
</filters>

So, no one off tokens and no selection of different filters for different resources - just the turning on/off of filters within resource sets. I put it in <build> so that the war plugin can use it too (see linked issue).

Show
Brett Porter added a comment - I think we are going backwards here (maybe we should have continued to work through this on the list...) things I definitely disagree with: automatic filenames, especially with names that might cause confusion with maven 1 files. filterIncludes/excludes, I don't agree that this is simpler than splitting it into 2 sets of resources I think you need > 2 filter files in some situations, especially wrt profiles so that you can select just the mysql database filters, for example I think I should go with my gut and hearken back to this I filed 2 years ago when I was a new user... MAVEN-514 . However, I'll simplify it a bit. so in build : <filters> <filter>filename.properties</filter> </filters> So, no one off tokens and no selection of different filters for different resources - just the turning on/off of filters within resource sets. I put it in <build> so that the war plugin can use it too (see linked issue).
Hide
Permalink
Brett Porter added a comment -

setting for resolution in beta-2. This is sort of a new feature improvement but the important thing is retaining backwards compat after beta-1, and I don't want a rushed solution we are stuck with.

Show
Brett Porter added a comment - setting for resolution in beta-2. This is sort of a new feature improvement but the important thing is retaining backwards compat after beta-1, and I don't want a rushed solution we are stuck with.
Hide
Permalink
Carsten Ziegeler added a comment -

Sigh, and I thought this topic was easy...
Anyway, it seems that we all agree to have a filtering "instruction" for a resource which turns on filtering. So what about just adding the simple element <filtering> to the resource section. If the element is available the resources are filtered, if not they are not filtered.
We could do this for beta-1 and can then think about how to add more instructions, either the way Brett wants it, with specifying the properties file or any other way. BUT PLEASE, let's make it configurable NOW if a resource should be filtered or not.

Show
Carsten Ziegeler added a comment - Sigh, and I thought this topic was easy... Anyway, it seems that we all agree to have a filtering "instruction" for a resource which turns on filtering. So what about just adding the simple element <filtering> to the resource section. If the element is available the resources are filtered, if not they are not filtered. We could do this for beta-1 and can then think about how to add more instructions, either the way Brett wants it, with specifying the properties file or any other way. BUT PLEASE, let's make it configurable NOW if a resource should be filtered or not.
Hide
Permalink
Brett Porter added a comment -

agreed, and done. anything that is backwards compat with m1 is a good thing

Show
Brett Porter added a comment - agreed, and done. anything that is backwards compat with m1 is a good thing

People

  • Assignee:
    Brett Porter
    Reporter:
    Carsten Ziegeler
Vote (0)
Watch (1)

Dates

  • Created:
    Updated:
    Resolved:

Time Tracking

Estimated:
1h
Original Estimate - 1 hour Original Estimate - 1 hour
Remaining:
0m
Remaining Estimate - 0 minutes
Logged:
2h
Time Spent - 2 hours