1 package com.atlassian.sal.api.usersettings;
2
3 import io.atlassian.fugue.Option;
4
5 import java.util.Set;
6
7 /**
8 * A builder for {@link UserSettings}
9 */
10 public interface UserSettingsBuilder {
11 /**
12 * add an extra entry to the builder, overwriting any existing value stored against key (regardless of type)
13 *
14 * @param key the key to store the value against
15 * @param value the non-null String to store, length cannot be longer than {@link UserSettingsService#MAX_KEY_LENGTH}
16 * @return this builder
17 * @throws IllegalArgumentException if value is null, or value is longer than {@link UserSettingsService#MAX_STRING_VALUE_LENGTH} characters, or key is null or longer than {@link UserSettingsService#MAX_KEY_LENGTH} characters.
18 */
19 UserSettingsBuilder put(String key, String value);
20
21 /**
22 * add an extra entry to the builder, overwriting any existing value stored against key (regardless of type)
23 *
24 * @param key the key to store the value against
25 * @param value the boolean to store
26 * @return this builder
27 * @throws IllegalArgumentException if key is null or longer than {@link UserSettingsService#MAX_KEY_LENGTH} characters.
28 */
29 UserSettingsBuilder put(String key, boolean value);
30
31 /**
32 * add an extra entry to the builder, overwriting any existing value stored against key (regardless of type)
33 *
34 * @param key the key to store the value against
35 * @param value the long to store
36 * @return this builder
37 * @throws IllegalArgumentException if key is null or longer than {@link UserSettingsService#MAX_KEY_LENGTH} characters.
38 */
39 UserSettingsBuilder put(String key, long value);
40
41 /**
42 * remove an entry from the builder
43 *
44 * @param key the key for the entry to remove
45 * @return this builder
46 * @throws IllegalArgumentException if key is null or longer than {@link UserSettingsService#MAX_KEY_LENGTH} characters.
47 */
48 UserSettingsBuilder remove(String key);
49
50 /**
51 * @param key the setting key being queried
52 * @return a {@link Option.Some Some} containing the value stored against key if one exists, a {@link com.atlassian.fugue.Option#none()}
53 * otherwise. Values can be of type String, Boolean or Long.
54 * @throws IllegalArgumentException if key is null or longer than {@link UserSettingsService#MAX_KEY_LENGTH} characters.
55 */
56 Option<Object> get(String key);
57
58 /**
59 * @return the set of keys known to this UserSettings
60 */
61 Set<String> getKeys();
62
63 /**
64 * @return an immutable UserSettings matching the contents of this builder
65 */
66 UserSettings build();
67 }