Retrieving and Changing Preferences

This chapter contains the following subjects describing functionality to retrieve or change preferences:

Preference Scopes

Infinity Process Platform 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:

The enumeration type PreferenceScope looks like the following:

public enum PreferenceScope
{
   DEFAULT,
   PARTITION,
   REALM,
   USER
}

General Access of Preferences

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 Infinity Process Platform Services for information on these services and the according Javadoc of the AdministrationService and QueryService for detailed information on their methods and parameter usage.

AdministrationService

Retrieving preferences from a given scope

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.

Saving Preferences

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.

QueryService

Retrieving preferences from a given scope

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.

Retrieving preferences satisfying a criteria

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.

Querying Preferences

The class PreferenceQuery provides the following functionality for querying preferences:

Finding All Existing 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.

Examples

This section shows some examples of queries used by the console import or export command.

Searching for User Scoped Preferences

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.

Searching for Realm Scoped Preferences

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

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:

Permission for Reading and Writing Preferences

Available Saving Permissions

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.

Permissions Depending on Scope

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