4.6 Using @EachProperty to Drive Configuration

The @ConfigurationProperties annotation is great for a single configuration class, but sometimes you want multiple instances each with their own distinct configuration. That is where EachProperty comes in.

The @EachProperty annotation will create a ConfigurationProperties bean for each sub-property within the given property. As an example consider the following class:

Using @EachProperty

import io.micronaut.context.annotation.Parameter;
import io.micronaut.context.annotation.EachProperty;
@EachProperty("test.datasource")  (1)
public class DataSourceConfiguration {
    private final String name;
    private URI url = new URI("localhost");
    public DataSourceConfiguration(@Parameter String name) (2)
            throws URISyntaxException {
        this.name = name;
    }
    public String getName() {
        return name;
    }
    public URI getUrl() { (3)
        return url;
    }
    public void setUrl(URI url) {
        this.url = url;
    }
}

Using @EachProperty

@EachProperty("test.datasource")
(1)
class DataSourceConfiguration {
    final String name
    URI url = new URI("localhost")
    DataSourceConfiguration(@Parameter String name) (2)
            throws URISyntaxException {
        this.name = name
    }
}

Using @EachProperty

@EachProperty("test.datasource")  (1)
class DataSourceConfiguration (2)
@Throws(URISyntaxException::class)
constructor(@param:Parameter val name: String) {
    (3)
    var url = URI("localhost")
}

The above DataSourceConfiguration defines a url property to configure one or many hypothetical data sources of some sort. The URLs themselves can be configured using any of the PropertySource instances evaluated to Micronaut:

Providing Configuration to @EachProperty

        ApplicationContext applicationContext = ApplicationContext.run(PropertySource.of(
                "test",
                CollectionUtils.mapOf(
                        "test.datasource.one.url", "jdbc:mysql://localhost/one",
                        "test.datasource.two.url", "jdbc:mysql://localhost/two")
        ));

Providing Configuration to @EachProperty

    ApplicationContext applicationContext = ApplicationContext.run(PropertySource.of(
            "test",
            [
                    "test.datasource.one.url": "jdbc:mysql://localhost/one",
                    "test.datasource.two.url": "jdbc:mysql://localhost/two"
            ]
    ))

Providing Configuration to @EachProperty

        val applicationContext = ApplicationContext.run(PropertySource.of(
                "test",
                mapOf(
                        "test.datasource.one.url" to "jdbc:mysql://localhost/one",
                        "test.datasource.two.url" to "jdbc:mysql://localhost/two"
                )
        ))

In the above example two data sources (called one and two) are defined under the test.datasource prefix defined earlier in the @EachProperty annotation. Each of these configuration entries triggers the creation of a new DataSourceConfiguration bean such that the following test succeeds:

Evaluating Beans Built by @EachProperty

        Collection<DataSourceConfiguration> beansOfType = applicationContext.getBeansOfType(DataSourceConfiguration.class);
        assertEquals(2, beansOfType.size()); (1)
        DataSourceConfiguration firstConfig = applicationContext.getBean(
                DataSourceConfiguration.class,
                Qualifiers.byName("one") (2)
        );
        assertEquals(
                new URI("jdbc:mysql://localhost/one"),
                firstConfig.getUrl()
        );

Evaluating Beans Built by @EachProperty

        when:
        Collection<DataSourceConfiguration> beansOfType = applicationContext.getBeansOfType(DataSourceConfiguration.class)
        assertEquals(2, beansOfType.size()) (1)
        DataSourceConfiguration firstConfig = applicationContext.getBean(
                DataSourceConfiguration.class,
                Qualifiers.byName("one") (2)
        )
        then:
        new URI("jdbc:mysql://localhost/one") == firstConfig.getUrl()

Evaluating Beans Built by @EachProperty

        val beansOfType = applicationContext.getBeansOfType(DataSourceConfiguration::class.java)
        assertEquals(2, beansOfType.size.toLong()) (1)
        val firstConfig = applicationContext.getBean(
                DataSourceConfiguration::class.java,
                Qualifiers.byName("one") (2)
        )
        assertEquals(
                URI("jdbc:mysql://localhost/one"),
                firstConfig.url
        )

List Based Binding

The default behavior of @EachProperty is to bind from a map style of configuration where the key is the named qualifier of the bean and the value is the data to bind from. For cases where map style configuration doesn’t make sense, it is possible to inform Micronaut the class should be bound from a list. Simply set the list member on the annotation to true.

@EachProperty List Example

/*
 * Copyright 2017-2020 original authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.micronaut.docs.config.env;
import io.micronaut.context.annotation.EachProperty;
import io.micronaut.context.annotation.Parameter;
import io.micronaut.core.order.Ordered;
import java.time.Duration;
@EachProperty(value = "ratelimits", list = true) (1)
public class RateLimitsConfiguration implements Ordered { (2)
    private final Integer index;
    private Duration period;
    private Integer limit;
    RateLimitsConfiguration(@Parameter Integer index) { (3)
        this.index = index;
    }
    @Override
    public int getOrder() {
        return index;
    }
    public Duration getPeriod() {
        return period;
    }
    public void setPeriod(Duration period) {
        this.period = period;
    }
    public Integer getLimit() {
        return limit;
    }
    public void setLimit(Integer limit) {
        this.limit = limit;
    }
}

@EachProperty List Example

/*
 * Copyright 2017-2020 original authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.micronaut.docs.config.env
import io.micronaut.context.annotation.EachProperty
import io.micronaut.context.annotation.Parameter
import io.micronaut.core.order.Ordered
import java.time.Duration
@EachProperty(value = "ratelimits", list = true) (1)
class RateLimitsConfiguration implements Ordered { (2)
    private final Integer index
    Duration period
    Integer limit
    RateLimitsConfiguration(@Parameter Integer index) { (3)
        this.index = index
    }
    @Override
    int getOrder() {
        index
    }
}

@EachProperty List Example

/*
 * Copyright 2017-2020 original authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package io.micronaut.docs.config.env
import io.micronaut.context.annotation.EachProperty
import io.micronaut.context.annotation.Parameter
import io.micronaut.core.order.Ordered
import java.time.Duration
@EachProperty(value = "ratelimits", list = true) (1)
class RateLimitsConfiguration
    constructor(@param:Parameter private val index: Int) (3)
    : Ordered { (2)
    var period: Duration? = null
    var limit: Int? = null
    override fun getOrder(): Int {
        return index
    }
}