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