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 writes of keys upto 100 characters in length
20 * and are expected to throw an exception if the key is longer than 255 characters.
21 * Keys should be kept as short as possible.
22 *
23 * Reads and removes must support keys longer than 256 characters.
24 * <p/>
25 * Instances are assumed to be not threadsafe and mutable.
26 *
27 * @since 2.0
28 */
29 public interface PluginSettings
30 {
31 /**
32 * Gets a setting value. The setting returned should be specific to this context settings object and not cascade
33 * the value to a global context.
34 *
35 * @param key The setting key. Cannot be null
36 * @return The setting value. May be null
37 * @throws IllegalArgumentException if the key is null.
38 */
39 Object get(String key);
40
41 /**
42 * Puts a setting value.
43 *
44 * @param key Setting key. Cannot be null, keys longer than 100 characters are not supported.
45 * @param value Setting value. Must be one of {@link String}, {@link List}, {@link Properties}, {@link Map}, or null.
46 * null will remove the item from the settings. If the value is a {@link String} it should not be longer
47 * than 99000 characters long. Values of a type other than {@link String} will be serialized as a
48 * {@link String} which cannot be longer than 99000 characters long.
49 * @return The setting value that was over ridden. Null if none existed.
50 * @throws IllegalArgumentException if value is not null, {@link String}, {@link List}, {@link Properties} or {@link Map},
51 * or if the key is null or longer than 255 characters
52 */
53 Object put(String key, Object value);
54
55 /**
56 * Removes a setting value
57 *
58 * @param key The setting key
59 * @return The setting value that was removed. Null if nothing was removed.
60 * @throws IllegalArgumentException if the key is null.
61 */
62 Object remove(String key);
63 }