Snippets Reference¶
A lookup page: the exact names, fields, settings and scopes to use when writing code against mConfig. It holds facts, not templates.
- Code to copy is in
examples/snippets.md
(in a source checkout:
examples/snippets.md). Its Java templates are compiled against the current API on every build. - What to replace in existing code is in Better practice: replace this with that.
Audience: developers and AI coding assistants. Where this page and the source code disagree, the code is right and this page needs fixing.
1. API contract: the exact names¶
Older documents and generated code often contain the forms in the right-hand column. Do not use those.
| Correct | Wrong or stale |
|---|---|
Configuration cfg = factory.getConfig("net"); |
Config cfg = ... (no such type) |
factory.getConfig(name) |
factory.getConfiguration(name) (does not exist) |
cfg.put(key, value) / cfg.put(key, value, scope) |
cfg.set(key, value) (does not exist) |
ConfigFactoryBuilder.create(org, app) |
new ConfigFactoryBuilder(...) (it is an interface) |
builder.setTestMode(true); returns void |
.setTestMode(true).build() (will not compile) |
builder.setTestConfigPaths(scope, list); returns void |
chaining off it (will not compile) |
builder.setFeature(...) returns the builder, chainable |
|
cfg.getSecret(key) returns a SecretValue |
casting getEntry(...) to SecretValue |
secret.getValue() (byte[]) / getChars(), then erase() |
secret.clearValue() (does not exist) |
ConfigSchema, SCHEMA_*, *.mconfig-schema.json |
ConfigScheme, SCHEME_* |
"SECRET": true in the schema entry |
a "Secret" entry type; "FLAGS": ["SECRET"] |
Other hard facts:
- The key separator is
/for hierarchical formats:cfg.getString("server/host"). Flat formats (.properties) keep dotted keys literal:cfg.getString("db.password"). - Typed getters return boxed types (
Integer,Boolean,Double), so they can benullwhenEXCEPTION_ON_MISSING_ENTRYis turned off. ConfigExceptionis unchecked;ConfigCheckedExceptionis checked.getConfig(String)throws the unchecked one.getConfig(String, ConfigSchema),flush(),reload()andsetTestConfigPaths()throw the checked one.ConfigFactory.close()is declared withoutthrows, so try-with-resources is clean.ConfigurationinheritsAutoCloseable.close() throws Exception; let the factory own the lifecycle instead of wrapping aConfigurationin try-with-resources.- One
ConfigFactoryper application. It owns the file watchers, caches and background threads;close()releases them. - Never provide defaults at the call site. They belong in a
*.mconfig-schema.jsonor aPRODUCT-scope resource file. - Dependency versions: read the version from the project's own build file or the local
repository. Do not copy a version or a
${mconfig.version}placeholder from documentation.
2. Schema fields and gotchas¶
A schema is a JSON file named <configName>.mconfig-schema.json, placed under
.config/<company>/<app>/ on the classpath, or in the OS schema directories
(/etc/mconfig/schemas, ~/.config/mconfig/schemas, %PROGRAMDATA%\mconfig\schemas, …).
It is found automatically. A complete example is in the
templates;
the full description is in Configuration Schemas.
| Field | Meaning |
|---|---|
KEY |
the key, with / as separator |
TYPE |
STRING, NUMBER, BOOLEAN, BYTES, MULTIPLE_STRINGS, ENUM, ENUM_SET, URI, FILEPATH, DATE, TIME, DATETIME, DURATION |
DEFAULT |
the default value; any JSON type |
DESCRIPTION |
text for documentation and tools |
PATTERN |
a range, an enumeration, a named validator (e.g. uint16) or a regular expression |
ARITY |
how many values the entry may hold |
SECRET |
true marks the entry as a secret |
MANDATORY |
the entry must have a value |
FLAGS |
list of flags; only MANDATORY is acted upon today |
WRITE_SCOPE |
the scope a put() without scope argument writes to |
Gotchas that cost real time:
- The file is an array of entry objects, each with its own
KEY. An object keyed by configuration key parses to an empty schema, without an error. - Field names are case-insensitive, by convention UPPER CASE.
DEFAULTaccepts any JSON type:"DEFAULT": 8080,"DEFAULT": falseand"DEFAULT": "8080"all work; numbers and booleans are read as their text form. A JSON array is joined into a comma-separated value.- Mark secrets with
"SECRET": true, and only that."FLAGS": ["SECRET"]parses (since 0.8.15 with a WARNING at schema load) but does not mark the entry secret: no redaction, noSecretValue, no wiping. - The flags
READ_ONLY,WRITE_ONLYandSENSITIVEare parsed and kept, but not enforced yet; loading a schema that uses them logs a WARNING. ALLOW_LOCAL_SCHEMA_OVERRIDE=falselocks an application to its bundled schema. The feature is deprecated since 0.8.17 and replaced in 0.9.0 by an allowlist of schema sources; it keeps working until then.- Schemas stay in force in test mode.
3. Strictness: choosing the failure mode¶
Set with ConfigFactoryBuilder.setFeature(...); all settings are described in
Config Features.
| Feature | Default | Effect |
|---|---|---|
EXCEPTION_ON_MISSING_ENTRY |
true |
a key with neither value nor default throws ConfigException; false returns null |
EXCEPTION_WHEN_CONFIGURATION_NOT_FOUND |
false |
true: a missing configuration as a whole throws |
SCHEMA_STRICT_MODE |
false |
true: keys the schema does not declare are rejected |
FALLBACKS_ACROSS_SCOPES |
true |
a lookup continues into more general scopes; false restricts the fallback to PRODUCT |
WRITE_FALLBACK_ACROSS_SCOPES |
false |
true: a write may fall back to a more specific scope |
- Schema
DEFAULTvalues apply in either mode;nullonly comes back for a key with no value and no default. DEFAULT_ON_MISSING_ENTRYis deprecated since 0.8.17: it was never evaluated, and setting it has no effect. Do not generate it.- Do not make up for a lenient setting with
if (v == null) v = FALLBACK;at the call site. Declare the default in the schema.
4. Library self-configuration¶
Library settings can be shipped as a classpath resource of your component instead of code. The file applies only to factories created for that company and application; values set in code win.
src/main/resources/.config/<company>/<app>/mconfig.properties
EVENTS_DETAIL_LEVEL=FAILURES_ONLY
UPDATE_CHECK_FREQUENCY_MS=2000
- Features marked
CODE_ONLY(ALLOW_MCONFIG_RUNTIME_SETTINGS,ENABLE_SELF_CONFIGURATION,ALLOW_APPLICATION_POLICY_LOCATIONS, …) are ignored in this file, with a warning; set them in code. See who may set a feature. - Do not use the global
.config/metabit/mConfig/mconfig.properties: it is deprecated and will be removed before 0.9.0. - Per-module settings go into their own file in the same directory (
vault.properties,aws.properties,kubernetes.properties), which keeps the modules apart. ENABLE_SELF_CONFIGURATION=false, set in code, switches classpath self-configuration off where the classpath is not fully controlled.
5. Scope reference¶
Resolution runs from the most specific scope down; the topmost layer holding the key wins. Within one scope, a location later in the search list overrides an earlier one. Details: Scopes, Priorities and Hierarchies.
| Priority | Scope | Typical source |
|---|---|---|
| 1 (top) | POLICY |
Group Policy / enforced admin settings |
| 2 | RUNTIME |
In-memory, set by your own code |
| 3 | SESSION |
Environment variables, CLI arguments |
| 4 | USER |
~/.config/, %APPDATA% |
| 5 | APPLICATION |
Installation directory, portable root |
| 6 | HOST |
/etc/opt/<company>/<app>/, %PROGRAMDATA%\<company>\<app> |
| 7 | CLUSTER |
ZooKeeper, Kubernetes |
| 8 | CLOUD |
Cross-cluster shared configuration |
| 9 | ORGANIZATION |
Licensee / tenant settings |
| 10 | PRODUCT |
Schema defaults, JAR resources |
- Do not register
POLICY-scope locations from application code; outside test mode they fail unlessALLOW_APPLICATION_POLICY_LOCATIONSis set in code. - Environment variables are read-only: a
put(..., ConfigScope.SESSION)against them is refused.
6. Module selection¶
Artifact IDs are lower case; the groupId is org.metabit.platform.support.config.
| Bundle | Use when |
|---|---|
mconfigbasic |
lightweight, purely file-based Java: core, schema, secrets, filesystem, JAR, .properties, util |
mconfigstandard |
cloud-native: adds environment variables, JSON/YAML/TOML (Jackson), INI, slf4j, the Windows registry |
Vault, AWS Secrets Manager and Kubernetes are opt-in storage modules, in neither bundle. They are not secrets providers; mConfig ships no secrets provider.
Packing everything into a single JAR must merge the META-INF/services files; never use the
assembly descriptor jar-with-dependencies. See
Packaging as a single JAR.
Related: Getting Started · Examples · AI Guidance