2.0 Scopes¶
mConfig uses the concept of hierarchical Scopes to manage configuration precedence. This is a core API-level concept that determines which configuration values "win" when the same key is defined in multiple places.
You can think of it as a layered fall-back hierarchy.
The Scope Hierarchy¶
The software may have generic defaults, which can be overridden by settings of the individual local installation. These, in turn, can be overridden by user-based settings, session-specific environment variables, or even enforced by system policies.
Scope order (from lowest to highest priority):
PRODUCT → ORGANIZATION → CLOUD → CLUSTER → HOST → APPLICATION → USER → SESSION → RUNTIME → POLICY
| Priority | Scope | Intended Use | Typical Sources |
|---|---|---|---|
| 10 | PRODUCT | Defaults shipped with the software. | ConfigSchema defaults, JAR resources |
| 9 | ORGANIZATION | Company-level defaults and licensing. | Registry, network services |
| 8 | CLOUD | Cloud-based configurations, shared across clusters. | HashiCorp Vault, AWS Secrets Manager, network services |
| 7 | CLUSTER | Cluster-wide settings. | Apache ZooKeeper, Kubernetes ConfigMaps and Secrets, network services |
| 6 | HOST | System-wide settings for one host. | /etc/opt/<company>/<app>/, %ProgramData%\<company>\<app>, Registry |
| 5 | APPLICATION | Installation-specific settings (portable/side-by-side). | Filesystem near the binary |
| 4 | USER | Per-user overrides and preferences. | ~/.config/, %AppData%, Registry |
| 3 | SESSION | Shell/session overrides. | Environment variables, command-line |
| 2 | RUNTIME | In-memory changes during program execution. | RAM layer (config.put(...)) |
| 1 | POLICY | Enforced overrides (highest priority). | GPO, Registry, policy files |
Why Scopes Matter¶
Understanding scopes is essential for both developing and deploying applications with mConfig:
- For Developers: Scopes allow you to provide sensible defaults in the
PRODUCTscope while allowing any value to be overridden by the environment or the user without changing your code. - For System Administrators: Scopes like
HOSTandPOLICYprovide a standard way to enforce settings across an entire machine or organization, ensuring security and compliance. - For Users: The
USERscope ensures that personal preferences are preserved regardless of system-wide updates or changes. - For CI/CD and Testing:
SESSIONandRUNTIMEscopes are perfect for passing temporary configuration or mocking settings during automated tests.
Resolution Logic¶
When you request a configuration value, mConfig searches through the layers from the highest priority scope down to the lowest. The first scope that contains the requested key provides the value.
Within the same scope, mConfig may have multiple sources (e.g., several directories in the HOST scope). In this case, the order is determined by the Search List. See Priorities and Hierarchies for more details on how ties are broken and how search paths are constructed.
Calling code can also limit which scopes are considered during resolution, allowing for fine-grained control over configuration precedence.