See: Description
Interface | Description |
---|---|
Configuration |
Represents a set of configuration properties.
|
Class | Description |
---|---|
ConfigurationSetting |
Declares a
ConfigurationSetting , specifying it's type, and default value. |
ConfigurationSetting.Builder |
Builds
ConfigurationSetting instances |
TimeDuration |
Represents a specification of a time duration.
|
Each plugin may contribute zero or more ConfigurationSetting
values. By declaring discoverable ConfigurationSetting
values a plugin enables two things:
Inject
injection site. This reduces coupling to the Plugin API, making it easier to re-use or share code in the plugin in other code bases and it also facilitates easier unit testing. Unit tests can just pass the the required values directly to the class under test, rather than having to pass values via the Configuration
APIConfiguration
Best practice is to define a constant for the setting name and use that constant rather than a literal string. The ConfigurationSetting
should be defined as a final static
constant. The field must be annotated with Named
to indicate the unique name of the setting.
The field or it's enclosing type must be annotated with Provides
so that the field is discoverable.
ConfigurationSetting
data-types must be one of the following:
String
- A textual valueInteger
- An integer valueLong
- A large integer valueBoolean
- A boolean value. It is recommended that the default value for a Boolean
setting is always Boolean.FALSE
Enum
- Where the value of is one of the case insensitive name of enum value namesTimeDuration
- A value representing a durationpublic interface PluginSettings { static final String SETTING_FOO = "my.plugin.setting.foo"; } @Provides class PluginImpl { @Named(PluginSettings.SETTING_FOO) static final ConfigurationSetting FOO = ConfigurationSetting.setting(10); }
public interface PluginSettings { static final String ACCESS_MODE_SETTING = "my.plugin.accessMode"; } @Provides class PluginImpl { @Named(PluginSettings.ACCESS_MODE_SETTING) @ConfigurationSetting.Description(@TranslatableDescription(type = MyPluginMessages.class, id = MyPluginMessages.ACCESS_MODE_DESCRIPTION)) static final ConfigurationSetting ACCESS_MODE = ConfigurationSetting.setting(java.nio.AccessMode.class, java.nio.AccessMode.READ); }
When a ConfigurationSetting
is declared as outlined above, the Dependency Injection runtime is able to map each setting to a concrete value derived from the Configuration
instance applicable to the current scope. Thus instead of invoking Configuration.get(String)
(which is strongly discouraged) a plugin service can just declare a dependency on the configuration setting value via an appropriately typed and Named
parameter in it's constructor
For example to inject the my.plugin.setting.foo
configuration setting value into some service, one would do:
@Provides class MyPluginService implements SomeService { @Inject MyPluginService(final @Named(PluginSettings.FOO_SETTING) int foo) { ... } }
For ease of use, injection sites may use primitive types where applicable.
Integer
can be injected as int
Long
can be injected as long
Boolean
can be injected as boolean
Note in each case if no default value is specified for the setting and the Configuration
also lacks a value for the setting then a runtime error will occur during creation of the service and likely lead to the application not starting.