You can access the admin page and navigate to the Settings > List menu to view the list of setting values or add a new setting value.

Data Types

1. ARRAY: An array data type where values are separated by commas. Example: 1, 2, 3
2. BOOLEAN: A boolean data type with values true or false.
3. FLOAT: A floating-point number data type.
4. DATE: A date data type, for example, 2024-05-30.
5. DATETIME: A datetime data type, for example, 2024-05-30 12:01:02.
6. EMAIL: An email data type, for example, dung@youngmonkeys.org.
7. IMAGE: An image data type represented by an image ID.
8. INTEGER: An integer data type ranging from -2147483648 to 2147483647.
9. LONG: A long integer data type ranging from -9223372036854775808 to 9223372036854775807.
10. MEDIA: A media data type represented by a media ID.
11. STRING: A string data type.
12. JSON: A structured JSON data type.
13. FILE_SIZE: A file size data type, for example, 1B, 2KB, 3MB, 4GB, 5TB.
14. PASSWORD: A password data type that will be encrypted.
15. URL: A URL data type.

SettingService Class

This class provides functions to:

• Allow you to retrieve setting values from the database using the getXxxValue functions.
• Enable you to cache setting values using the watchLastUpdatedTimeAndCache or scheduleCacheValue functions. You can then use the getCachedValue function to retrieve the cached value.
• Allow you to decrypt encrypted setting values using the decryptValue function.
• Provide you with the admin URL using the getAdminUrl function.
• Provide you with the web URL using the getWebUrl function.
• Provide you with the websocket URL using the getWebManagementUrl function.

You can find the source code of the SettingService here.

AdminSettingService Class

This class provides functions to:

• Allow you to set setting values using the saveSetting or setXxxValue functions.
• Allow you to set the last update time of settings to trigger the update of values in the cache.

You can find the java docs of the AdminSettingService here.

Initialization and Usage

Let's take an example where we are developing a website named book store. Suppose the users of book store can be authors, so we need to create a role for authors and save the role ID in the settings. First, let's declare the setting name as follows:

public static final String SETTING_NAME_BOOK_AUTHOR_ROLE_ID =
        "book_store_book_author_role_id";

Next, we can create a configuration class, which can be called when EzyPlatform starts up. It will check if the author role has been created and saved in the settings. If not, it will create the author role and save the role ID in the settings:

@EzyConfigurationAfter
@AllArgsConstructor
public class AdminBookStoreConfig implements EzyBeanConfig {

    private final AdminSettingService settingService;
    private final AdminUserRoleService userRoleService;

    @Override
    public void config() {
        long savedBookAuthorRoleId = settingService.getLongValue(
            SETTING_NAME_BOOK_AUTHOR_ROLE_ID
        );
        if (savedBookAuthorRoleId <= 0) {
            long roleId = userRoleService.saveUserRoleNameIfNotExists(
                AddUserRoleNameModel.builder()
                    .name(ROLE_AUTHOR_NAME)
                    .displayName(ROLE_AUTHOR_DISPLAY_NAME)
                    .build()
            ).getId();
            settingService.setLongValue(
                SETTING_NAME_BOOK_AUTHOR_ROLE_ID,
                roleId
            );
        }
    }
}

When you need to use it, you can retrieve the value of the setting book_store_book_author_role_id like this:

public class BookStoreSettingService {

    private final SettingService settingService;

    public long getBookAuthorRoleId() {
        return settingService.getLongValue(
            SETTING_NAME_BOOK_AUTHOR_ROLE_ID
        );
    }
}

Cache

Sometimes, we want to cache data on the server for faster access. For example, book store needs to display a list of featured books on the homepage, which requires quick querying. Therefore, we can save the list of IDs of featured books in the settings:

public static final String SETTING_NAME_HIGHLIGHT_BOOK_IDS =
        "book_store_highlight_book_ids";

Since by default the value stored in settings is a string, to retrieve a list of IDs as List<Long>, we need to register a converter first:

settingService.addValueConverter(
    SETTING_NAME_BOOK_AUTHOR_ROLE_ID,
    value -> SingletonStringDeserializer
        .getInstance()
        .deserialize(value, List.class, Long.class)
);

Next, there are two ways to cache data.

This method is suitable for small settings because it queries the database periodically. The source code will look like this:

settingService.scheduleCacheValue(
    SETTING_NAME_HIGHLIGHT_BOOK_IDS
);

For this method, saving the setting is simple, for example:

public void setHighlightBookIds(
    List<Long> bookIds
) {
    settingService.setArrayValue(
        SETTING_NAME_HIGHLIGHT_BOOK_IDS,
        bookIds
    );
}

This method will generate an additional setting with the suffix _last_updated_time, for example book_store_highlight_book_ids_last_updated_time, to store the last update time. SettingService will frequently query the database to check if there is a change in the last update time. If so, it will retrieve the setting from the database and store it in the cache. The source code using watchLastUpdatedTimeAndCache will look like this:

settingService.watchLastUpdatedTimeAndCache(
    SETTING_NAME_HIGHLIGHT_BOOK_IDS
);

For this method, saving the setting is slightly more complex:

public void setHighlightBookIds(
        List<Long> bookIds
) {
    settingService.setArrayValue(
        SETTING_NAME_HIGHLIGHT_BOOK_IDS,
        bookIds
    );
    settingService.setLastUpdateTime(
        SETTING_NAME_HIGHLIGHT_BOOK_IDS
    );
}

It needs to call the setLastUpdateTime function to change the last update time.

Encryption

To encrypt sensitive information, you can use the setPasswordValue function, for example:

settingService.setPasswordValue(
    "password_setting_key",
    "password value"
);

When you need to retrieve the setting value, you will call the getPasswordValue function.

settingService.getPasswordValue("password_setting_key");

Conventions

Although you can name settings whatever you want, I recommend using uppercase letters and underscores for consistency and ease of recognition by users. For example: book_store_book_author_role_id.