com.atlassian.sal.api.usersettings

Interface UserSettingsService

public interface UserSettingsService

Service for getting and updating immutable UserSettings objects stored against a user name UserSettings can be used to store values of type String, Boolean and Long - nothing more. Max key length is MAX_KEY_LENGTH, Values of type String also have a max length of MAX_STRING_VALUE_LENGTH

Since:

2.9

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_KEY_LENGTH Key length is limited by DB constraints.
static int	MAX_STRING_VALUE_LENGTH
static String	USER_SETTINGS_PREFIX

Method Summary

Methods

Modifier and Type	Method and Description
UserSettings	getUserSettings(String userName) Deprecated. since 2.10, use getUserSettings(com.atlassian.sal.api.user.UserKey) instead
UserSettings	getUserSettings(UserKey userKey) Gets the UserSettings for the given user.
void	updateUserSettings(String userName, com.google.common.base.Function<UserSettingsBuilder,UserSettings> updateFunction) Deprecated. since 2.10, use updateUserSettings(com.atlassian.sal.api.user.UserKey, com.google.common.base.Function) instead
void	updateUserSettings(UserKey userKey, com.google.common.base.Function<UserSettingsBuilder,UserSettings> updateFunction) Updates the UserSettings stored for this user.

Field Detail

USER_SETTINGS_PREFIX

static final String USER_SETTINGS_PREFIX

See Also:

Constant Field Values

MAX_STRING_VALUE_LENGTH

static final int MAX_STRING_VALUE_LENGTH

See Also:

Constant Field Values

MAX_KEY_LENGTH

static final int MAX_KEY_LENGTH

Key length is limited by DB constraints.

Method Detail

getUserSettings

@Deprecated
UserSettings getUserSettings(String userName)

Deprecated. since 2.10, use getUserSettings(com.atlassian.sal.api.user.UserKey) instead

Gets the UserSettings for the user with name userName.

Parameters:

userName - name of the user whose user settings are to be retrieved

Returns:

a UserSettings for the user with name userName,

Throws:

IllegalArgumentException - if no user could be found with that name

getUserSettings

UserSettings getUserSettings(UserKey userKey)

Gets the UserSettings for the given user.

Parameters:

userKey - key of a user whose user settings are to be retrieved

Returns:

a UserSettings for the user with name userName,

Throws:

IllegalArgumentException - if no user could be found with that name

updateUserSettings

@Deprecated
void updateUserSettings(String userName,
                                 com.google.common.base.Function<UserSettingsBuilder,UserSettings> updateFunction)

Deprecated. since 2.10, use updateUserSettings(com.atlassian.sal.api.user.UserKey, com.google.common.base.Function) instead

Updates the UserSettings stored for this user with name UserName. Implementations of this interface will ensure that updateFunctions provided to this method are called in a threadsafe manner. Consumers can throw RuntimeExceptions within updateFunction to control flow when the input to updateFunction is unexpected. As such, implementers must either rethrow caught RuntimeExceptions, or not catch them in the first place. The intended behaviour of this function is that the return value of updateFunction be stored against the specified user. However, product implementations do not do this, and update the user settings in the underlying database in response to calls to the UserSettingsBuilder provided to updateFunction, and ignore the return value from updateFunction.

Parameters:

userName - name of the user whose UserSettings are to be updated. If userName does not match a known user, updateFunction will not be called.

updateFunction - function to update a user's UserSettings. The parameter to updateFunction is a UserSettingsBuilder whose contents match the UserSettings for the provided user.

Throws:

IllegalArgumentException - if no user could be found with that name

UnsupportedOperationException - if updateFunction creates entries with key length > MAX_KEY_LENGTH or with a String value with length > MAX_STRING_VALUE_LENGTH

updateUserSettings

void updateUserSettings(UserKey userKey,
                      com.google.common.base.Function<UserSettingsBuilder,UserSettings> updateFunction)

Updates the UserSettings stored for this user. Implementations of this interface will ensure that updateFunctions provided to this method are called in a threadsafe manner. Consumers can throw RuntimeExceptions within updateFunction to control flow when the input to updateFunction is unexpected. As such, implementers must either rethrow caught RuntimeExceptions, or not catch them in the first place. The intended behaviour of this function is that the return value of updateFunction be stored against the specified user. However, product implementations do not do this, and update the user settings in the underlying database in response to calls to the UserSettingsBuilder provided to updateFunction, and ignore the return value from updateFunction. This function will be deprecated in a future version of SAL with replacements with a more appropriate signature, or the intended behaviour, or both.

Parameters:

userKey - key of a user whose UserSettings are to be updated. If user is null or does not exist updateFunction will not be called.

updateFunction - function to update a user's UserSettings. The parameter to updateFunction is a UserSettingsBuilder whose contents match the UserSettings for the provided user.

Throws:

IllegalArgumentException - if no user could be found with that name

UnsupportedOperationException - if updateFunction creates entries with key length > MAX_KEY_LENGTH or with a String value with length > MAX_STRING_VALUE_LENGTH