Configuration Document Overrides

There are situations where a configuration document can override or be overridden by other configuration documents. For example, a configuration document that exists on a host might override configuration documents that exist on a cluster to which the host belongs. In such cases, values for keys must look through all of the files that might override the values, and choose the one with the highest priority. In this example, the host’s local configuration document has a higher priority than the cluster document.

To define file overrides in the dependency signature, use the following syntax to add multiple paths with priority to a configuration document:

<PropertiesConfigurationDocument name="resources.xml">
   <DocumentCILocation>
      <ReferenceLocation priority="2">websphereas_resource_configfiles</ReferenceLocation>
      <ReferenceLocation priority="3">j2ee_cluster_configfiles</ReferenceLocation>
      <ReferenceLocation priority="1">j2eeapplication_configfiles</ReferenceLocation>
   </DocumentCILocation>     
   …
</PropertiesConfigurationDocument

The file name (resources.xml in the above example) must be the same in all reference locations.

Keep in mind that a reference location is a reference to a TQL query that specifies a topological path from the consumer deployable component to the configuration document. This also means that such a path must exist between the deployable component and all of the different locations. For more information about <DocumentCILocation> see Specify Paths of Configuration Documents.

The condition itself does not change when you add multiple paths that have priorities. At runtime (when the search expression is evaluated), the correct values according to the priorities are used. For example, in properties files, if given a Key K that exists both in priority 1 and priority 2 (with a condition on its value), the condition will only be evaluated on the document with priority 1. If the key K exists only in priority 2, the condition will only be evaluated on the document with priority 2.

For more information on properties conditions, see Properties Configuration Documents.

In XML documents, each XPath is considered a key. For example, \Root\Element\@Attribute means that the attribute “Attribute” with that path is a key, and its value might be overridden in different files.

If the XPath also has some constant condition (a condition not involving variables), that condition will be part of the key. For example: \Root\Element[@name = ‘name’]\@Attribute.

However, if the XPath has a non-constant condition, those conditions are stripped from the key, and are considered to be part of the value. So for the path \Root\Element[@name = ${NAME}]\@Attribute, the key would be the path \Root\Element\@Attribute and the condition Element[@name = ‘name’] will only be evaluated on the highest priority document where that key exists.

If an XML document uses priorities, it is important to make sure the XPath conditions are built as described above, to prevent incorrect and unexpected behavior.

For more information on XPath conditions, see XML Configuration Documents.

Multiple Configuration Documents with the same Priority”

It is possible to given the same priority to different <ReferenceLocation> elements. In this case, when evaluating a condition, the framework will look at all files with the same priority and will try and match all of them.

The condition will evaluate to True if at least a set number of files evaluates to True. The number of files is defined by the samePriorityMatchAtLeast attribute .

For example:

<PropertiesConfigurationDocument name="resources.xml">
   <DocumentCILocation samePriorityMatchAtLeast=”1”>
      <ReferenceLocation priority="1">websphereas_resource_configfiles</ReferenceLocation>
      <ReferenceLocation priority="1">j2ee_cluster_configfiles</ReferenceLocation>
      <ReferenceLocation priority="1">j2eeapplication_configfiles</ReferenceLocation>
   </DocumentCILocation>
…
</PropertiesConfigurationDocument>

This means that when evaluating a condition, at least one of the referenced file locations is to a file where the condition evaluates to True.

Note Currently, only the value of 1 is supported for the samePriorityMatchAtLeast attribute.