Partial modules
A composed module reuses parent modules that are already built. Some modules, though, need another module that they should not build themselves, such as a data source shared by the whole application. A partial module declares that need, and leaves it to the module that composes it.
Requiring a module
Mark a @DIModule supertype with @DIModule.Required to require it rather than provide it:
@DIModule
interface DatabaseModule {
val dataSource: DataSource
}
@DIModule
interface MigrationModule : @DIModule.Required DatabaseModule { (1)
val migrator: Migrator
}
@DIModule
interface UsersModule : @DIModule.Required DatabaseModule {
fun usersRepository(): UsersRepository
}
| 1 | MigrationModule needs a dataSource, but does not bind it. |
A module with a required supertype is partial.
It is still a DatabaseModule, so its bindings can read dataSource like any other member.
Building a part
Next to its usual generated code, a partial module gets a <Module>Part class, which holds a binding for each member it provides:
public class MigrationModulePart {
public constructor(migrator: Binding<MigrationModule, Unit, Migrator>)
}
You build a part like a module, binding only what it provides:
val migration = MigrationModulePart(
migrator = Binding.single { Migrator(dataSource) }, (1)
)
| 1 | dataSource belongs to the required DatabaseModule: it is read from the module that composes the part. |
A part is not a module: it does not implement MigrationModule, since nothing in it could answer for dataSource.
Its properties are reserved to generated code.
Composing partial modules
A composed module takes a part in place of a built module for each partial parent, next to a parent that provides what the parts require:
@DIModule(composed = true)
interface AppModule : DatabaseModule, MigrationModule, UsersModule
val app = AppModule(
databaseModule = DatabaseModule(dataSource = Binding.single { HikariDataSource(config) }),
migrationModule = migration, (1)
usersModule = UsersModulePart(usersRepository = Binding.single { SqlUsersRepository(dataSource) }),
)
| 1 | A MigrationModulePart, not a MigrationModule. |
MigrationModule and UsersModule both reach DatabaseModule, but only DatabaseModule itself provides it.
There is a single dataSource, and both app.migrator and app.usersRepository() use it.
Each module gets its own bindings
A part is a recipe.
Every module it is composed into gets its own copy of its bindings, so that each one builds its own single instances against its own required members:
val prod = AppModule(prodDatabase, migration, users)
val test = AppModule(testDatabase, migration, users)
prod.migrator.dataSource // prodDatabase's data source
test.migrator.dataSource // testDatabase's data source
The parents that are full modules, such as prodDatabase, are shared as with any composition.
Providing parents in a partial module
A partial module may also provide parents of its own:
@DIModule
interface CacheModule {
val cache: Cache
}
@DIModule(composed = true)
interface ProfilesModule : @DIModule.Required DatabaseModule, CacheModule {
fun profiles(): ProfileRepository
}
Its part then binds the members of CacheModule too:
val profiles = ProfilesModulePart(
cache = Binding.single { Cache() },
profiles = Binding.single { SqlProfileRepository(dataSource, cache) },
)
With composed = true, the part gets a second constructor, which takes the parents it provides as already-built modules:
val sharedCache = CacheModule(cache = Binding.single { Cache() })
val profiles = ProfilesModulePart(
cacheModule = sharedCache, (1)
profiles = Binding.single { SqlProfileRepository(dataSource, cache) },
)
| 1 | Shared, like the parent of any composed module: every module composing profiles uses the very same Cache as sharedCache. |
A parent given this way is already built, so its bindings cannot read what the partial module requires: cache cannot use dataSource here.
Use the first constructor when they need to.
Swapping a part
The parent-swapping copy<Module> of a composed module takes a part for each partial parent.
Each one defaults to null, which keeps that parent as it is:
val withOtherMigrations = app.copyAppModule(migrationModule = otherMigration)
val onTestDatabase = app.copyAppModule(databaseModule = testDatabase)
Since every binding of a part is read against the module that composes it, swapping the provider is enough: onTestDatabase.migrator uses the test data source.
Building a partial module on its own
A partial module keeps its full builder, which binds every member, required ones included. It builds a complete module, which is handy in tests:
val migrationModule = MigrationModule(
dataSource = Binding.value(inMemoryDataSource),
migrator = Binding.single { Migrator(dataSource) },
)
Rules
The processor rejects, at compile time:
-
@DIModule.Requiredon a supertype that is not a@DIModule; -
a partial module that requires an interface, and also provides it through another of its supertypes;
-
a composed module whose parents require an interface that none of them provides (
'MigrationModule' requires 'DatabaseModule', which no parent of 'AppModule' provides.); -
a composed module whose parents provide the same interface more than once (
Interface 'DatabaseModule' is inherited more than once, via 'PostgresModule' and 'SqliteModule'.).
A plain @DIModule, which is not composed, may extend a partial module without providing what it requires: its full builder binds every member, required ones included.
@DIModule.Required only has a meaning on a direct supertype of a @DIModule interface, and is ignored anywhere else.
| A feature library can ship its wiring as a part: see multi-module projects. |