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