# Top-level Pipeline Run Configuration Guide

Top-level Configuration

This chapter describes an alternative, overriding method for specifying many configuration settings for a particular UIMA pipeline run. Its use is optional.

## What is Configuration?

Configuration is externally specified information that exists per UIMA pipeline run. A common example is configuration parameters. Other examples exist; for instance, you can specify where logging is to go.

Configuration consists of key - value pairs, typically stored in a separate file, and written in the style of Java properties files. The same syntax is followed, so you can write: my-key-name : my value string my-key-name = my value string my-key-name my value string or even my-key-name

For the full set of rules, see the Javadocs for the Java `Properties`.

Multiple properties files are allowed; they are loaded in an order, such that later ones take precidence over earlier ones. So, if you have lots of properties, you can put the defaults in one file, and then in another file, just override the ones you need to.

Individual key-value pairs can also be specified on the Java command line, using the Java `-D` parameter; these override same-named keys that come from other sources.

## Where Configuration Information comes from

The common use case is to put the key-value pairs into one (or more) properties files. Properties can also be entered, individually, on the Java command line, as `-D` parameters; properties entered in this way override other specifications.

Properties may also be specified in a new XML element, <topLevelSettings>, in the <operationalProperties> element of a top level descriptor. <topLevelSettings> is ignored for other than the top level descriptor for a particular UIMA run.

<topLevelSettings> can contain 0 or more standard UIMA <import> elements, specifying multiple properties files to import. However, it can also have 0 or more <settings elements, the inner text of which is taken as the contents of a properties file, inline.

## How it works

At startup time, the property specifications are read and stored in a set of normal Java Properties class instances. These are arranged according to the defaulting order, in the case where there are more than one source.

Individual configuration parameter specifications in the descriptors will ignore this, unless a particular parameter declaration has an additional <topLevelName> element, which specifies the key name to be used at the top level to set this parameter's value. If this name is present, and if a value can be found for this key from among the top level property specifications (including system properties set with the Java `-D` parameter), then this value overrides the value otherwise specified for this parameter.

It is expected that the deployer will create the key names and add them to the configuration descriptors, where needed.

You may use the same top level name for multiple parameters; the effect of this is that one setting at the top level will override multiple parameters.