Including External Files

For production applications, AMPS configuration files can become large and complicated. In many cases, different instances of an AMPS server need to reuse the same definitions. For example, both servers in a High-Availability pair may need to use the same queue and SOW definitions.

To help you manage complicated configurations and more easily keep configuration consistent on different servers, AMPS allows you to include external files in the configuration file by using the Include directive.

For example, you could use this for a High-Availability pair to include a file that defines the queue, transaction log, and topic definitions. Both instances could include exactly the same file for those definitions, while having different instance names and port numbers.

When AMPS loads a configuration file that contains an Include directive, AMPS follows this process:

• Load and parse the configuration file

• If the file contains any Include directives, load and parse the files specified by those directives. If the included files contain Include directives, load and parse the files specified by those directives (and so forth until all Include directives have been processed).

• Once all files have been loaded and parsed, replace the Include directives in the original files with the parsed files.

AMPS does not process the configuration file until all of the Include directives have been resolved and the files have been parsed.

A file may not be included by any file that it includes, or it is impossible for AMPS to complete the parsing process.

Because each file is individually parsed, XML entities defined in a file are not defined for the files that are Included by that file.

To make it easier to identify which elements of the complete AMPS configuration file have been inserted through the Include mechanism, AMPS can include comments in the assembled file that indicate the source file for configuration elements. By default, this feature is off, and XML content is included verbatim. To change the default for the instance, use the ConfigIncludeCommentDefault configuration element to enable comments, by default, for every Include in the instance. To override commenting behavior for an individual Include, use the comment attribute.

Example

Consider a configuration file with the following Logging element defined:

<AMPSConfig>
    ...

    <Logging>
        <Include comment="true">filetarget.xml</Include>
    </Logging>
</AMPSConfig>

After parsing the configuration file, AMPS loads and parses the filetarget.xml file and replaces the Include element with the contents of that file.

Suppose filetarget.xml contains the following Target directive:

<Target>
    <Protocol>file</Protocol>
    <FileName>/var/log/amps-log-%n.log</FileName>
    <Level>info</Level>
</Target>

The configuration that AMPS uses will be effectively the same as if the configuration file contained the following XML:

<AMPSConfig>
    ...

    <Logging>
        <!-- Start <Include>filetarget.xml</Include> -->
        <Target>
            <Protocol>file</Protocol>
            <FileName>/var/log/amps-log-%n.log</FileName>
            <Level>info</Level>
        </Target>
        <!-- End <Include>filetarget.xml</Include> -->
    </Logging>

    ...
</AMPSConfig>

Include directives are processed at startup, when AMPS loads the configuration file. Changing the included files after AMPS starts has no effect.