1 package com.atlassian.sal.api.usersettings;
2
3 import com.atlassian.sal.api.user.UserKey;
4 import com.google.common.base.Function;
5
6 /**
7 * Service for getting and updating immutable UserSettings objects stored against a user name
8 *
9 * UserSettings can be used to store values of type String, Boolean and Long - nothing more.
10 * 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}
11 *
12 * @since 2.9
13 */
14 public interface UserSettingsService {
15
16 String USER_SETTINGS_PREFIX = "sal_";
17
18 int MAX_STRING_VALUE_LENGTH = 255;
19
20 /**
21 * Key length is limited by DB constraints.
22 */
23 int MAX_KEY_LENGTH = 200 - USER_SETTINGS_PREFIX.length();
24
25 /**
26 * Gets the UserSettings for the user with name userName.
27 *
28 * @param userName name of the user whose user settings are to be retrieved
29 * @return a UserSettings for the user with name userName,
30 * @throws IllegalArgumentException if no user could be found with that name
31 * @deprecated since 2.10, use {@link #getUserSettings(com.atlassian.sal.api.user.UserKey)} instead
32 */
33 @Deprecated
34 UserSettings getUserSettings(String userName);
35
36 /**
37 * Gets the UserSettings for the given user.
38 *
39 * @param userKey key of a user whose user settings are to be retrieved
40 * @return a UserSettings for the user with name userName,
41 * @throws IllegalArgumentException if no user could be found with that name
42 */
43 UserSettings getUserSettings(UserKey userKey);
44
45 /**
46 * Updates the UserSettings stored for this user with name UserName. Implementations of this interface will ensure
47 * that updateFunctions provided to this method are called in a threadsafe manner.
48 *
49 * Consumers can throw RuntimeExceptions within updateFunction to control flow when the input to updateFunction
50 * is unexpected. As such, implementers must either rethrow caught RuntimeExceptions, or not catch them in the first place.
51 *
52 * The intended behaviour of this function is that the return value of updateFunction be stored against the specified user.
53 * However, product implementations do not do this, and update the user settings in the underlying database in response to calls
54 * to the UserSettingsBuilder provided to updateFunction, and ignore the return value from updateFunction.
55 *
56 * @param userName name of the user whose UserSettings are to be updated. If userName does not match a known user,
57 * updateFunction will not be called.
58 * @param updateFunction function to update a user's UserSettings. The parameter to updateFunction is a
59 * UserSettingsBuilder whose contents match the UserSettings for the provided user.
60 * @throws IllegalArgumentException if no user could be found with that name
61 * @throws UnsupportedOperationException if updateFunction creates entries with key length > {@link UserSettingsService#MAX_KEY_LENGTH} or with a String value
62 * with length > {@link UserSettingsService#MAX_STRING_VALUE_LENGTH}
63 * @deprecated since 2.10, use {@link #updateUserSettings(com.atlassian.sal.api.user.UserKey, com.google.common.base.Function)} instead
64 */
65 @Deprecated
66 void updateUserSettings(String userName, Function<UserSettingsBuilder, UserSettings> updateFunction);
67
68 /**
69 * Updates the UserSettings stored for this user. Implementations of this interface will ensure that updateFunctions
70 * provided to this method are called in a threadsafe manner.
71 *
72 * Consumers can throw RuntimeExceptions within updateFunction to control flow when the input to updateFunction
73 * is unexpected. As such, implementers must either rethrow caught RuntimeExceptions, or not catch them in the first place.
74 *
75 * The intended behaviour of this function is that the return value of updateFunction be stored against the specified user.
76 * However, product implementations do not do this, and update the user settings in the underlying database in response to calls
77 * to the UserSettingsBuilder provided to updateFunction, and ignore the return value from updateFunction.
78 *
79 * This function will be deprecated in a future version of SAL with replacements with a more appropriate signature, or the
80 * intended behaviour, or both.
81 *
82 * @param userKey key of a user whose UserSettings are to be updated. If user is null or does not exist updateFunction will not be called.
83 * @param updateFunction function to update a user's UserSettings. The parameter to updateFunction is a
84 * UserSettingsBuilder whose contents match the UserSettings for the provided user.
85 * @throws IllegalArgumentException if no user could be found with that name
86 * @throws UnsupportedOperationException if updateFunction creates entries with key length > {@link UserSettingsService#MAX_KEY_LENGTH} or with a String value
87 * with length > {@link UserSettingsService#MAX_STRING_VALUE_LENGTH}
88 */
89 void updateUserSettings(UserKey userKey, Function<UserSettingsBuilder, UserSettings> updateFunction);
90 }