1 package com.atlassian.sal.api.usersettings;
2
3 import com.google.common.base.Function;
4
5 /**
6 * Service for getting and updating immutable UserSettings objects stored against a user name
7 *
8 * UserSettings can be used to store values of type String, Boolean and Long - nothing more.
9 * Max key length is {@link UserSettingsService#MAX_KEY_LENGTH}, Values of type String also have a max length of {@link UserSettingsService#MAX_STRING_VALUE_LENGTH}
10 *
11 * @since 2.9
12 */
13 public interface UserSettingsService
14 {
15 public static final String USER_SETTINGS_PREFIX = "sal_";
16
17 public static final int MAX_STRING_VALUE_LENGTH = 255;
18
19 /** Key length is limited by DB constraints. */
20 public static final int MAX_KEY_LENGTH = 200 - USER_SETTINGS_PREFIX.length();
21 /**
22 * Gets the UserSettings for the user with name userName
23 * @param userName name of the user whose user settings are to be retrieved
24 * @return a UserSettings for the user with name userName,
25 * @throws IllegalArgumentException if no user could be found with that name
26 */
27 UserSettings getUserSettings(String userName);
28
29 /**
30 * Updates the UserSettings stored for this user with name UserName. Implementations of this interface will ensure
31 * that updateFunctions provided to this method are called in a threadsafe manner.
32 *
33 * Consumers can throw RuntimeExceptions within updateFunction to control flow when the input to updateFunction
34 * is unexpected. As such, implementers must either rethrow caught RuntimeExceptions, or not catch them in the first place.
35 *
36 * @param userName name of the user whose UserSettings are to be updated. If userName does not match a known user,
37 * updateFunction will not be called.
38 * @param updateFunction function to update a user's UserSettings. The parameter to updateFunction is a
39 * UserSettingsBuilder whose contents match the UserSettings for the provided user. The
40 * return value of updateFunction will be stored against the specified user.
41 *
42 * @throws IllegalArgumentException if no user could be found with that name
43 * @throws UnsupportedOperationException if updateFunction creates entries with key length > {@link UserSettingsService#MAX_KEY_LENGTH} or with a String value
44 * with length > {@link UserSettingsService#MAX_STRING_VALUE_LENGTH}
45 */
46 void updateUserSettings(String userName, Function<UserSettingsBuilder, UserSettings> updateFunction);
47
48 }