Configuration element merging rules
If a configuration element is specified multiple times in the server configuration, the elements are merged. The following rules apply to configuration merging:
- Singleton elements are always merged. In the following example, all instances of the element in
the server configuration are
featureManager
merged to form a singlefeatureManager
element:
The effective configuration becomes:<featureManager> <feature>servlet-3.0</feature> </featureManager> <featureManager> <feature>jdbc-4.0</feature> </featureManager>
<featureManager> <feature>servlet-3.0</feature> <feature>jdbc-4.0</feature> </featureManager>
- Factory elements that are specified at the highest level of the server configuration are merged
if they have the same ID. In the following example, the
dataSource
element withid= "ds1"
is merged and thedataSource
element withid= "ds2"
stays as it is. For example,
The effective configuration becomes:<dataSource id="ds1" jdbcDriverRef="myDriver"/> <dataSource id="ds1" jndiName="jdbc/myDriver"/> <dataSource id="ds2" jdbcDriverRef="myDriver2"/>
<dataSource id="ds1" jdbcDriverRef="myDriver" jndiName="jdbc/myDriver"/> <dataSource id="ds2" jdbcDriverDref="myDriver2"/>
- If a factory element does not have an ID value, it is considered distinct from other elements of
the same type without an ID value. Multiple factory elements without ID values are not merged
together. In the following example, the
dataSource
are not merged, so the effective configuration is the same as the specified configuration:
The effective configuration becomes:<dataSource jdbcDriverRef="myDriver"/> <dataSource jndiName="jdbc/myDriver"/>
<dataSource jdbcDriverRef="myDriver"/> <dataSource jndiName="jdbc/myDriver"/>
- If the elements that are to be merged have conflicting attributes, the merged element uses the
last value that is encountered by the configuration parser. In the following example, the
dataSource
element withid= "ds1"
is merged and thejdbcDriverRef="myDriver2"
is used, whilejdbcDriverRef="myDriver"
is removed.
The effective configuration becomes:<dataSource id="ds1" jdbcDriverRef="myDriver"/> <dataSource id="ds1" jdbcDriverRef="myDriver2"/>
<dataSource id="ds1" jdbcDriverRef="myDriver2"/>
- If a factory element is nested underneath another element, it is merged with other elements
under the same effective parent only. In the following example, the
dataSource
element withid= "ds1"
is merged and theproperties.derby.embedded id="props1"
element is merged with the otherproperties.derby.embedded id="props1"
element whose parent is alsodataSource id="ds1"
.
The effective configuration becomes:<dataSource id="ds1"> <properties.derby.embedded id="props1" databaseName="myDB"/> </dataSource> <dataSource id="ds2"> <properties.derby.embedded id="props1" user="myUser"/> </dataSource> <dataSource id="ds1"> <properties.derby.embedded id="props1" createDatabase="create"/> </dataSource>
<dataSource id="ds1"> <properties.derby.embedded id="props1" databaseName="myDB" createDatabase="create"/> </dataSource> <dataSource id="ds2"> <properties.derby.embedded id="props1" user="myUser"/> </dataSource>
- If a factory element is nested underneath another element and the factory element does not have
a specified ID value, special rules apply depending on the cardinality of the nested element. If
multiple nested elements of a particular type are expected, the elements are not merged. However, if
only a single nested element is expected, the nested elements are merged together. For example,
The effective configuration becomes:<topLevel> <multipleNested enabled="true"/> <multipleNested value="1"/> <singleNested enabled="false"/> <singleNested value="2"/> </topLevel>
<topLevel> <multipleNested enabled="true"/> <multipleNested value="1"/> <singleNested enabled="false" value="2"/> </topLevel>
- If two factory elements are nested underneath another element and the ID values that do not
match, the merging behavior depends on the cardinality of the nested element. If multiple nested
elements are expected, the elements are not merged. If a single nested element is expected, the
nested elements are merged together despite the conflicting ID values. For
example,
The effective configuration becomes:<topLevel> <multipleNested id="1" enabled="true"/> <multipleNested id="2" value="1"/> <singleNested id="3" enabled="false"/> <singleNested id="4" value="2"/> </topLevel>
<topLevel> <multipleNested id="1" enabled="true"/> <multipleNested id="2" value="1"/> <singleNested id="4" enabled="false" value="2"/> </topLevel>