IoC ConfigUser Guide

Overview

IocConfig 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 IocConfig with the Fantom Respository Manager:

C:\> fanr install -r http://repo.status302.com/fanr/ afIocConfig

To use in a Fantom project, add a dependency to its build.fan:

depends = ["sys 1.0", ..., "afIocConfig 1.0+"]

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(MappedConfig config) {
        // applications override factory defaults
        config["my.number"] = "69"
    }
}

class OtherModule {
    @Contribute { serviceType=FactoryDefaults# }
    static Void contributeFactoryDefaults(MappedConfig 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 1,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(MappedConfig 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(MappedConfig 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 IoC Type coerced to the field type. That means you can contribute Str or Uri values and inject it as a File.

Release Notes

v1.0.4

• Chg: Exposed the underlying config map in IocConfigSource.

v1.0.2

• Chg: Upgraded to afIoc-1.5.2.
• Bug: IocConfigSource.get() threw an Err if coerceTo type was null.

v1.0.0

• New: @Config has a default id of the field name it is being injected into.
• New: ConfigProvider can be configured with bespoke Config facets. (As used by BedSheet.)
• Chg: Removed ConfigSource.getCoerced() in favour of a default value in ConfigSource.get().
• Chg: Upgraded to afIoc-1.5.0.

v0.0.2

• New: Preview Release