This chapter contains the following subjects describing functionality to retrieve or change preferences:
Stardust supports different scopes to store and retrieve preferences. A scope always has to be specified when accessing the preference store. The following scopes are supported:
IStaticConfigurationProvider SPI implementing providers.
Refer to the chapter
Implementing a Static Configuration Provider for Default Preferences
for details on how to implement this provider.The enumeration type PreferenceScope looks like the following:
public enum PreferenceScope
{
DEFAULT,
PARTITION,
REALM,
USER
}
The AdministrationService and the QueryService classes provide methods to retrieve preferences from a given scope.
Please also refer to the sections AdministrationService and QueryService of the chapter Stardust Services for information on these services and the according Javadoc of the AdministrationService and QueryService for detailed information on their methods and parameter usage.
Use the following method to retrieve preferences from a given scope:
Preferences getPreferences(PreferenceScope scope, String moduleId, String preferencesId);
Hereby, scope determines the scope from which the
preferences are to be retrieved from. Parameter moduleId
declares the moduleId of the preferences and the preferencesId
the ID of the preferences.
The method returns a preferences object.
To saves changed preferences to the preference store, the following method is provided:
void savePreferences(Preferences preferences);
Parameter preferences determines a preferences object to
be saved.
Required permission for this method is saveOwnUserScopePreferences.
In case you like to save a complete list of preferences to the preference store, use the following method:
void savePreferences(List<Preferences> preferences);
The parameter preferences declares the list of
preferences to be saved.
Required permission for this method is saveOwnUserScopePreferences.
The method to retrieve preferences from a given scope has the
same usage as for the AdministrationService as described in
section Retrieving preferences from a given
scope of the AdministrationService.
To retrieve preferences satisfying the criteria specified in a provided query, use the following method:
List<Preferences> getAllPreferences(PreferenceQuery preferenceQuery);
Hereby, preferenceQuery determines the preference query
with specified criteria. Please refer to the following section for a detailed
description on the according query class.
A list of preferences satisfying the criteria is returned.
The class PreferenceQuery provides the following functionality for querying preferences:
The following method provides the option to create a query for finding all existing preferences on a defined scope:
public static PreferenceQuery findAll(PreferenceScope scope)
{
PreferenceQuery query = new PreferenceQuery();
if (scope == null)
{
scope = PreferenceScope.PARTITION;
}
query.getFilter().add(PreferenceQuery.SCOPE.isEqual(scope.name()));
return query;
}
Hereby, the parameter scope determines the scope to search
in. The method returns the readily configured query.
To search for preferences, use the following method:
public static PreferenceQuery findPreferences(PreferenceScope scope, String moduleId,
String preferencesId)
{
PreferenceQuery query = new PreferenceQuery();
if (scope == null)
{
scope = PreferenceScope.PARTITION;
}
query.getFilter().add(PreferenceQuery.SCOPE.isEqual(scope.name())).add(
PreferenceQuery.MODULE_ID.like(moduleId)).add(
PreferenceQuery.PREFERENCES_ID.like(preferencesId));
return query;
}
The scope to search in is determines by scope.
Parameter moduleId declares the module ID, preferencesId
the preferences ID to search for. Please note that
you can use the wildcard '*' for both. The method
returns the readily configured query.
This section shows some examples of queries used by the console import or export command.
PreferenceQuery preferenceQuery = PreferenceQuery.findPreferences(PreferenceScope.PARTITION, ConfigurationVariableUtils.CONFIGURATION_VARIABLES, "*");
PreferenceQuery preferenceQuery = PreferenceQuery.findPreferences(PreferenceScope.PARTITION, ConfigurationVariableUtils.CONFIGURATION_VARIABLES, modelId);
PreferenceQuery preferenceQuery = PreferenceQuery.findPreferences(PreferenceScope.PARTITION, PermissionUtils.PERMISSIONS, PermissionUtils.GLOBAL_SCOPE);
To create a query to search for user scoped preferences belonging to different users and user realms, the following method is provided:
public static PreferenceQuery findPreferencesForUsers(String realmId, String userId,
String moduleId, String preferencesId)
{
PreferenceQuery query = new PreferenceQuery();
query.getFilter()
.add(PreferenceQuery.SCOPE.isEqual(PreferenceScope.USER.name()))
.add(PreferenceQuery.MODULE_ID.like(moduleId))
.add(PreferenceQuery.PREFERENCES_ID.like(preferencesId))
.add(PreferenceQuery.REALM_ID.like(realmId))
.add(PreferenceQuery.USER_ID.like(userId));
return query;
}
A non-admin user can also use these methods.
For using wildcards, Administrator role is required.
If a non-admin user is trying to use the method then the result would be restricted to
preferences matching its own userID.
Parameter realmId determines the realm ID,
parameter userId the user ID,
parameter moduleId the module ID and
parameter preferencesId the preferences ID to search for.
The wildcard '*' can be used for all these parameters.
The method returns the readily configured query.
In case you like to create a query to search for realm scoped preferences belonging to different realms, use the following method:
public static PreferenceQuery findPreferencesForRealms(String realmId,
String moduleId, String preferencesId)
{
PreferenceQuery query = new PreferenceQuery();
query.getFilter()
.add(PreferenceQuery.SCOPE.isEqual(PreferenceScope.REALM.name()))
.add(PreferenceQuery.MODULE_ID.like(moduleId))
.add(PreferenceQuery.PREFERENCES_ID.like(preferencesId))
.add(PreferenceQuery.REALM_ID.like(realmId));
return query;
}
A non-admin user can also use these methods.
For using wildcards, Administrator role is required.
If a non-admin user is trying to use the method then the result would be restricted to
preferences matching its own realmID.
Parameter realmId determines the realm ID,
parameter moduleId the module ID and
parameter preferencesId the preferences ID to search for.
The wildcard '*' is allowed for these parameters.
The method returns the readily configured query.
Cleaning up preferences can be performed depending on the preference scope. User and realm scoped preferences need to be removed with user and realm references, whereby partition scoped preferences are cleaned up with models.
The following preferences cleanup behavior occurs on API calls:
cleanupRuntime(true);cleans up no preferences at all. Users are kept and so are the preferences.
cleanupRuntime(false);cleans up user and realm scope preferences.
cleanupRuntimeAndModels();cleans up user, realm and partition scope preferences.
The following permissions for saving preferences in a specific scope are available:
Note that saving to other realms or users scopes always requires the administrator role.
Reading preferences from default, system, own partition, own realm and own user scope is always allowed. Other read access needs administrator permissions.
Saving is allowed in the own user scope by default, while saving in other scopes is not allowed by default. Administrators may save preferences in all scopes and in all partitions, realms or users folders.
The following permissions apply for reading and writing preferences in a specific scope:
| Scope Name | Own Scope | Read Permission | Write Permission |
|---|---|---|---|
| User | yes | always | default = owner |
| Realm | yes | always | default = administrator |
| Partition | yes | always | default = administrator |
| Default | - | always | never |
| User | no | administrator | administrator |
| Realm | no | administrator | administrator |
| Partition | no | never | never |