Configurable components

Preferred configurations

The PreferredConfig annotation can be used to specify one or more preferred Config subtypes for the component. When the Configurer configures the component, it will try to find a Config instance of the preferred types in the order specified, and use the first one found to configure the component. If none of the preferred configurations is found, the default configuration provided to the Configurer will be used, unless the fallbackToDefaultConfig option is set to false in the annotation.

This allows libraries to provide specific Config subtypes for their configurable components, while still allowing the application to configure them using the default configuration. The application that uses the library can use it's default configuration or provide the library specific configuration to configure the library components.

Components can convert to the specific Config subtype using the Config.as(Class<T>) method in the configure method.

Example:

interface MySuperConfig extends Config {}
interface MyConfig extends MySuperConfig {

    final String HOST_PROP = "host";
    final String PORT_PROP = "port";

    default String getHost() {
        return get(HOST_PROP, "localhost");
    }

    default int getPort() {
        return getInteger(PORT_PROP, 8080);
    }
}

@PreferredConfig({ MyConfig.class, MySuperConfig.class })
class MyComponent implements Configurable {

    private String host;
    private int port;

    @Override
    public void configure(Config config) {
        MyConfig myConfig = config.as(MyConfig.class);
        this.host = myConfig.getHost();
        this.port = myConfig.getPort();
   }
}

This is useful for external libraries components, that can be configured using the library custom Config subtypes, providing specific configuration for the library, or fallback to application's default configuration.

Configuration options

The ConfigurationOptions annotation allows to customize the configuration process for the component.

By default, the Configurer will configure properties annotated with @ConfigurableProperty. As properties are only configured if annotated with @ConfigurableProperty, setting configureProperties to false can be used to skip the properties configuration step, for example in components extending other configurable components that already configure their properties.

Example:

class BaseComponent implements Configurable {
    ...
    @ConfigurableProperty("host")
    private String host;
    ...
}
@ConfigurationOptions(configureProperties = false)
class MyExtendedComponent extends BaseComponent {
    ...
    @Override
    public void configure(Config config) {
        ...
        setHost(...);
        ...
    }
    ...
}

Nested Configurable beans are not configured by default, as independent configuration is expected for them. This can be overriden setting configureNestedBeans to true, to enable automatic configuration of nested beans.

Example:

class NestedComponent implements Configurable {
    ...
}
@ConfigurationOptions(configureNestedBeans = true)
class MyComponent implements Configurable {
    ...
    private NestedComponent nestedComponent = new NestedComponent();
    ...
}

Note: The configurable bean must have accesible getters for the nested configurable beans, or the property must be public.