1. Pods
  2. AF-IOC 1.1.0
  3. User Guide

AF-IOCUser Guide

Overview

IoC is an Inversion of Control (IoC) container, or Dependency Injection (DI) framework, based on the most excellent Tapestry 5 IoC for Java. Above and beyond all else, this IoC offers:

  • distributed service configuration between pods and modules
  • extensive error reporting
  • lazy(ish) service loading
  • case insensitivity

Quick Start

class Main {
  static Void main(Str[] args) {
    registry := IocService([MyModule#]).start.registry

    MyService1 test1 := registry.serviceById("myservice1")

    MyService1 test2 := registry.dependencyByType(MyService1#)

    MyService1 test3 := registry.autobuild(MyService1#)

    MyService1 test4 := registry.injectIntoFields(MyService1())

    Service.find(IocService#).uninstall
  }
}

class MyService1 {
  @Inject
  MyService2? service2
}

class MyService2 {
  Str kick := "Ass!"
}

class MyModule {
  static Void bind(ServiceBinder binder) {
    binder.bindImpl(MyService1#)
    binder.bindImpl(MyService2#)
  }
}

Terminology

IoC distinguishes between Services and Dependencies.

A service is a singleton class of which there is only one instance (or one per thread). Each service is identified by a unique ID (usually the unqualified class name) and may, or may not, be represented by a Mixin. Services are managed by IoC and must be defined by a module. Services may solicit configuration contributed by other modules.

A dependency is any class or object that another class depends on. A dependency may or may not be a service. For example, a class may depend on having a field Int maxNoOfThreads but that Int isn't a service. Non service dependencies may be managed by user defined dependency providers.

A contribution is a means to configure a service.

A module is a class where services and contributions are defined.

Loading Modules

When building a registry, you declare which modules are to loaded. You may also load modules in dependant pods, in which case, each pod should have declared the following meta:

"afIoc.module" : "{qname}"

Where {qname} is a qualified type name of a module. Additional modules can be declared by the @SubModule facet.

Modules can also be loaded from index properties in a similar manner.

Defining Services

Services are defined in Module classes, where each meaningful method is static and annotated with a facet.

The exception is bind() which does not have a facet but is declared with a standard signature. The bind method is the common means to define services, examples below:

static Void bind(ServiceBinder binder) {

  // has service ID of 'MyService'
  binder.bind(MyService#, MyServiceImpl#)

  // has service ID of 'myServiceImpl'
  binder.bindImpl(MyServiceImpl#)

  // has service ID of 'elephant'
  binder.bindImpl(MyServiceImpl#).withId("elephant")
}

Modules may can also define builder methods. These are static methods annotated with the @Build facet. Here you may construct and return the service yourself. Any parameters are taken to be dependencies and are resolved as such when the method is called. For example, to manually build a service with the Id penguin:

@Build { serviceId="penguin" }
static EmailService buildStuff(EmailConfig config) {
  EmailServiceImpl(config)
}

Dependency Injection

IoC performs both ctor and field injection.

Note that under the covers, all services are resolved via their unique service ids, injection by type is merely a layer on top, added for convenience.

When IoC autobuilds a service it locates a suitable ctor. This is either the one donned with the @Inject facet or the one with the most parameters. Ctor parameters are taken to be dependencies and are resolved appropriately.

Field injection happens after the object has been created and so fields must be declared as nullable:

@Inject
MyService? myService

The exception to the rule is if you declare a serialisation ctor:

new make(|This|? f) { f?.call(this) }

On calling f all injectable fields will be set, even fields marked as const.

After object construction and field injection, any extra setup may be performed via methods annotated with @PostInjection. These methods may be of any visibility and all parameters are resolved as dependencies.

Service Scope

Services are either created once perApplication (singletons) or once perThread. Application scoped services must be defined as const. If you need mutable state in your const service, try using the ConcurrentState class.

It is illegal to attempt to inject a perThread scoped service into a perApplication scoped service.

Service Configuration

Services can solicit configuration from modules simply by declaring a list or a map in their ctor or builder method.

class Example {
  new make(Str[] mimeTypes) { ... }
  ...
}

Modules may then contribute to the Example service:

@Contribute
static Void contributeExample(OrderedConfig config) {
  config.addUnordered("text/plain")
}

The list and map types are inferred from the ctor definition and all contribution types must fit.

If the service declares a map configuration then contribution methods should take a MappedConfig object. If the map config uses Str as the key, then the created map is caseInsensitive otherwise the map is ordered.

Tips

Define one main module and declare it both the pod meta and the pod index props. Use @SubModule to reference additional dependant modules in the same pod.

If you have no say in how your classes are created (say, when you're using flux) then use the following line to inject dependencies when needed:

(Service.find(IocService#) as IocService).injectIntoFields(this)

When creating GUIs (say, with fwt) then use Registry.autobuild to create your panels, commands and other objects. These aren't services and should not be declared as such, but they do often make use of services.

IoC gives detailed error reporting should something go wrong, nevertheless should you need more, use IocHelper.debugOperation to make IoC give trace level contextual information.

Don't be scared of creating const services! Use ConcurrentState to safely store and access mutable state across thread boundaries.

Release Notes

v1.1.0

  • New: Extend IoC by defining your own DependencyProviders.
  • New: @ServiceId lets you disambiguate between different implmentations of the same service mixin.
  • New: @Autobuild injects a fresh service on every build.
  • New: Ordered configuration contributions are ordered across modules.
  • New: Services can be created even if they don't define any ctors.

v1.0.0

  • New: Added addUnorderedAll and addMappedAll to OrderedConfig and MappedConfig.
  • Chg: Multiple instances of ConcurrentState can be created with the same state class.
  • Bug: Made public the withState() and getState() methods on ConcurrentState.
  • Bug: NPE could be thrown if ctor depdendency not found.

v0.0.2

  • Preview release