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 255, Values of type String also have a max length of 255.
10 *
11 * @since 2.9
12 */
13 public interface UserSettingsService
14 {
15 /**
16 * Gets the UserSettings for the user with name userName
17 * @param userName name of the user whose user settings are to be retrieved
18 * @return a UserSettings for the user with name userName,
19 * @throws IllegalArgumentException if no user could be found with that name
20 */
21 UserSettings getUserSettings(String userName);
22
23 /**
24 * Updates the UserSettings stored for this user with name UserName. Implementations of this interface will ensure
25 * that updateFunctions provided to this method are called in a threadsafe manner.
26 *
27 * Consumers can throw RuntimeExceptions within updateFunction to control flow when the input to updateFunction
28 * is unexpected. As such, implementers must either rethrow caught RuntimeExceptions, or not catch them in the first place.
29 *
30 * @param userName name of the user whose UserSettings are to be updated. If userName does not match a known user,
31 * updateFunction will not be called.
32 * @param updateFunction function to update a user's UserSettings. The parameter to updateFunction is a
33 * UserSettingsBuilder whose contents match the UserSettings for the provided user. The
34 * return value of updateFunction will be stored against the specified user.
35 *
36 * @throws IllegalArgumentException if no user could be found with that name
37 * @throws UnsupportedOperationException if updateFunction creates entries with key length > 255 or with a String value
38 * with length > 255
39 */
40 void updateUserSettings(String userName, Function<UserSettingsBuilder, UserSettings> updateFunction);
41
42 }