T - Type of the settingpublic class Setting<T> extends Object
groups that determine where they are
valid. Groups can be global or local. If a group is global, all of its settings
are global.
Each setting requires a "primary" name (available via getName(). This name
is used when storing settings and when displaying information about the setting.
Each setting is allowed to have alternate names that can be used when searching a source
for an setting's value. For example, the getSystem() method searches for a value
in the system properties by looking up the primary name & then alternate names in turn
until it finds a non-null value.
All settings in global groups are required to have unique names (including their alternate
names); it is enforced during instantiation and will throw an exception is duplicates are
found.
Getting Started:
To declare a setting you need 3 things. A factory class, a Setting.Group, and
a static field that holds the setting. Because the settings are used by annotation
processing this is done via annotations.
Factory:
A setting factory is a simple class that holds one or more group and setting definitions
and is annotated with the Setting.Factory annotation.
\@Setting.Factory
public class MySettings {
// declare groups & settings here
}
Group:
Each settings is required to belong to a group. Groups are declared using the
Setting.Group.Info annotation and the Setting.Group.declare() initializer.
\@Setting.Factory
public class MySettings {
\@Setting.Group.Info(id="my", desc="My Settings")
public static final MY_GROUP = Setting.Group.declare();
}
Setting:
Now that you have a factory and a group you can define settings. It's done similarly
to the group declaration but requires different information.
\@Setting.Factory
public class MySettings {
\@Setting.Group.Info(id="my", desc="My Settings")
public static final MY_GROUP = Setting.Group.declare();
\@Setting.Info(name="a.setting", group="my", desc"A Setting", def="10")
public static final A = Setting.declare()
}
Annotation Processing:
Setting & Setting.Group are designed to work with the "settingsgen"
annotation processor. It generates documentation and an abstract JDBC datasource
named AbstractGeneratedDataSource from all
of the global settings groups.
NOTE: Settings can be defined in code without annotations and thus without
the support of the annotation processor. This is required for settings with types
not supported by the processor.
Annotation Supported Types:
Although any type can be used with a setting only the following types can be
declared via annotations using the annotation processor
| Modifier and Type | Class and Description |
|---|---|
static interface |
Setting.Converter<U>
String to
U converter functional interface. |
static interface |
Setting.Description
Setting value description annotation.
|
static interface |
Setting.Factory
Setting factory annotation
Must be applied to any class that is generating settings via
the annotation processor.
|
static class |
Setting.Group
Setting group.
|
static interface |
Setting.Info
Setting definition annotation.
|
| Constructor and Description |
|---|
Setting(Setting.Group group,
String description,
Class<T> type,
Supplier<String> dynamicDefaultSupplier,
Setting.Converter<T> fromString,
Function<T,String> toString,
String[] names)
Constructs a new setting instance with a dynamic default value and without support via the annotation processor.
|
Setting(Setting.Group group,
String description,
Class<T> type,
T defaultValue,
Setting.Converter<T> fromString,
Function<T,String> toString,
String[] names)
Constructs a new setting instance with a static default value and without support via the annotation processor.
|
| Modifier and Type | Method and Description |
|---|---|
static <U> Setting<U> |
declare()
Forward declare a setting that will be initialized by annotation processing.
|
T |
fromString(String value)
Convert a string to the setting's native type.
|
T |
get(Properties properties)
Looks up the setting in the provided
properties. |
T |
getDefault()
Retrieve the default value of this setting.
|
String |
getDefaultText()
Retrieve the default value of this setting as text.
|
String |
getDescription()
Retrieve the description of this setting.
|
Setting.Group |
getGroup()
Retrieve the setting's group
|
String |
getName()
Retrieve the primary name of this setting.
|
String[] |
getNames()
Get all names for this setting; including
primary and alternate names.
|
T |
getSystem()
Looks up the setting in system properties.
|
String |
getText(Properties properties)
Looks up the setting in the provided
properties, returning
it as a text value. |
Class<? extends T> |
getType()
Retrieve the type of this setting.
|
void |
init(String groupId,
String description,
Class<T> type,
String defaultValue,
Setting.Converter<T> fromString,
Function<T,String> toString,
String[] names)
Initializes a forward declared setting instance.
|
void |
init(String groupId,
String description,
Class<T> type,
Supplier<String> defaultValue,
Setting.Converter<T> fromString,
Function<T,String> toString,
String[] names)
Initializes a forward declared setting instance.
|
boolean |
isDefaultDynamic()
Flag that tells whether the setting
uses a dynamic or static default value.
|
String |
toString() |
String |
toString(T value)
Convert a native type to a string value.
|
public Setting(Setting.Group group, String description, Class<T> type, T defaultValue, Setting.Converter<T> fromString, Function<T,String> toString, String[] names)
group - Group the setting belongs to.description - Description of the setting.type - Type of the setting.defaultValue - Default value of the setting in its native type.fromString - Functional that converts a string to this settings type.toString - Functional that converts a native setting value to a string.names - Primary & alternate names for the setting.public Setting(Setting.Group group, String description, Class<T> type, Supplier<String> dynamicDefaultSupplier, Setting.Converter<T> fromString, Function<T,String> toString, String[] names)
group - Group the setting belongs to.description - Description of the setting.type - Type of the setting.dynamicDefaultSupplier - Supplier of the dynamic default value for this setting.fromString - Functional that converts a string to this settings type.toString - Functional that converts a native setting value to a string.names - Primary & alternate names for the setting.public static <U> Setting<U> declare()
Settingpublic void init(String groupId, String description, Class<T> type, String defaultValue, Setting.Converter<T> fromString, Function<T,String> toString, String[] names)
groupId - Id of the group the setting belongs to.description - Description of the setting.type - Type of the setting.fromString - Functional that converts a string to this settings type.toString - Functional that converts a native setting value to a string.names - Primary & alternate names for the setting.public void init(String groupId, String description, Class<T> type, Supplier<String> defaultValue, Setting.Converter<T> fromString, Function<T,String> toString, String[] names)
groupId - Id of the group the setting belongs to.description - Description of the setting.type - Type of the setting.fromString - Functional that converts a string to this settings type.toString - Functional that converts a native setting value to a string.names - Primary & alternate names for the setting.public Setting.Group getGroup()
public String getName()
public String[] getNames()
public Class<? extends T> getType()
public boolean isDefaultDynamic()
true if the default value is dynamic, false otherwise.public T getDefault()
public String getDefaultText()
public String getDescription()
public T fromString(String value)
value - String value to parse.IllegalArgumentException - If the value cannot be parsed.public String toString(T value)
value - Native value to convert into text.public T getSystem()
default
value is returned.public T get(Properties properties)
properties.
This method tries all names (primary & alternates) in the
order in which they were defined and returns the first
non-null value.
If no value is found the setting's getDefault() default)
value is returned.public String getText(Properties properties)
properties, returning
it as a text value.
This method tries all names (primary & alternates) in the
order in which they were defined and returns the first
non-null value.
If no value is found the setting's getDefaultText() default)
value is returned.