env library Jetleaf
π Jetleaf Environment, Profiles & Property Resolution Subsystem
This library provides the centralized environment abstraction, multi-profile management, and hierarchical property resolution engine for the Jetleaf framework.
It encapsulates:
- Environment Abstractions: Environment, ConfigurableEnvironment,
StandardEnvironment. - Multi-Profile Management: Active profiles, default profiles, profile evaluation.
- Property Sources: PropertySource, MapPropertySource, CommandLinePropertySource.
- Property Resolvers: PropertyResolver, ConfigurablePropertyResolver, AbstractPropertyResolver.
- Type-Safe Configuration Binding: Expression evaluation and property conversion.
ποΈ Hierarchical Property Resolution Cascade
Jetleaf resolves configuration properties by cascading through ordered property sources:
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Hierarchical Property Sources (Highest to Lowest) β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β 1. Command-Line Arguments (--server.port=9090, -Dcustom=val) β
β β β
β 2. Environment Variables (SERVER_PORT=8080, JETLEAF_ACTIVE_PROFILES)β
β β β
β 3. Profile-Specific Files (application-prod.properties / .yaml) β
β β β
β 4. Default Application File (application.properties / .yaml / .json) β
β β β
β 5. Programmatic Defaults (DefaultPropertiesPropertySource) β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
π¦ Exports Categorization
π Environment Management
- Environment β read-only access to active profiles and configuration properties.
- ConfigurableEnvironment β allows mutation of active profiles and property sources.
StandardEnvironmentβ standard production environment incorporating system env and properties.- Profiles β utility for profile predicate evaluation (e.g.
dev & !cloud).
π Property Resolvers & Sources
- PropertyResolver β contract for querying string and typed properties with fallback defaults.
- PropertySource β named source of key-value property pairs.
- MapPropertySource β in-memory map backed property source.
- CommandLinePropertySource β parses
--key=valuecommand-line arguments into properties. - SimpleCommandLinePropertySource β lightweight CLI argument parser source.
- PropertySources β ordered container managing the precedence of multiple property sources.
π― Usage Example: Configuring Profiles & Reading Typed Properties
import 'package:jetleaf/env.dart';
void main() {
final env = StandardEnvironment();
// 1. Configure active environment profiles
env.setActiveProfiles(['production', 'eu-west']);
// 2. Add an in-memory property source
env.getPropertySources().addFirst(
MapPropertySource('customConfig', {
'server.host': '0.0.0.0',
'server.port': 8080,
'cache.enabled': true,
}),
);
// 3. Resolve properties with defaults
final host = env.getProperty<String>('server.host', 'localhost');
final port = env.getProperty<int>('server.port', 3000);
final isCache = env.getProperty<bool>('cache.enabled', false);
print('Server listening on: $host:$port (Cache: $isCache)');
print('Active profiles: ${env.getActiveProfiles()}');
}
Classes
- AbstractEnvironment
- Base class for creating environment implementations in Jetleaf.
- AbstractPropertyResolver
- An abstract base implementation of ConfigurablePropertyResolver that provides common functionality for resolving property placeholders, type conversion, and required property validation.
- AlphabeticalRule
- A property source ordering rule that sorts sources alphabetically by name.
- ApplicationArguments
- Defines the contract for accessing and parsing command-line arguments passed to an application.
- ApplicationConfigurationProperties
-
ConfigurationProperties is a class for defining application configuration in a typed and expressive way,
similar to defining settings in
application.yaml, but directly in Dart. - ApplicationConfigurationProperty
- A base class for defining structured and strongly typed configuration classes in the Jetleaf framework.
- BeforeRule
- Represents a reordering rule for property sources that ensures one source appears before another within a list of PropertySources.
-
CommandLinePropertySource<
T> - A base class for property sources that are backed by command line arguments.
- ComparatorRule
- A property source ordering rule that sorts sources using a custom OrderComparator.
- CompositePropertySource
- A composite implementation of ListablePropertySource that aggregates multiple PropertySource instances.
- ConfigurableEnvironment
- A configurable extension of the Environment interface that allows mutation of environment internals such as active profiles and property sources.
- ConfigurablePropertyResolver
- A specialized PropertyResolver that allows full control over property placeholder behavior and type conversion logic using a configurable ConfigurableConversionService.
- DefaultApplicationArguments
- Default implementation of ApplicationArguments that wraps command-line arguments and exposes them via a PropertySource-based backing system.
-
Env<
T> - A generic configuration property accessor for environment variables.
- Environment
- Environment Contract
- GlobalEnvironment
- A concrete implementation of AbstractEnvironment that represents the default runtime environment for most applications.
- JetleafProperty
- Base class for all Jetleaf framework configuration properties.
-
ListablePropertySource<
T> - A specialized PropertySource capable of enumerating all available property keys, allowing efficient lookup operations.
- MapPropertySource
- A PropertySource implementation backed by a Map of key-value pairs.
- MutablePropertySources
- A mutable container for managing an ordered list of PropertySource objects.
- PriorityRule
- A reordering rule for property sources based on explicit numeric priorities.
- Profiles
- A profile predicate used by Environment to determine if given profile expressions match the active/default profiles.
- PropertyResolver
- A service abstraction for resolving application properties and configuration values.
-
PropertySource<
T> - A base abstraction representing a source of key-value properties, such as maps, environment variables, or configuration files.
- PropertySourceOrderRule
-
Defines a user-supplied rule that determines the ordering of
`PropertySource`objects within Jetleafβs configuration system. - PropertySources
- A collection of PropertySources that provides lookup and stream support.
- PropertySourcesPropertyResolver
- A concrete implementation of AbstractPropertyResolver that retrieves property values from a collection of PropertySources managed by a MutablePropertySources container.
- SimpleCommandLinePropertySource
-
A CommandLinePropertySource that adapts
CommandLineArgsinto a resolvable PropertySource. - SystemEnvironmentPropertySource
- A MapPropertySource that exposes system environment variables as a property source.
Mixins
- ConfigurationPropertySource
- A mixin that provides access to a globally attached Environment.
Properties
-
environmentLoggingListener
β Obs<
Map< LogLevel, String> > -
A reactive listener that holds environment-specific logging configuration.
final
Exceptions / Errors
- DartLoadingException
- Exception thrown when Dart file loading fails.
- EnvironmentParsingException
- An Exception thrown when an error occurs during environment property parsing.
- MissingRequiredEnvironmentException
- Exception thrown when a required environment variable is not found.
- MissingRequiredPropertiesException
- Exception thrown when required properties are not found.