Using Modular Configuration Files

Use <xi:include> and href= instead of <sb-include> and file=. For example:

<xi:include href="security-settings.xml" />
<xi:include href="../../custom-functions.xml" />

You cannot use the ${param} syntax to place an environment variable in your href URL.

There are cases where you do not need to wrap the fragment file's top element in a <streambase-configuration> wrapper. For example:

<?xml version="1.0"?>
<security>
  <ssl-authentication>
    <param name="keystore" ...
  ...
</security>

However, since the <streambase-configuration> wrapper works with both <sb-include> and <xi:include>, TIBCO recommends using it in all configuration fragment files.

There can be only one root <streambase-configuration> element.

There can be only one of each first-level element (<global>, <server>, <java-vm>, and so on).

Fragment files XIncluded in a top-level file must contain elements with valid XML, but cannot be fully valid server configuration files with a <streambase-configuration> root element.

You can temporarily add a <streambase-configuration> root element to your fragment files to get the advantages of autocompletion and tag suggestion while using the Studio Configuration File Editor. When using strict rules, you must remove this root element before using the file as an XIncluded XML fragment.

The <streambase-configuration> element can appear again as a child of the root <streambase-configuration> element. This allows you to combine two or more complete configuration files that are each valid in their own contexts.

Each <streambase-configuration> element can contain zero or more child elements.

At whatever nesting depth a <streambase-configuration> element appears as a child, all of its first-level child elements are considered added to the root <streambase-configuration> element of the resolved top-level file.

The above rules mean that a fragment file with <streambase-configuration> root element is a fully valid configuration file, and can take advantage of all the editing conveniences of the Studio Configuration File Editor.

There can be more than one of most elements that were formerly restricted to one each. This applies to the first-level elements (<global>, <server>, <java-vm>, and so on), and to non-list child elements of those.

If, after resolving all included fragments, the root level contains more than one of the same element, they are merged together into one element.

Despite the previous rule, the following elements are never merged because merging might compromise security, or because the union of their attributes has no logical value.

The following elements are considered list elements that can appear more than once under their parent and have no child nodes. The children of list elements are merged with special handling described below.

If the resolved file contains more than one first-level element (<global>, <server>, <java-vm>, and so on), then regardless of the order in which they appear, they are each merged into a single element of the same name.

In general, if two merged fragments of the same first-level element define different child elements and thus have no conflicts, they are merged into a single element of that name. Later-appearing lines are appended to earlier-appearing lines for that element.

In general, if two merged fragments define the same element, the last-appearing definition wins. This allows you to override a setting made early in a file with a configuration fragment entered or included near the end of the file.

In general, if two merged fragments define the same attribute or define multiple <param> elements with the same name, the last-appearing attribute or <param name=/> wins. Exceptions:

When parsing the configuration file with all includes resolved, StreamBase uses the following rules to detect elements and attributes that need to be merged:

When comparing a first-level element defined in the base configuration file with the same element defined or included later in the file, StreamBase looks for competing child elements of those first-level elements under comparison. Two child elements match when they meet all these criteria:

If two compared child elements match, they are merged. This usually means the last-defined one wins, with exceptions noted above.

If two compared child elements do not match, the later-defined child element is appended to the parent of the first-defined child element. Notice that this rule covers all children of list elements, which are simply appended top-to-bottom in the order parsed from the resolved configuration file.