68. Settings Provider¶

The net.solarnetwork.settings.SettingSpecifierProvider interface defines the way a class can declare themselves as a user-configurable component. The main elements of this API are:

public interface SettingSpecifierProvider {

    /**
     * Get a unique, application-wide setting ID.
     *
     * @return unique ID
     */
    String getSettingUid();

    /**
     * Get a non-localized display name.
     *
     * @return non-localized display name
     */
    String getDisplayName();

    /**
     * Get a list of {@link SettingSpecifier} instances.
     *
     * @return list of {@link SettingSpecifier}
     */
    List<SettingSpecifier> getSettingSpecifiers();

}

The getSettingUid() method defines a unique ID for the configurable component. By convention the class or package name of the component (or a derivative of it) is used as the ID.

The getSettingSpecifiers() method returns a list of all the configurable properties of the component, as a list of Setting Specifier instances.

68.1 Setting accessors¶

s

@Override
private String username;

public List<SettingSpecifier> getSettingSpecifiers() {
    List<SettingSpecifier> results = new ArrayList<>(1);

    // expose a "username" setting with a default value of "admin"
    results.add(new BasicTextFieldSettingSpecifier("username", "admin"));

    return results;
}

// settings are updated at runtime via standard setter methods
public void setUsername(String username) {
    this.username = username;
}

Setting values are treated as strings within the Settings API, but the methods associated with settings can accept any primitive or standard number type like int or Integer as well.

BigDecimal setting example

@Override
private BigDecimal num;

public List<SettingSpecifier> getSettingSpecifiers() {
    List<SettingSpecifier> results = new ArrayList<>(1);

    results.add(new BasicTextFieldSettingSpecifier("num", null));

    return results;
}

// settings will be coerced from strings into basic types automatically
public void setNum(BigDecimal num) {
    this.num = num;
}

68.1.1 Proxy setting accessors¶

Sometimes you might like to expose a simple string setting but internally treat the string as a more complex type. For example a Map could be configured using a simple delimited string like key1 = val1, key2 = val2. For situations like this you can publish a proxy setting that manages a complex data type as a string, and en/decode the complex type in your component accessor methods.

Delimited string to Map setting example

@Override
private Map<String, String> map;

public List<SettingSpecifier> getSettingSpecifiers() {
    List<SettingSpecifier> results = new ArrayList<>(1);

    // expose a "mapping" proxy setting for the map field
    results.add(new BasicTextFieldSettingSpecifier("mapping", null));

    return results;
}

public void setMapping(String mapping) {
    this.map = StringUtils.commaDelimitedStringToMap(mapping);
}