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