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.
|
Annotation Type | Description |
---|---|
ConfigurationSetting.Description | Deprecated
since 20.3.0.
|
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.