HOW-TO: Merge sub-items from parent POM to child POM in a Maven plugin configuration


June 7, 2007 By John Casey

Cross-Posted from my buildchimp blog:

I just ran into a bug report about this, so I thought it might be a good idea to post about it. The bug report detailed a case where the following configurations were not being merged correctly:

Parent POM:

<configuration>
  <items>
    <item>one</item>
    <item>two</item>
  </items>
</configuration>

Child POM:

<configuration>
  <items>
    <item>three</item>
  </items>
</configuration>

Expected result, according to MNG-2591:

<configuration>
  <items>
    <item>one</item>
    <item>two</item>
    <item>three</item>
  </items>
</configuration>

By default, Maven would simply replace the parent’s <items> sub-elements with those from the child, resulting in only one item: three. This is mainly because Maven treats all plugin configuration as XML DOM content, without any idea of what makes up a list of related items, and what is just complex configuration. Moreover, sometimes you want to override the entire list instead of merely appending to it…it’s a difficult balance to strike. However, Maven does support a special attribute to control this behavior. Using the combine.children attribute with a value of append, you can tell Maven to treat the sub-items as a list, and combine them into a single, larger list during inheritance calculations.

As of Revision 545315 in Maven’s Subversion repository (in the latest trunk), things have changed subtly in this functionality, to render a more consistent and intuitive result. Given the same parent POM from above, and this child POM:

<configuration>
  <items combine.children="append">
    <item>three</item>
  </items>
</configuration>

Maven versions prior to this new revision will render the following configuration:

<configuration>
  <items>
    <item>three</item>
    <item>one</item>
    <item>two</item>
  </items>
</configuration>

…while the newest revision in Maven’s SVN repository will render this configuration:

<configuration>
  <items>
    <item>one</item>
    <item>two</item>
    <item>three</item>
  </items>
</configuration>

Admittedly, this is a fairly arcane configuration trick. Hopefully, during the course of our 2.1.x work, we can find a simpler way to change configuration-merging behavior for plugins in Maven’s POM.