3.10 Better Practice: Replace This With That

A list of things to replace by better practice, for people and for AI coding assistants. Each item shows the code to look for, what to write instead, and why.

  • Part 1 is for code that does not use mConfig yet: boilerplate you can delete.
  • Part 2 is for code that uses mConfig, but in a way that works against it.

The code to copy is in examples/snippets.md ("templates" below); names and settings are in the Snippets Reference.

Part 1: Replace your own boilerplate with mConfig

1.1 Loading a properties file by hand

Instead of:

Properties defaults = new Properties();
try (InputStream in = getClass().getClassLoader().getResourceAsStream("defaultconfig.properties"))
    {
    defaults.load(in);
    }
catch (IOException e)
    {
    e.printStackTrace();
    }

Do this: put the file into src/main/resources/.config/<company>/<app>/network.properties and read through mConfig.

Configuration net = factory.getConfig("network");

Why: mConfig finds defaults in the JAR by itself and layers the files of the host, the user and the environment on top. The loading block goes away entirely. Template: "Bootstrap".

1.2 A hand-written list of places to look

Instead of:

File file = new File(System.getProperty("user.home"), ".myapp/config.properties");
if (!file.exists())
    { file = new File("/etc/myapp/config.properties"); }

Do this: nothing. The search list is built in.

Configuration cfg = factory.getConfig("config");

Why: mConfig knows the standard locations of each operating system (~/.config, /etc, %APPDATA%, %PROGRAMDATA%, the registry, …) and their order of precedence. mconfig <company>:<app> search-paths lists them.

1.3 Detecting the operating system to find the configuration directory

Instead of:

String os = System.getProperty("os.name").toLowerCase();
Path dir = os.contains("win") ? Paths.get(System.getenv("APPDATA"), "MyApp")
                              : Paths.get(System.getProperty("user.home"), ".config", "myapp");

Do this: for reading, nothing (see 1.2). For a directory to write your own files to:

Path dir = ConfigUtil.whereToPutMyFiles(factory, ConfigScope.USER, true);

Why: the rules differ per platform and change over time; mConfig keeps them in one place.

1.4 Reading environment variables or system properties directly

Instead of:

String host = System.getenv("MYAPP_HOST");
int    port = Integer.parseInt(System.getProperty("myapp.port", "8080"));

Do this: add mconfigsourceenvvar (part of mconfigstandard) and read the configuration.

String  host = net.getString("server/host");
Integer port = net.getInteger("server/port");

Why: the variable MYAPP_NETWORK_SERVER_HOST then overrides the files without any code, the default lives in the schema, and the tool can show where a value came from. Template: "Environment variables".

1.5 Defaults and validation as if chains

Instead of:

String value = props.getProperty("port");
int port = (value == null) ? 8080 : Integer.parseInt(value);
if (port < 1 || port > 65535)
    { throw new IllegalArgumentException("port out of range"); }

Do this: declare it once in network.mconfig-schema.json, then read it.

[ { "KEY": "server/port", "TYPE": "NUMBER", "DEFAULT": 8080, "PATTERN": "uint16" } ]
Integer port = net.getInteger("server/port");

Why: name, type, limits, default and description sit in one place, apply wherever the value is read, and can be turned into documentation. Template: "Defaults: schema and resource file".

1.6 A file watcher or a restart to pick up changes

Instead of:

WatchService watcher = FileSystems.getDefault().newWatchService();
configDir.register(watcher, StandardWatchEventKinds.ENTRY_MODIFY);
// ... a thread that waits, reloads the file and swaps the values ...

Do this: read the value when you need it; subscribe only if you must react.

net.subscribeToUpdates(location -> connectionPool.resize(net.getInteger("pool/size")));

Why: mConfig checks its sources for changes (every UPDATE_CHECK_FREQUENCY_MS) and the next read returns the new value. Template: "Hot reload".

1.7 Passwords as String

Instead of:

String password = props.getProperty("db.password");
log.debug("connecting with {}", props);

Do this: mark the entry with "SECRET": true in the schema, then:

SecretValue password = cfg.getSecret("db/password");

Why: a SecretValue shows as [REDACTED] in logs and toString(), stays out of exports, and can be wiped with erase(). Template: "Secrets".

1.8 Redirecting configuration paths for tests by hand

Instead of:

System.setProperty("user.home", tempDir.toString());   // and hope nothing else reads it

Do this:

ConfigFactoryBuilder builder = ConfigFactoryBuilder.create("ACME", "demoApp");
builder.setTestMode(true);
builder.setTestConfigPaths(ConfigScope.USER, List.of(tempDir.toString()));

Why: test mode keeps tests away from the real configuration of the machine and the user, without changing production code. Template: "Tests"; details: Test Mode.

Part 2: If you already use mConfig, do it this way

2.1 A default at the call site

Instead of:

Integer port = cfg.getInteger("server/port");
if (port == null)
    { port = 8080; }

Do this: declare "DEFAULT": 8080 in the schema.

Integer port = cfg.getInteger("server/port");

Why: a default at the call site is invisible, unvalidated and undocumented, and the second place that reads the key will use a different one. With the default settings a missing value throws ConfigException anyway, so the null check is dead code.

2.2 Parsing or validating by hand

Instead of:

int port = Integer.parseInt(cfg.getString("server/port"));

Do this:

Integer port = cfg.getInteger("server/port");

Why: the typed getters convert, and TYPE and PATTERN in the schema have already checked the value.

2.3 Copying values into fields at startup

Instead of:

this.port = cfg.getInteger("server/port");   // in the constructor, used for the lifetime

Do this: keep the Configuration and read on use, or subscribe to updates (1.6).

int port() { return cfg.getInteger("server/port"); }

Why: a copy never changes; hot reload does nothing for it.

2.4 A factory per lookup

Instead of:

Configuration c = ConfigFactoryBuilder.create("ACME", "demoApp").build().getConfig("network");

Do this: build one ConfigFactory for the application, share it, close it on shutdown.

Why: every factory scans the search locations again and owns watcher threads; a factory that is never closed leaks them.

2.5 A secret read as a string, or marked the wrong way

Instead of:

String password = cfg.getString("db/password");
{ "KEY": "db/password", "TYPE": "STRING", "FLAGS": ["SECRET"] }

Do this:

{ "KEY": "db/password", "TYPE": "STRING", "SECRET": true }
SecretValue password = cfg.getSecret("db/password");

Why: "FLAGS": ["SECRET"] is accepted (with a WARNING) but protects nothing; only "SECRET": true does. And a String cannot be wiped and ends up in a log line sooner or later.

2.6 A dot as separator in hierarchical keys

Instead of:

cfg.getString("server.host");   // against a JSON, YAML or TOML file with nested "server"

Do this:

cfg.getString("server/host");

Why: the separator is /. A dot is part of the key; in flat formats such as .properties the key server.host is one literal name.

2.7 Chaining off setTestMode()

Instead of:

ConfigFactory factory = ConfigFactoryBuilder.create("ACME", "demoApp").setTestMode(true).build();

Do this:

ConfigFactoryBuilder builder = ConfigFactoryBuilder.create("ACME", "demoApp");
builder.setTestMode(true);
ConfigFactory factory = builder.build();

Why: setTestMode(), setTestConfigPaths() and setTestParameters() return void; the chained form does not compile. Only the setFeature(...) family, setSchemas(), addSource() and addSecretsProvider() return the builder.

2.8 Reading the environment next to mConfig

Instead of:

String host = System.getenv("DEMOAPP_NETWORK_SERVER_HOST");
if (host == null)
    { host = cfg.getString("server/host"); }

Do this:

String host = cfg.getString("server/host");

Why: with mconfigsourceenvvar the variable already arrives in the SESSION scope and overrides the files. Your own precedence logic duplicates the hierarchy and hides the origin of the value.

2.9 Your own override or fallback logic

Instead of:

String value = overrides.containsKey(key) ? overrides.get(key) : cfg.getString(key);

Do this:

cfg.put(key, value, ConfigScope.RUNTIME);

Why: RUNTIME is the scope for in-memory overrides by your own code; it wins over everything except POLICY. Fallback between scopes is built in (FALLBACKS_ACROSS_SCOPES). The ConfigUtil.withOverrides() view is for cases where the configuration must not be changed.

2.10 Packing a single JAR with jar-with-dependencies

Instead of:

<descriptorRef>jar-with-dependencies</descriptorRef>

Do this: use a packaging that merges the META-INF/services files (the merging assembly descriptor, shade's ServicesResourceTransformer, or Shadow's mergeServiceFiles()).

Why: that descriptor keeps one file per service interface, so storages and formats go missing; build() fails with JAVA_SERVICE_CONFIGURATION_ERROR, or sources are lost without notice. Template: "Dependencies"; details: Packaging as a single JAR.

2.11 Library settings in the global mconfig.properties

Instead of: src/main/resources/.config/metabit/mConfig/mconfig.properties

Do this: src/main/resources/.config/<company>/<app>/mconfig.properties, or setFeature(...) in code.

Why: the global file is deprecated and removed before 0.9.0; a component configures the library for itself only. Features marked CODE_ONLY can be set in code only.

2.12 POLICY locations registered by the application

Instead of:

builder.setFeature(ConfigFeature.ADDITIONAL_RUNTIME_DIRECTORIES, List.of("POLICY:/opt/myapp/policy"));

Do this: leave POLICY to the administrator's locations (Group Policy, enforced settings). Use HOST or APPLICATION for what the application ships.

Why: POLICY overrides everything, so an application must not grant it to itself. Outside test mode such a location fails unless ALLOW_APPLICATION_POLICY_LOCATIONS is set in code.

2.13 A version copied from documentation

Instead of: copying <version>${mconfig.version}</version>, or a version number from an example, into a build file.

Do this: take the version the project already uses (its pom.xml, build.gradle, or the local repository). If none can be found, ask.

Why: examples age; a placeholder without a definition does not build.

Settings that replace manual code

Instead of writing Set
checks for keys the schema does not know SCHEMA_STRICT_MODE=true
null handling for missing values schema DEFAULT; EXCEPTION_ON_MISSING_ENTRY decides between exception and null
loops over scopes for reading or writing FALLBACKS_ACROSS_SCOPES, WRITE_FALLBACK_ACROSS_SCOPES
probing file formats in a fixed order FILE_FORMAT_READING_PRIORITIES, FILE_FORMAT_WRITING_PRIORITIES

All settings: Config Features.