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 * Gets a setting value. The setting returned should be specific to this context settings object and not cascade
32 * the value to a global context.
33 *
34 * @param key The setting key. Cannot be null
35 * @return The setting value. May be null
36 * @throws IllegalArgumentException if the key is null.
37 */
38 Object get(String key);
39
40 /**
41 * Puts a setting value.
42 *
43 * @param key Setting key. Cannot be null, keys longer than 100 characters are not supported.
44 * @param value Setting value. Must be one of {@link String}, {@link List}, {@link Properties}, {@link Map}, or null.
45 * null will remove the item from the settings. If the value is a {@link String} it should not be longer
46 * than 99000 characters long. Values of a type other than {@link String} will be serialized as a
47 * {@link String} which cannot be longer than 99000 characters long.
48 * @return The setting value that was over ridden. Null if none existed.
49 * @throws IllegalArgumentException if value is not null, {@link String}, {@link List}, {@link Properties} or {@link Map},
50 * or if the key is null or longer than 255 characters
51 */
52 Object put(String key, Object value);
53
54 /**
55 * Removes a setting value
56 *
57 * @param key The setting key
58 * @return The setting value that was removed. Null if nothing was removed.
59 * @throws IllegalArgumentException if the key is null.
60 */
61 Object remove(String key);
62 }