Setting Utilities

The Setting Hierarchy

Fluent Commerce allows settings to be defined at multiple levels. When you request a setting, the platform searches for a value in the following order of precedence:

• Location: Settings for a specific location (also known as Agent).
• Retailer: Settings for a retailer.
• Account: Settings across the account.
• Global: Reserved for platform use.

`SettingUtils` automatically handles this hierarchy for you. When you request a setting, it returns the value from the most specific context that has one.

Core Methods

`getSetting`

This is the simplest method for retrieving a single setting. You provide the setting's name, and it returns a `Setting` object. 

1import com.fluentcommerce.util.core.SettingUtils;
2import com.fluentcommerce.util.core.SettingUtils.Setting;
3import java.util.Optional;
4
5// ...
6
7// Get a single setting by its name
8Setting mySetting = SettingUtils.getSetting(context, "my.setting.name");

The `Setting` Object

The `getSetting` method returns a `Setting` object, which has a powerful `.as()` method. This allows you to convert the setting's value into the data type you need, including complex POJOs if the setting is stored as JSON.

1// Get a setting and convert it to a String, with a fallback default value
2String endpointUrl = SettingUtils.getSetting(context, "my.endpoint.url")
3    .as(String.class)
4    .orElse("https://default.api.com/endpoint");
5
6// Get a setting and convert it to an Integer
7int retryCount = SettingUtils.getSetting(context, "my.retry.count")
8    .as(Integer.class)
9    .orElse(3);
10
11// If a setting stores a JSON object, you can convert it directly to a POJO
12Optional<MyConfig> config = SettingUtils.getSetting(context, "my.json.config")
13    .as(MyConfig.class);

`getSettings`

If you need to retrieve multiple settings at once, `getSettings` is more efficient than calling `getSetting` repeatedly, as it fetches all specified settings in a single API call.

You provide a `Map` where the keys are your own identifiers and the values are the setting names. The method returns a new `Map` with the same keys, but with each value replaced by a `Setting` object containing the corresponding setting value.

1Map<String, String> settingsToFetch = ImmutableMap.of(
2    "endpoint", "my.endpoint.url",
3    "timelimit", "my.timelimit.value"
4);
5
6// Get multiple settings in one call
7Map<String, Setting> fetchedSettings = SettingUtils.getSettings(context, settingsToFetch);
8
9// Access the settings using the keys you provided
10String endpoint = fetchedSettings.get("endpoint").as(String.class).orElse(null);
11int timeout = fetchedSettings.get("timelimit").as(Integer.class).orElse(5000);

`getSettingsByNamespace`

This method allows you to fetch all settings that share a common prefix or "namespace". This is useful for retrieving a group of related settings without having to know all their individual names.

If a setting contains both a `value` and a `lobValue` (line-of-business-specific value), this method will prioritize `value`, giving preference to the primary configuration over the business-specific one. The result is returned as a `Map`, where the keys match those provided in the request, but each value is replaced with a `Setting` object containing the resolved setting value.

1// Fetch all settings that start with "my.feature."
2Map<String, Setting> featureSettings = SettingUtils.getSettingsByNamespace(context, "my.feature");
3
4String featureName = featureSettings.get("my.feature.name").as(String.class).orElse(null);
5boolean isEnabled = featureSettings.get("my.feature.enabled").as(Boolean.class).orElse(false);