3.9 Utilities and Adapters¶
The mConfigUtil module provides specialized Configuration implementations (adapters) and static utility methods to bridge existing Java structures with the mConfig ecosystem.
3.9.1 Core Adapters¶
These classes allow existing configuration sources to be viewed through the Configuration interface.
3.9.1.1 PropertiesConfiguration¶
Used for adapting legacy code step-by-step. It allows programmatically generated java.util.Properties to be integrated into the unified mConfig structure.
- Note: This adapter provides almost none of the advanced features mConfig supplies (like multi-tier resolution or automatic schema discovery).
- Recommendation: Consider loading properties via mConfig itself by adding paths to ConfigFeature.ADDITIONAL_USER_DIRECTORIES.
3.9.1.2 OverridingConfiguration¶
Provides an immutable view that overlays a Map<String, Object> on top of an existing Configuration. Overrides take precedence.
- Note: This is intended for temporary, in-memory overlays.
- Recommendation: For most use cases, prefer using Configuration.put*(key, value, ConfigScope.RUNTIME). The RUNTIME scope is specifically designed for temporary overrides that are not persisted.
3.9.1.3 RemappedConfiguration¶
Remaps keys matching a newPrefix to an oldPrefix for lookup in an underlying source configuration. This is useful for maintaining backward compatibility or redirecting configuration branches.
3.9.1.4 What the adapters are, and what they are not¶
The adapters help with transition and adoption. They are views for reading, not a second facade;
for anything beyond that, use the mConfig Configuration itself.
- Read-only. Every
put(...)throwsConfigExceptionwith reasonNOT_WRITEABLE, with or without a scope;isWriteable()isfalse. (Up to 0.8.16,RemappedConfigurationwrote through for someputvariants.) - No cursor, and the schema cannot be set on a view:
getConfigCursor()andsetConfigSchema()throwUnsupportedOperationException. RemappedConfigurationandOverridingConfigurationshow their source as it is. Values, entries, the schema,getSourceLocations(),isClosed()and update subscriptions are those of the configuration behind the view. A secret is handed on as aSecretValue. An entry reports the key, scope and location it has in the source; the schema of a remapped view knows the keys under the old prefix.- A remapped view hides what the source has under the new prefix. Every key starting with
newPrefixis read fromoldPrefix, so a key the source itself has undernewPrefixcannot be read through the view; a listing still names it once, since the view shows both under the same name. Choose anewPrefixthe source does not use. - Overrides are checked when read. An override that cannot be converted to the requested type
throws
ConfigException(CONVERSION_FAILURE); one that does not match the schema of the parent throwsConfigException(ARGUMENT_INVALID). The value is not put into the message. An entry from the overrides has no scope and no location (null): it was not read from anywhere. PropertiesConfigurationbehaves like thePropertiesbehind it. A key that is not there givesnull, no exception. A value that cannot be converted to the requested type throwsConfigException(CONVERSION_FAILURE), as parsing the string in plain Java would (up to 0.8.16:null).getSecret()returns the property as aSecretValue(up to 0.8.16: alwaysnull); in thePropertiesit stays a plain, unprotected String, so the first such access is logged at INFO level, once per JVM, through the JDK'sSystem.LoggernamedmConfig. Read secrets through mConfig itself. No schema, no locations, no update notifications.
3.9.2 Scope-Restricted Reads¶
All three adapter classes implement the full Configuration interface, including the
scope-aware read methods. Scope restriction is per-call — there is no per-instance
scope state — so the same adapter instance can safely serve call sites that need
different scope views.
The adapters do not treat the scopes alike:
| Adapter | Scope-restricted read |
|---|---|
RemappedConfiguration |
passed on to the source: only the given scopes are read |
OverridingConfiguration |
an override applies whatever the scopes; keys that are not overridden are read from the parent in the given scopes |
PropertiesConfiguration |
the scopes are ignored: Properties have none |
To read a value only from specific scopes, use getConfigEntryFromFullKey(key, scopes):
EnumSet<ConfigScope> localScopes = EnumSet.of(ConfigScope.PRODUCT, ConfigScope.HOST);
Configuration remapped = ConfigUtil.remapped(base, "old.prefix", "new.prefix");
ConfigEntry entry = remapped.getConfigEntryFromFullKey("my.key", localScopes);
String value = (entry != null) ? entry.getValueAsString() : null;
To enumerate all keys visible in specific scopes:
Set<String> keys = config.getAllConfigurationKeysFlattened(localScopes);
3.9.3 ConfigUtil Entry Point¶
The ConfigUtil class provides convenient factory methods for the adapters above, along with other helper functions:
- Factory Methods:
ConfigUtil.fromProperties(Properties props)ConfigUtil.withOverrides(Configuration parent, Map<String, Object> overrides)ConfigUtil.remapped(Configuration source, String oldPrefix, String newPrefix)
- Path Discovery:
ConfigUtil.whereToPutMyFiles(...): Helps find writable configuration paths for a given scope.ConfigUtil.printConfigPaths(...): Prints the discovered configuration search paths for debugging.
- Property Extraction:
ConfigUtil.copyPrefixedEntriesToJavaProperties(...): Exports a subset of a configuration to aPropertiesobject.ConfigUtil.copySchemeDefinedEntriesToJavaProperties(...): Exports all entries defined by the configuration schema.
- Quick Configuration:
ConfigUtil.quickConfig(...): A one-liner for bootstrapping a standard configuration for simple applications.
3.9.4 Usage¶
Add the following dependency to your project:
<dependency>
<groupId>org.metabit.platform.support.config</groupId>
<artifactId>mConfigUtil</artifactId>
<version>${mconfig.version}</version>
</dependency>
JPMS module name:
requires metabit.mconfig.util;