1 /*
2 * Copyright (C) 2010-2014 Hamburg Sud and the contributors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.aludratest.config;
17
18 /**
19 * The basic interface for configuration data. Instances of implementing classes are passed to {@link Configurable} objects for
20 * configuration purposes.<br>
21 * The Configurable can invoke any methods declared in this interface to retrieve its required configuration, without having to
22 * deal with its storage location, overwrite issues etc. <br>
23 * Preferences based configuration is stored in a tree form, with nodes containing configuration key-value pairs as well as named
24 * subnodes. Imagine a configuration file like this:
25 *
26 * <pre>
27 * mykey=valueXY
28 * myfont/name=Arial
29 * myfont/size=12
30 * myfont/color=#ff0000
31 * </pre>
32 *
33 * Then you could access e.g. the <code>myfont/size</code> property using
34 * <code>prefs.<b>getChildNode("myfont")</b>.getFloatValue("size");</code> <br>
35 * You could even pass the <code>prefs.getChildNode("myfont")</code> node to e.g. an internal configuration method. <br>
36 * <br>
37 *
38 * One Preferences instance is <b>always</b> only used for one Configurable type, so you will not be able to retrieve the
39 * configuration of other Configurable classes via this interface. <br>
40 * <br>
41 *
42 * <b>This interface is not intended to be implemented outside AludraTest framework.</b>
43 *
44 * @author falbrech
45 *
46 */
47 public interface Preferences {
48
49 /**
50 * Returns the String representation of the given configuration key's value.
51 *
52 * @param key
53 * Configuration key to retrieve the value of.
54 *
55 * @return The value of the configuration key, as a String. <code>null</code> is returned if no value is stored.
56 */
57 public String getStringValue(String key);
58
59 /**
60 * Returns the String representation of the given configuration key's value, or the given default value when no value is
61 * stored for this key, or the stored value is <code>null</code>.
62 *
63 * @param key
64 * Configuration key to retrieve the value of.
65 * @param defaultValue
66 * The default value to return if no value is stored for the given configuration key, or the stored value is
67 * <code>null</code>.
68 * @return The value of the configuration key, as a String, or the default value.
69 */
70 public String getStringValue(String key, String defaultValue);
71
72 /**
73 * Returns the int representation of the given configuration key's value.
74 *
75 * @param key
76 * Configuration key to retrieve the value of.
77 *
78 * @return The value of the configuration key, as an int. <code>0</code> is returned if no value is stored, or the stored
79 * String is <code>null</code>.
80 */
81 public int getIntValue(String key);
82
83 /**
84 * Returns the int representation of the given configuration key's value, or the given default value when no value is stored
85 * for this key, or the stored String form of the value is <code>null</code>.
86 *
87 * @param key
88 * Configuration key to retrieve the value of.
89 * @param defaultValue
90 * The default value to return if no value is stored for the given configuration key, or if the stored String form
91 * of the value is <code>null</code>.
92 * @return The value of the configuration key, as an int, or the default value.
93 */
94 public int getIntValue(String key, int defaultValue);
95
96 /**
97 * Returns the boolean representation of the given configuration key's value.
98 *
99 * @param key
100 * Configuration key to retrieve the value of.
101 *
102 * @return The value of the configuration key, as a boolean. <code>false</code> is returned if no value is stored, or the
103 * stored String is <code>null</code>.
104 */
105 public boolean getBooleanValue(String key);
106
107 /**
108 * Returns the boolean representation of the given configuration key's value, or the given default value when no value is
109 * stored for this key, or the stored String form of the value is <code>null</code>.
110 *
111 * @param key
112 * Configuration key to retrieve the value of.
113 * @param defaultValue
114 * The default value to return if no value is stored for the given configuration key, or if the stored String form
115 * of the value is <code>null</code>.
116 * @return The value of the configuration key, as a boolean, or the default value.
117 */
118 public boolean getBooleanValue(String key, boolean defaultValue);
119
120 /**
121 * Returns the float representation of the given configuration key's value.
122 *
123 * @param key
124 * Configuration key to retrieve the value of.
125 *
126 * @return The value of the configuration key, as a float. <code>0</code> is returned if no value is stored, or the stored
127 * String is <code>null</code>.
128 */
129 public float getFloatValue(String key);
130
131 /**
132 * Returns the float representation of the given configuration key's value, or the given default value when no value is stored
133 * for this key, or the stored String form of the value is <code>null</code>.
134 *
135 * @param key
136 * Configuration key to retrieve the value of.
137 * @param defaultValue
138 * The default value to return if no value is stored for the given configuration key, or if the stored String form
139 * of the value is <code>null</code>.
140 * @return The value of the configuration key, as a float, or the default value.
141 */
142 public float getFloatValue(String key, float defaultValue);
143
144 /**
145 * Returns the double representation of the given configuration key's value.
146 *
147 * @param key
148 * Configuration key to retrieve the value of.
149 *
150 * @return The value of the configuration key, as a double. <code>0</code> is returned if no value is stored, or the stored
151 * String is <code>null</code>.
152 */
153 public double getDoubleValue(String key);
154
155 /**
156 * Returns the double representation of the given configuration key's value, or the given default value when no value is
157 * stored for this key, or the stored String form of the value is <code>null</code>.
158 *
159 * @param key
160 * Configuration key to retrieve the value of.
161 * @param defaultValue
162 * The default value to return if no value is stored for the given configuration key, or if the stored String form
163 * of the value is <code>null</code>.
164 * @return The value of the configuration key, as a double, or the default value.
165 */
166 public double getDoubleValue(String key, double defaultValue);
167
168 /**
169 * Returns the char representation of the given configuration key's value.
170 *
171 * @param key
172 * Configuration key to retrieve the value of.
173 *
174 * @return The value of the configuration key, as a char. <code>'\0'</code> is returned if no value is stored, or the stored
175 * String is <code>null</code>. If a longer String is stored, only the first character is returned.
176 */
177 public char getCharValue(String key);
178
179 /**
180 * Returns the char representation of the given configuration key's value, or the given default value when no value is stored
181 * for this key, or the stored String form of the value is <code>null</code>.
182 *
183 * @param key
184 * Configuration key to retrieve the value of.
185 * @param defaultValue
186 * The default value to return if no value is stored for the given configuration key, or if the stored String form
187 * of the value is <code>null</code>.
188 * @return The value of the configuration key, as a char, or the default value.
189 */
190 public char getCharValue(String key, char defaultValue);
191
192 /**
193 * Returns the available configuration key names on this Preferences node.
194 *
195 * @return The available configuration key names on this Preferences node, possibly an empty array, but never
196 * <code>null</code>.
197 */
198 public String[] getKeyNames();
199
200 /**
201 * Returns the configuration child node with the given name, or <code>null</code> if no such node exists on this configuration
202 * node.
203 *
204 * @param name
205 * Name of the configuration child node
206 *
207 * @return The configuration child node with the given name, or <code>null</code> if no such node exists on this configuration
208 * node.
209 */
210 public Preferences getChildNode(String name);
211
212 /**
213 * Returns the names of the available configuration child nodes on this configuration node.
214 *
215 * @return The names of the available configuration child nodes on this configuration node, possibly an empty Array, but never
216 * <code>null</code>.
217 */
218 public String[] getChildNodeNames();
219
220
221 }