5.3 AI Guidance (Notes for Code-Generating Tools)¶
We just know people will use code generators. So it's probably for the best to give the AI some hints.
This document summarizes mConfig behaviours that code generators often miss. The goal is to prevent boilerplate, duplicate logic, or incorrect assumptions.
Three companions carry the concrete material:
- Snippets Reference: the exact API names, schema fields, settings and scopes.
- examples/snippets.md: code templates to copy; the Java ones are compiled against the current API on every build.
- Better Practice: Replace This With That: what to replace, as pairs of "instead of" and "do this". Use part 1 when migrating code to mConfig, part 2 when reviewing code that uses it.
Read the documentation before reconstructing behaviour from sources¶
Before attempting to explain or reverse-engineer mConfig behaviour from library source code or JAR artifacts:
- Read the core chapters first:
- 20 Scopes and 21 How it works (10-tier scope hierarchy and architecture)
- 22 Priorities and hierarchies (Precedence rules: within a scope, later entries override earlier ones for reading)
- 15 Test mode (Isolation and runtime settings activation requirements)
- 23 Configuration schemas (Schema format, type constraints, defaults)
- 42 Logging (Available loggers and bootstrap selection)
- Search list vs. Active layers: getSearchList() returns all candidate ConfigLocations considered across all scopes and storages, including directories that do not exist yet on disk (which are retained so that lazily created configurations are detected at runtime). To find only the locations that actually exist and contributed active data layers, use configuration.getSourceLocations().
Logging and runtime debug control¶
- Runtime logging overrides are handled by mConfig core (
RuntimeConfigurator) and are only enabled if the application setALLOW_MCONFIG_RUNTIME_SETTINGStotruein code (it cannot be enabled from outside or frommconfig.properties). - Environment variables start with
MCONFIG_RUNTIME_: MCONFIG_RUNTIME_DEBUG_LEVEL= off|0, error|1, warn|2, info|3, debug|4, trace|5MCONFIG_RUNTIME_DEBUG_OUTPUT= "stderr", "stdout", "quiet", orfile:<path>(appended if present, created if missing)MCONFIG_RUNTIME_DEBUG_OUTPUTis handled internally byInternalLogger. You do not need to implement a custom logger for this.
Related docs: - mConfigSourceEnvVar README - logging
Console logging for dev/tests¶
ConsoleLogginginmConfigCoremain jar (service"console").- Production logging should use
mConfigLoggingSlf4jor the defaultNullLogging. - Enable with
ConfigFeature.LOGGING_TO_USE_IN_CONFIGLIB = "console".
Related docs: - logging
Defaults belong in resources, not in code¶
mConfigSourceJARautomatically loads defaults from resources located at.config/<company>/<app>/<config>.<ext>.- For a standard Maven layout, the default location is:
src/main/resources/.config/<company>/<app>/<config>.properties- Schemas (typed defaults and validation) live next to the config file:
src/main/resources/.config/<company>/<app>/<config>.mconfig-schema.json- Avoid manual loading of
Propertiesdefaults. mConfig already layers JAR defaults with filesystem, environment, and other sources. - Avoid null checks. mConfig has ConfigFeature flags to control behaviour, whether to throw an exception or return a default value. Prefer setting defaults as described above.
Related docs: - simple configuration loading - 3.8 code improvements - regular use
Fallbacks and conversion are built in¶
- Fallback across scopes is a first-class feature:
FALLBACKS_ACROSS_SCOPEScontrols reads (default: true)WRITE_FALLBACK_ACROSS_SCOPEScontrols writes (default: false)- Typed getters (
getInteger,getBoolean, etc.) perform conversion for you. Do not parse values manually. - Schema defaults apply automatically: a missing key with a
DEFAULTin the schema returns it. SetEXCEPTION_ON_MISSING_ENTRY=falseonly if keys with neither value nor default should returnnullinstead of throwing. Do not generateDEFAULT_ON_MISSING_ENTRY: it is deprecated and has no effect.
Related docs: - 2.5 config features - design consolidated - 3.8 code improvements
converters and mappers¶
- ConfigMapper is provided to map from and to POJOs.
- ConfigUtil.fromProperties(...) is a bridge to convert legacy
Properties. - ConfigUtil.withOverrides(...) is a bridge to merge custom maps.
- ConfigUtil.remapped(...) is a bridge to prefix sub-configs.
- See examples/configuration_views.md for more.
Overrides: use scopes, not ad-hoc logic¶
- For in-process overrides, prefer
ConfigScope.RUNTIMEviaput(...). It is the highest regular scope and overrides everything exceptPOLICY. - For environment/session overrides, use
ConfigScope.SESSION(env vars and CLI). Avoid custom precedence logic.
Related docs: - regular use - 2.1 how it works
Test Mode is a first-class feature¶
- Enable with
ConfigFactoryBuilder.setTestMode(true)or viaMCONFIG_RUNTIME_TEST_MODE=truewhenALLOW_MCONFIG_RUNTIME_SETTINGSis on. A component may also set its own test mode in its self-configuration filesrc/test/resources/.config/<company>/<app>/mconfig.properties(TEST_MODE=true); never put that intosrc/main/resources. The global.config/metabit/mConfig/mconfig.propertiesis deprecated and cannot set it (see who may set a feature). - Do not generate POLICY-scope locations (
POLICY:directory prefixes, POLICY sources): outside test mode they fail unless the application setsALLOW_APPLICATION_POLICY_LOCATIONS. - Test Mode bypasses OS paths and prefers test resources such as
src/test/resources/.config/<company>/<app>/andsrc/test/resources/config/{SCOPE}. - Test Mode can be locked down globally with
ConfigFactoryBuilder.forbidTestMode().
Related docs: - test mode - testing configuration
Prefer mConfigUtil adapters for legacy interop¶
ConfigUtil.withOverrides(...): immutable overlay; prefer over custom map merges.ConfigUtil.remapped(...): prefix remapping for sub-config views.ConfigUtil.fromProperties(...): bridge legacyPropertieswithout re-parsing.
Related docs:
- configuration views
- mConfigUtil/src/main/java/org/metabit/platform/support/config/util/ConfigUtil.java
Cloud and Secret Storages are Opt-in¶
mConfig has storage modules for cloud-native and secret configuration. They are opt-in: neither
mConfigBasic nor mConfigStandard includes them. They are storage modules, not secrets providers
(addSecretsProvider()); mConfig ships no secrets provider in this version yet. Check for 0.9.x versions regarding secrets providers.
- Vault (
mConfigSourceVault): sources default to theCLOUDscope;withScope(...)on the builder places them elsewhere. - AWS Secrets Manager (
mConfigSourceAwsSecretsManager): same;CLOUDby default. - Kubernetes (
mConfigSourceKubernetes,mConfigSourceKubernetesFabric8): ConfigMaps and Secrets; the mounted directories go into theCLUSTERscope.
An additional source registered at POLICY scope fails in productive mode unless ALLOW_APPLICATION_POLICY_LOCATIONS is set in code.
Before concluding that a source is missing or unsupported, check for these mConfigSource* modules.
Related docs: - 3.5 Handling Secrets - 26 Security Model (Secrets Concept)