IoC ConfigUser Guide
Overview
IoC Config
is an IoC library for providing injectable config values.
Config values are essentially constants, but their value can be overridden on registry startup.
This makes them great for use by 3rd party libraries. The libraries can set sensible default values, and applications may then optionally override them.
Install
Install IoC Config
with the Fantom Repository Manager ( fanr ):
C:\> fanr install -r http://repo.status302.com/fanr/ afIocConfig
To use in a Fantom project, add a dependency to build.fan
:
depends = ["sys 1.0", ..., "afIocConfig 1.0+"]
Documentation
Full API & fandocs are available on the Status302 repository.
Quick Start
1). Create a text file called Example.fan
:
using afIoc using afIocConfig class Example { @Config { id="my.number" } @Inject Int? myNumber Void print() { echo("My number is ${myNumber}") } } class AppModule { static Void bind(ServiceBinder binder) { binder.bindImpl(Example#) } @Contribute { serviceType=ApplicationDefaults# } static Void contributeApplicationDefaults(Configuration config) { // applications override factory defaults config["my.number"] = "69" } } class OtherModule { @Contribute { serviceType=FactoryDefaults# } static Void contributeFactoryDefaults(Configuration config) { // 3rd party libraries set factory defaults config["my.number"] = "666" } } // ---- Standard Support Class ---- class Main { Void main() { registry := RegistryBuilder().addModules([AppModule#, OtherModule#, IocConfigModule#]).build.startup example := (Example) registry.dependencyByType(Example#) example.print() // --> 69 registry.shutdown() } }
2). Run Example.fan
as a Fantom script from the command line:
C:\> fan Example.fan ... IoC started up in 507ms My number is 69
Usage
All config values are referenced by a unique config id
(a string). This id is used to set a factory default value, application values and to inject the value in to a service.
Start by setting a default value by contributing to the FactoryDefaults service in your AppModule
:
@Contribute { serviceType=FactoryDefaults# } static Void contributeFactoryDefaults(Configuration config) { config["configId"] = "666" }
Config's may take any value as long as it is immutable (think const
class).
Anyone may then easily override your value by contributing to the ApplicationDefaults service:
@Contribute { serviceType=ApplicationDefaults# } static Void contributeApplicationDefaults(Configuration config) { config["configId"] = "69" }
Config values may be injected into your service by using the @Config
facet with the standard IoC @Inject
facet:
class MyService { @Config { id="configId" } @Inject File configValue ... }
Note that when config values are injected, they are Type coerced to the field type. That means you can contribute Str
or Uri
values and inject it as a File
.
If an id
is not supplied in @Config
then it is inferred from the field name and containing pod. For example, if Type MongoMgr
in pod myMongo
looked like:
class MongoMgr { @Config @Inject Url mongoUrl ... }
Then the id myMongo.mongoUrl
would be looked up. Failing that, a fallback to just mongoUrl
would be attempted.
Release Notes
v1.1.12
- Bug: Bodged release - updated to IoC 1.7.2.
v1.0.10
- Chg: Updated to IoC 1.7.0.
v1.0.8
- Chg: Updated to IoC 1.6.4 and removed dependencies on depreacted classes / methods.
v1.0.6
- New: Unknown config ids are inferred from the field and pod name.
- Chg: Updated to IoC 1.6.0.
- Chg: Replaced
ConcurrentState
usage with newconst TypeCoercer
.
v1.0.4
- Chg: Exposed the underlying config map in
IocConfigSource
.
v1.0.2
- Chg: Updated to IoC 1.5.2.
- Bug:
IocConfigSource.get()
threw an Err ifcoerceTo
type wasnull
.
v1.0.0
- New:
@Config
has a defaultid
of the field name it is being injected into. - New:
ConfigProvider
can be configured with bespokeConfig
facets. (As used by BedSheet.) - Chg: Removed
ConfigSource.getCoerced()
in favour of a default value inConfigSource.get()
. - Chg: Upgraded to IoC 1.5.0.
v0.0.2
- New: Preview Release