1 package com.atlassian.sal.api.pluginsettings;
2
3 import java.util.List;
4 import java.util.Map;
5 import java.util.Properties;
6
7 /**
8 * Provides access to settings globally or per project/space/repository/build-plan
9 * <p/>
10 * The following types are supported:
11 * <ul>
12 * <li>java.lang.String</li>
13 * <li>java.util.List</li>
14 * <li>java.util.Properties</li>
15 * <li>java.util.Map</li>
16 * </ul>
17 * {@link List} and {@link Map} types must contain only {@link String}.
18 * <p/>
19 * Implementations are only required to support keys up to 100 characters long. Some may support up to 255
20 * characters, but keys should be kept as short as possible.
21 * <p/>
22 * Instances are assumed to be not threadsafe and mutable.
23 *
24 * @since 2.0
25 */
26 public interface PluginSettings
27 {
28 /**
29 * Gets a setting value. The setting returned should be specific to this context settings object and not cascade
30 * the value to a global context.
31 *
32 * @param key The setting key. Cannot be null
33 * @return The setting value. May be null
34 * @throws IllegalArgumentException if the key is null or longer than 100 characters
35 */
36 Object get(String key);
37
38 /**
39 * Puts a setting value.
40 *
41 * @param key Setting key. Cannot be null
42 * @param value Setting value. Must be one of {@link String}, {@link List}, {@link Properties}, {@link Map}, or null.
43 * null will remove the item from the settings.
44 * @return The setting value that was over ridden. Null if none existed.
45 * @throws IllegalArgumentException if value is not {@link String}, {@link List}, {@link Properties}, {@link Map},
46 * or null, or if the key is null or longer than 100 characters
47 */
48 Object put(String key, Object value);
49
50 /**
51 * Removes a setting value
52 *
53 * @param key The setting key
54 * @return The setting value that was removed. Null if nothing was removed.
55 * @throws IllegalArgumentException if the key is null or longer than 100 characters
56 */
57 Object remove(String key);
58 }