map & set multibinding

[luozejiaqun]

Implement map & set multibinding just like dagger2.
Here is some implementation details:

Every MapMultibinding & SetMultibinding will involve 3 definitions:

1. the multibinding itself whose qualifier is mapMultibindingQualifier or setMultibindingQualifier
2. the element in multibinding whose qualifier is multibindingElementQualifier (use mapMultibindingQualifier/setMultibindingQualifier as prefix)
3. the MultibindingIterateKey which used to retrieve all elements, the key's qualifier is multibindingIterateKeyQualifier (also use mapMultibindingQualifier/setMultibindingQualifier as prefix)

When getting specific element from map multibinding, the map multibinding will try to retrieve the element through multibindingValueQualifier;
When getting all elements from map or set multibinding, the multibinding will first try to get all MultibindingIterateKeys and filter them based on multibindingQualifier, and then retrieve each element through multibindingElementQualifier.

The known problems:

1. the multibinding qualifier can't be null, since it's qualifier will be used as prefix of element & iterate key
2. the map multibinding doesn't support null as a key or value
3. the elements order of multibiding is different with the order of element definitions Now, both set & map multibinding elements are iterated in the order they are defined.

And just like dagger2, multibinding is inherited (because MultibindingIterateKey can be retrieved from getAll), current scope's multibinding can get all elements that define in linked scope.

Here are some use cases:

module {
    intoMap<String, Simple.ComponentInterface1>("keyOfComponent1") {
        Simple.Component1()
    }
    intoMap<String, Simple.ComponentInterface1>("keyOfComponent2") {
        Simple.Component2()
    }

    intoSet<Simple.ComponentInterface1> {
        Simple.Component1()
    }
    intoSet<Simple.ComponentInterface1> {
        Simple.Component2()
    }
}

val map: Map<String, Simple.ComponentInterface1> = koin.getMapMultibinding()
val set: Set<Simple.ComponentInterface1> = koin.getSetMultibinding()

issue #772

[arnaudgiuliani]

Looks interesting, will check for 4.1 👍

[luozejiaqun]

UPDATE:
the old implement is too error prone to write the following code:

module {
    intoMap("keyOfComponent1") {
        Simple.Component1() // implicitly declare Map<String, Simple.Component1>
    }
    intoMap("keyOfComponent2") {
        Simple.Component2() // implicitly declare Map<String, Simple.Component2>
    }

    intoSet {
        Simple.Component1() // implicitly declare Set<Simple.Component1>
    }
    intoSet {
        Simple.Component2() // implicitly declare Set<Simple.Component2>
    }
    /* Map<String, Simple.Component1> & Map<String, Simple.Component2>,
    Set<Simple.Component1> & Set<Simple.Component2> are different multibindings */
}

so I update the implement. Now elements can only be injected through explicit multibinding declaration and force type safety:

module {
    declareMapMultibinding<String, Simple.ComponentInterface1> {
        intoMap("keyOfComponent1") { Simple.Component1() }
        intoMap("keyOfComponent2") { Simple.Component2() }
        intoMap("keyOfComponent3") { Other() } // build error
    }

    declareSetMultibinding<Simple.ComponentInterface1> {
        intoSet { Simple.Component1() }
        intoSet { Simple.Component2() }
        intoSet { Other() } // build error
    }
}

[luozejiaqun]

The rare use cases:

data class MapKey(
    val name: String,
    val value: Int,
) {
    override fun toString(): String = name
}

module {
    declareMapMultibinding<MapKey, Simple.ComponentInterface1> {
        intoMap(MapKey("key", 1)) { Simple.Component1() }
        intoMap(MapKey("key", 2)) { Simple.Component1() } // MapMultibindingKeyTypeException will be thrown
    }
}

since multibinding implement uses key.toString() as a part of element & IterateKey qualifier, if two keys have different values but the same toString(), it defines one element actually. This is so weird and error prone, so an exception will be thrown.
BUT, the detection only works for the same module, if you separate the definitions into different modules, no exception thrown, and I can't figure out a way to detect it.

val mapKey1 = MapKey("key", 1)
val mapKey2 = MapKey("key", 2)

module {
    declareMapMultibinding<MapKey, Simple.ComponentInterface1> {
        intoMap(mapKey1) { Simple.Component1() }
    }
}

module {
    declareMapMultibinding<MapKey, Simple.ComponentInterface1> {
        intoMap(mapKey2) { Simple.Component1() } // NO exception thrown
    }
}

val map: Map<MapKey, Simple.ComponentInterface1> = koin.getMapMultibinding()
map[mapKey1] == null
map[mapKey2] != null

This is not the common use cases, maybe same module detection is enough?

[luozejiaqun]

The multibinding overrides issue:

module {
    declareMapMultibinding<String, Simple.ComponentInterface1> {
        intoMap("keyOfComponent1") { Simple.Component1() }
    }
}

module {
    declareMapMultibinding<String, Simple.ComponentInterface1> { // multibinding override
        intoMap("keyOfComponent1") { Simple.Component2() } // element override
    }
}

If we load modules with allowOverride = false, we must answer the question: Are multibinding overloads and element overloads considered overloads? If they are, then the current implementation is fine (but the DefinitionOverrideException messages maybe a little unreadable). If not, then we need to exclude these cases during loadModules. But how to detect and exclude them? I lean towards the former, that is, in this scenario, you must declare multibinding once and inject all elements within the same module.