Deephaven properties file format

Properties files are text files, usually named with a .prop extension, that store key-value pairs. The key is called a "property". Deephaven properties files add some useful extensions to the standard Java properties format.

Java properties files

Deephaven properties files are based on standard Java properties files:

  • Each line in the file represents a single property-value pair.
  • All whitespace is ignored, except trailing whitespace in the value.
  • Everything is a string.
  • # or ! at the beginning of the line makes a comment.
  • The latest entry wins in case of duplicate properties.
  • Properties are case-sensitive.

Deephaven processes access properties files via the Configuration Service and not from the filesystem, so any files on disk are just for reference and are not authoritative.

To edit a properties file, you need to export it, make edits, and import the changed file. The example below uses an arbitrary directory (/tmp/propfiles), where the executing user has write permission, and administrative user irisadmin has read permission.

See dhconfig and dhconfig properties for more details.

Once a properties file has been changed, any services that use the changed properties must be restarted or reloaded to pick up the changes.

Java system properties

Properties may be passed to the Java runtime on the command line by passing them as JVM arguments, e.g. -DpropertyName=propertyValue. These properties are called "System properties". Certain properties must be set this way, such as those governing how to load the properties file.

System properties are applied after all properties files are loaded, so they have the highest priority and override any settings in properties files.

Key-value parsing

Each line in the file represents a single key-value pair.

Everything before the first equals sign is the key name, and everything after is the value.

Leading whitespace and whitespace surrounding the = is trimmed; trailing whitespace is preserved.

If a value is complex, the application must define how it should be parsed. Some Deephaven property values are comma— or semi-colon-delimited lists.

A property name without an assigned value is assigned an empty string. This is not the same as "undefined", which means the property does not exist in the properties files.

Note

property : value and property value are also valid in Java properties files, but whitespace is not recognized as a separator in Deephaven property files.

Deephaven properties file enhancements

The Deephaven properties file parser adds some important features:

  • includefiles

    Deephaven's includefiles directive causes other properties files to be included in a properties file.

    • includefiles must be the first non-comment line in the file.
    • The latest entry wins. Included files are parsed in order and before settings in the current file. If a property is included in multiple files, the entry in the last file parsed is effective.

  • Scoped stanzas

    A scoped stanza creates a group of settings that only apply to certain processes.

  • Finalization

    The final and finalize keywords create keys that cannot be overridden by later entries.

The includefiles keyword

The includefiles directive must be the first non-comment line in the file. Only one includefiles directive is allowed in a properties file, but it can list multiple files to include, and these can include other files. Included files are processed in order and before the contents of the current file. Settings in later files override those in earlier files.

In a typical installation, iris-common.prop includes iris-environment.prop and iris-endpoints.prop.

  • iris-environment.prop includes iris-defaults.prop.
  • iris-defaults.prop is controlled by Deephaven and contains default values for most properties required by Deephaven processes. Properties set in the other files override these defaults.

Scoped stanzas

A scoped stanza is a scope definition followed by properties enclosed in curly braces.

A scope definition establishes the conditions that must exist for the configuration parser to read the subsequent lines until the end of the scoped region. A scope definition is of the form:

[property1.name=value1{|value2|...valueN}{, property2.name=valueX{|valueY…}}]

The minimum scope declaration is [property.name=value]. In this case, only if the system has a defined property with name property.name and a value equal to value will the subsequent lines be parsed.

  • You may include multiple values for a given property by using a vertical pipe character (|) to separate the different values. It is not possible to use property values containing a vertical pipe for scoping purposes. This is an OR operation - if any one of the specified values matches the value of the specified property, the scope is considered to match the context. Empty values are not permitted.

  • You may include multiple property names in one scope definition. This is an AND operation - all property names within a scope declaration must match at least one of the given values. Undefined properties are considered not to match.

  • Property names are trimmed of whitespace. Values preserve only trailing whitespace (the same way regular lines are parsed).

Finalization

Properties may be specified multiple times in one or more files parsed together. Files are evaluated top to bottom, with includefiles first. The last property setting "wins".

Some property settings should not be overridden. This can be important for properties that need to be kept consistent between processes, ensuring that a key property cannot be overridden in a scoped stanzas or subsequent file. Deephaven properties files support two new keywords to prevent overrides, final and finalize.

Caution

Trying to set a property that has been finalized causes an error that will prevent a process from running.

The final keyword

The final keyword declares that the property definition on the same line may not be further modified.

The final keyword is used in the following form:

final property = value

Note

No property may be defined with the exact name 'final', with or without a value.

The finalize keyword

The finalize keyword declares that the named properties may not be further modified.

This can be useful if a property may have different values in different scopes, but after the sections have been parsed, whatever value the property has should not be further changed.

If the property has not been defined, it is not defined here, and attempting to define it later is an error.

The finalize keyword is used in the following form:

finalize <property.name>{, <property2.name>}

Note

No property may be defined with the exact name 'finalize', with or without a value.

Example file

The following properties file excerpt illustrates some of the formatting features.