Sets of members
A module can gather some of its members into a Set, such as every service that has to be started when the application starts.
You mark the members with an annotation of your own, and the processor generates a function returning all of them.
Declaring a set
A set is an annotation class annotated with @DISet, which names the type of its elements:
interface Service {
fun start()
}
@DISet(of = Service::class) (1)
annotation class Services
@DIModule(sets = [Services::class]) (2)
interface AppModule {
@Services val database: Database (3)
@Services val server: HttpServer
@Services fun scheduler(): Scheduler? = null (4)
val port: Int
}
| 1 | Every member of the Services set must be a Service. |
| 2 | The module generates a function for every set it lists in sets. |
| 3 | Database, HttpServer and Scheduler all implement Service. |
| 4 | A member of a set may be nullable: null is left out of the set. |
The processor generates an extension function named setOf followed by the name of the annotation:
public fun AppModule.setOfServices(): Set<Service>
It reads each member off the module, so the set always holds what the module’s bindings currently provide:
val app = AppModule(
database = Binding.single { Database() },
server = Binding.single { HttpServer(port) },
port = Binding.value(8080),
)
app.setOfServices().forEach { it.start() } (1)
| 1 | Starts the database and the server: scheduler() keeps its default implementation, which returns null. |
The function has the visibility of the module: an internal module gets an internal function.
What a set holds
A set holds every member of the module that carries its annotation, inherited members included, in the order the module declares them: inherited members first, in the order of the supertypes, then the module’s own.
Since the result is a Set, two members that provide the same value, or two equal values, appear in it once.
A member also belongs to a set when the annotation is on a declaration it overrides. Kotlin does not carry an annotation over to an override, but Inara does:
interface ServiceHolder {
@Services val service: Service
}
interface ServerHolder : ServiceHolder {
override val service: HttpServer (1)
}
| 1 | Still a member of Services, without repeating the annotation. |
A function is called without arguments, so all of its parameters must have a default value or be vararg.
A default value declared on an overridden declaration counts, since an override cannot declare one of its own.
A member may belong to several sets, by carrying several set annotations.
Gathering the members of descendants
The function always answers for the module it is called on. Called on a module that extends the one listing the set, it collects the members of that module too, even when the module is typed as its ancestor:
@DIModule
interface ServerAppModule : AppModule {
@Services val metrics: MetricsReporter
}
val asAppModule: AppModule = serverApp
asAppModule.setOfServices() // database, server and metrics, plus scheduler if it is not null
A module may therefore list a set that none of its own members belongs to, as the place where the members of its descendants are gathered. A framework can list the set on the module its code receives, and let every module of the application contribute:
@DIModule(sets = [Services::class])
interface FrameworkModule {
val config: FrameworkConfig
}
fun boot(module: FrameworkModule) {
module.setOfServices().forEach { it.start() } (1)
}
| 1 | Every @Services member of the module given to boot, whichever library it comes from. |
Listing an inherited set again in sets is allowed, and changes nothing.
An annotated member does not require its module to list the set: a parent can annotate its members, and leave it to the modules extending it to gather them. This is how a composed module gathers the members of the modules it is built from, partial modules included:
@DIModule
interface DatabaseModule {
@Services val database: Database
}
@DIModule
interface ServerModule {
@Services val server: HttpServer
}
@DIModule(composed = true, sets = [Services::class])
interface ApplicationModule : DatabaseModule, ServerModule
| A module that you implement by hand, rather than build with its generated builder, only answers with the members of the module listing the set. |
Asynchronous members
By default, the generated function is not suspend, and no suspend member may belong to the set.
Pass suspend = true to @DISet to make it suspend, and allow suspend members:
@DISet(of = Service::class, suspend = true)
annotation class RemoteServices
The set decides, never its members: the function is declared on the module listing the set, while the members it collects may come from modules extending it, compiled later.
Generic element types
A generic element type is star-projected:
interface Plugin<C>
@DISet(of = Plugin::class)
annotation class Plugins (1)
| 1 | setOfPlugins() returns a Set<Plugin<*>>, which holds a Plugin<String> as well as a Plugin<Int>. |
Restrictions
The processor rejects a set annotation that:
-
has a
SOURCEretention, which would hide it on the members of a module compiled in another Gradle module; -
declares a
@Targetthat includes neitherFUNCTIONnorPROPERTY; -
names an
oftype that is neitherpublicnorinternal, or that is declared inside a declaration that is neither.
It rejects a sets argument that:
-
lists an annotation that is not annotated with
@DISet, or lists the same annotation twice; -
gives the module two sets with the same simple name, since both would generate the same function;
-
gives the module a set whose function would have the name of one of its members, which would hide it;
-
gives a
publicmodule a set whoseoftype isinternal, or whoseoftype isinternalto another Gradle module.
It rejects a member that carries a set annotation, directly or through a declaration it overrides, when it is:
-
ignored by Inara: a
var, an extension member, or a generic function; -
a function that cannot be called without arguments;
-
of a type that is not a subtype of the set’s
oftype, nullability aside; -
suspend, while the set is not@DISet(suspend = true).
Finally, a set annotation may only annotate a function or a property declared in an interface, and never a private one.
Changing a set
The code generated for a module lists the members of its sets, inherited ones included, as they are when it is compiled. Adding a member to a set, or removing one, is therefore a change to the module’s binary interface, like adding a member: every module extending it must be recompiled to see it.
Gradle does so when it builds your application, since the classpath changed. Only a module published in a library, then used with a newer version of a module it extends, can miss the change: see multi-module projects.
A set of AutoCloseable members closes every resource of a module at once, for instance in the ApplicationStopped event of the Ktor guide.
|