Settings Services

Vault Java SDK provides two services for working with Vault configuration settings.

Settings Service

SettingsService provides read-only access to global settings values from within custom Vault Java SDK code. The service supports both single and batch retrieval, however, batch retrieval is preferred when reading multiple settings to amortize the lookup cost.

To retrieve a setting, build a SettingRetrieveRequest using newSettingRetrieveRequestBuilder(). Specify the settings type with withType(), the group with withGroup(), and the setting name with withSetting(). All three are required.

The following example retrieves a single boolean setting:

SettingsService settingsService = ServiceLocator.locate(SettingsService.class);

SettingRetrieveRequest checklistsEnabledRequest = settingsService.newSettingRetrieveRequestBuilder()
        .withType("general_settings__sys")
        .withGroup("checklist")
        .withSetting("enabled")
        .build();
Boolean checklistsEnabled = settingsService.retrieve(checklistsEnabledRequest).getValue(ValueType.BOOLEAN);

The following example retrieves multiple settings in a single batch call:

SettingsService settingsService = ServiceLocator.locate(SettingsService.class);

SettingRetrieveRequest checklistsEnabled = settingsService.newSettingRetrieveRequestBuilder()
        .withType("general_settings__sys").withGroup("checklist").withSetting("enabled").build();
SettingRetrieveRequest enableBinderExport = settingsService.newSettingRetrieveRequestBuilder()
        .withType("general_settings__sys").withGroup("binder_options").withSetting("enable_binder_export").build();

SettingBatchRetrieveRequest batchRequest = settingsService.newSettingBatchRetrieveRequestBuilder()
        .withRequests(VaultCollections.asList(checklistsEnabled, enableBinderExport))
        .build();

// Responses are in the same order as the requests.
List<SettingRetrieveResponse> responses = settingsService.batchRetrieve(batchRequest).getResponses();
Boolean checklists = responses.get(0).getValue(ValueType.BOOLEAN);
Boolean binderExport = responses.get(1).getValue(ValueType.BOOLEAN);

Use hasValue() to guard against settings that exist in the schema but have no stored value. getValue() returns null in that case.

SettingsService settingsService = ServiceLocator.locate(SettingsService.class);

SettingRetrieveRequest request = settingsService.newSettingRetrieveRequestBuilder()
        .withType("general_settings__sys")
        .withGroup("vault_information")
        .withSetting("vault_name")
        .build();

SettingRetrieveResponse response = settingsService.retrieve(request);

String vaultName = response.hasValue() ? response.getValue(ValueType.STRING) : "default-name";

Learn more about SettingsService in the Javadocs.

Settings Metadata Service

SettingsMetadataService provides read-only access to what types, groups, and settings exist, along with their labels, descriptions, and value types. It functions similarly to the three metadata Settings API endpoints. It does not read or modify setting values.

The following example retrieves the full schema for a settings type:

SettingsMetadataService metadataService = ServiceLocator.locate(SettingsMetadataService.class);

SettingsTypeMetadataRetrieveRequest request = metadataService
        .newSettingsTypeMetadataRetrieveRequestBuilder()
        .withType("general_settings__sys")
        .build();

SettingsTypeMetadataRetrieveResponse response = metadataService.retrieveTypeMetadata(request);

for (SettingsGroupInfo group : response.getGroups()) {
    for (SettingInfo setting : group.getSettings()) {
        String name = setting.getName();       // e.g. "enable_checklists"
        SettingType type = setting.getType();  // BOOLEAN, STRING, or NUMBER
    }
}

The following example lists all available settings types:

SettingsMetadataService metadataService = ServiceLocator.locate(SettingsMetadataService.class);

SettingsTypeListResponse response = metadataService.listTypes();

if (response.hasTypes()) {
    for (SettingsTypeInfo type : response.getTypes()) {
        String typeName = type.getName();   // e.g. "general_settings__sys"
        String typeLabel = type.getLabel(); // e.g. "General Settings"
    }
}

The following example retrieves metadata for a single setting:

SettingsMetadataService metadataService = ServiceLocator.locate(SettingsMetadataService.class);

SettingMetadataRetrieveRequest request = metadataService
        .newSettingMetadataRetrieveRequestBuilder()
        .withType("general_settings__sys")
        .withGroup("checklist")
        .withSetting("enabled")
        .build();

SettingInfo settingInfo = metadataService.retrieveSettingMetadata(request).getSettingInfo();

String name = settingInfo.getName();
String label = settingInfo.getLabel();
SettingType type = settingInfo.getType();             // BOOLEAN, STRING, or NUMBER
String defaultValue = settingInfo.getDefaultValue();  // null if no default is defined

Learn more about SettingsMetadataService in the Javadocs.