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.

  property = value
  

• 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.

/usr/illumon/latest/bin/dhconfig properties export iris-environment.prop --directory /tmp/propfiles

vi /tmp/propfiles/iris-environment.prop

sudo -u irisadmin /usr/illumon/latest/bin/dhconfig properties import /tmp/propfiles/iris-environment.prop

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.

property = value

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.

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.

includefiles=iris-environment.prop,iris-endpoints.prop

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.

[service.name=iris_console|interactive_console] {
    # For clients, use a relative path to allow lookup from classloader.
    tls.truststore=truststore-iris.p12
    tls.truststore.passphrase.file=truststore_passphrase
}

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.

  [property1.name=value1|value2|value3] {
    # This section is parsed if property1.name equals value1, value2, or value3
  }
  

• 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.

  [property1.name=value1|value2,property2.name=value3] {
    # This section is parsed if property1.name equals value1 or value2,
    # AND property2.name equals value3
  }
  

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

  [        property1.name    =  value1  ] {
    # This section is parsed if "property1.name" equals "value  "
  }
  

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.

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

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>}

Example file

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

# parse iris-defaults.prop, before the contents of this file
includefiles=iris-defaults.prop

# some.property will have the value "second value"
some.property=first value
some.property=second value

# do not permit webserver.sslRequired to be changed later
final webserver.sslRequired=true

# set tls.truststore properties differently in two contexts
# for all server processes, use the absolute path
tls.truststore=/etc/sysconfig/illumon.d/resources/truststore-iris.p12
tls.truststore.passphrase.file=/etc/sysconfig/illumon.d/resources/

# this section applies only if service.name=iris_console OR service.name=interactive_console
[service.name=iris_console|interactive_console] {
    # For clients, use a relative path to allow lookup from classloader.
    tls.truststore=truststore-iris.p12
    tls.truststore.passphrase.file=truststore_passphrase
}

# now that the values have been set, do not allow them to change
finalize tls.truststore.passphrase.file, tls.truststore

# Do not permit truststore_passphrase to be set. Note that if it was given a value in the included iris-defaults.prop file, that value will be kept.
finalize truststore_passphrase


# this section applies if jpy.env=python310
[jpy.env=python310] {
    # the value is the comma-separated text. The consumer must parse it into a collection.
    jpy.pythonLib=/usr/lib/libpython3.10.so,/usr/lib64/libpython3.10.so.1.0,/usr/lib/x86_64-linux-gnu/libpython3.10.so.1
}

# this section applies only if jpy.env=python310 AND os=ubunto
[jpy.env=python310,os=ubuntu] {
    # REPLACE the setting for jpy.pythonLib, when this section applies
    jpy.pythonLib=/usr/lib/x86_64-linux-gnu/libpython3.10.so.1
}

Related documentation

• dhconfig
• dhconfig properties
• Property inspector utility