From c86517de09c0c54e9792d30c46ef1ed982c69ed7 Mon Sep 17 00:00:00 2001 From: Philip Durbin Date: Tue, 6 Sep 2022 15:30:44 -0400 Subject: [PATCH] tweak docs and release note #7000 Emphasize that the change is for devs for now. The idea is to migrate settings to the new framework over time. --- doc/release-notes/7000-mpconfig-support.md | 15 +++------------ .../source/developers/configuration.rst | 19 ++++++++----------- .../source/developers/testing.rst | 2 +- 3 files changed, 12 insertions(+), 24 deletions(-) diff --git a/doc/release-notes/7000-mpconfig-support.md b/doc/release-notes/7000-mpconfig-support.md index cea26968139..f2585dc2bf5 100644 --- a/doc/release-notes/7000-mpconfig-support.md +++ b/doc/release-notes/7000-mpconfig-support.md @@ -1,15 +1,6 @@ -# Introducing broader MicroProfile Config Support +# Broader MicroProfile Config Support for Developers As of this release, many [JVM options](https://guides.dataverse.org/en/latest/installation/config.html#jvm-options) -support to be set using any [MicroProfile Config Source](https://docs.payara.fish/community/docs/Technical%20Documentation/MicroProfile/Config/Overview.html#config-sources). +can be set using any [MicroProfile Config Source](https://docs.payara.fish/community/docs/Technical%20Documentation/MicroProfile/Config/Overview.html#config-sources). -This allows for much greater flexibility when configuring your Dataverse installation, especially when making use -of containers, setting up development environments or firing up ephemeral environments for CI etc. - -Some options have been renamed for better consistency. Docs have been changed and enhanced accordingly. -**Important** to know: any old settings remain to work as-is, but you'll find deprecation hints in the logs. - -Future enhancements to this may include: -- Validation of JVM options on start -- Interoperability with database settings -- Single file configurability for your installation (sth. like /etc/dataverse.conf) and hot-reload +Currently this change is only relevant to developers but as settings are migrated to the new "lookup" pattern documented in the [Consuming Configuration](https://guides.dataverse.org/en/latest/developers/configuration.html) section of the Developer Guide, anyone installing the Dataverse software will have much greater flexibility when configuring those settings, especially within containers. These changes will be announced in future releases. diff --git a/doc/sphinx-guides/source/developers/configuration.rst b/doc/sphinx-guides/source/developers/configuration.rst index f7b0fc85693..fb15fea7900 100644 --- a/doc/sphinx-guides/source/developers/configuration.rst +++ b/doc/sphinx-guides/source/developers/configuration.rst @@ -18,13 +18,12 @@ authentication providers, harvesters and others. Simple Configuration Options ---------------------------- -Developers have accessed the simple properties via +Developers can access simple properties via: -1. ``JvmSettings..lookup(...)`` for JVM system property settings -2. ``SettingsServiceBean.get(...)`` for database settings and +1. ``JvmSettings..lookup(...)`` for JVM system property settings. +2. ``SettingsServiceBean.get(...)`` for database settings. 3. ``SystemConfig.xxx()`` for specially treated settings, maybe mixed from 1 and 2 and other sources. -4. ``SettingsWrapper`` must be used to obtain settings from 2 and 3 in frontend JSF (xhtml) pages. Please see the note - on how to :ref:`avoid common efficiency issues with JSF render logic expressions +4. ``SettingsWrapper`` for use in frontend JSF (xhtml) pages to obtain settings from 2 and 3. Using the wrapper is a must for performance as explained in :ref:`avoid common efficiency issues with JSF render logic expressions `. 5. ``System.getProperty()`` only for very special use cases not covered by ``JvmSettings``. @@ -34,7 +33,6 @@ happiness to all the system administrators out there. This will be done by adopt So far we streamlined configuration of these Dataverse Software parts: -- ✅ Version information - ✅ Database Connection Complex Configuration Options @@ -86,19 +84,18 @@ supporting the old way of setting them. Adding a JVM Setting ^^^^^^^^^^^^^^^^^^^^ -Whenever a new options gets added or an existing configuration migrated to +Whenever a new option gets added or an existing configuration gets migrated to ``edu.harvard.iq.dataverse.settings.JvmSettings``, you will attach the setting to an existing scope or create new sub-scopes first. - Scopes and settings are organised in a tree-like structure within a single enum ``JvmSettings``. - The root scope is "dataverse". - All sub-scopes are below that. -- Scopes are parted by singular dots. -- A scope may be a placeholder, filled with a variable during lookup. (Named object mapping) +- Scopes are separated by dots (periods). +- A scope may be a placeholder, filled with a variable during lookup. (Named object mapping.) Any consumer of the setting can choose to use one of the fluent ``lookup()`` methods, which hides away alias handling, -conversion etc from consuming code. See also the detailed JavaDoc for these methods. - +conversion etc from consuming code. See also the detailed Javadoc for these methods. Moving or Replacing a JVM Setting ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/sphinx-guides/source/developers/testing.rst b/doc/sphinx-guides/source/developers/testing.rst index 4a09dcf864a..4b3d5fd0a55 100755 --- a/doc/sphinx-guides/source/developers/testing.rst +++ b/doc/sphinx-guides/source/developers/testing.rst @@ -86,7 +86,7 @@ Our codebase provides little helpers to ease dealing with state during tests. Some tests might need to change something which should be restored after the test ran. For unit tests, the most interesting part is to set a JVM setting just for the current test. -Please use ``@JvmSetting(key = JvmSettings.XXX, value = "")`` annotation on a test method or +Please use the ``@JvmSetting(key = JvmSettings.XXX, value = "")`` annotation on a test method or a test class to set and clear the property automatically. To set arbitrary system properties for the current test, a similar extension