The Dataverse Software uses different types of configuration:
JVM system properties
Simple database value settings
Complex database stored data structures
1 and 2 are usually simple text strings, boolean switches or digits. All of those can be found in Configuration.
Anything for 3 is configured via the API using either TSV or JSON structures. Examples are metadata blocks, authentication providers, harvesters and others.
Developers have accessed the simple properties via
System.getProperty(...)for JVM system property settings
SettingsServiceBean.get(...)for database settings and
SystemConfig.xxx()for specially treated settings, maybe mixed from 1 and 2 and other sources.
SettingsWrappermust be used to obtain settings from 2 and 3 in frontend JSF (xhtml) pages. Please see the note on how to avoid common efficiency issues with JSF render logic expressions.
As of Dataverse Software 5.3, we start to streamline our efforts into using a more consistent approach, also bringing joy and happiness to all the system administrators out there. This will be done by adopting the use of MicroProfile Config over time.
So far we streamlined configuration of these Dataverse Software parts:
✅ Database Connection
We should enable variable substitution in JSON configuration. Example: using substitution to retrieve values from MicroProfile Config and insert into the authentication provider would allow much easier provisioning of secrets into the providers.
Developers benefit from:
A streamlined API to retrieve configuration, backward-compatible renaming strategies and easier testbed configurations.
Config API is also pushing for validation of configuration, as it’s typesafe and converters for non-standard types can be added within our codebase.
Defaults in code or bundled in
META-INF/microprofile-config.propertiesallow for optional values without much hassle.
System administrators benefit from:
Lots of database settings have been introduced in the past, but should be more easily configurable and not rely on a database connection.
Running a Dataverse installation in containers gets much easier when configuration can be provisioned in a streamlined fashion, mitigating the need for scripting glue and distinguishing between setting types.
Classic installations have a profit, too: we can enable using a single config file, e.g. living in
Features for monitoring resources and others are easier to use with this streamlined configuration, as we can avoid people having to deal with
asadmincommands and change a setting comfortably instead.
This technology is introduced on a step-by-step basis. There will not be a big shot, crashing upgrades for everyone. Instead, we will provide backward compatibility by deprecating renamed or moved config options, while still supporting the old way of setting them.
Introducing a new setting or moving and old one should result in a key
dataverse.<scope/task/module/...>.<setting>. That way we enable sys admins to recognize the meaning of an option and avoid name conflicts. Starting with
dataversemakes it perfectly clear that this is a setting meant for this application, which is important when using environment variables, system properties or other MPCONFIG sources.
System.getProperty()calls with either injected configs or retrieve programmatically if more complex handling is necessary. If you rename the property, you should provide an alias. See below.
Database settings need to be refactored in multiple steps. First you need to change the code retrieving it to use MicroProfile Config API instead (just like above). Then you should provide an alias to retain backward compatibility. See below.
When moving an old key to a new (especially when doing so with a former JVM system property setting), you should
add an alias to
src/main/resources/META-INF/microprofile-aliases.properties to enable backward compatibility.
The format is always like
Details can be found in
When moving a database setting (
:ExampleSetting), configure an alias
src/main/resources/META-INF/microprofile-aliases.properties. This will enable backward compatibility.
A database setting with an i18n attribute using lang will have available language codes appended to the name.
More details in