1 /*
2 * Copyright (c) 2003-2008 by Cosylab d. d.
3 *
4 * This file is part of Java-Common.
5 *
6 * Java-Common is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * Java-Common is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with Java-Common. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 package com.cosylab.application.state;
21
22 import java.awt.Color;
23 import java.awt.Dimension;
24 import java.awt.Font;
25 import java.awt.Rectangle;
26
27 import java.io.IOException;
28 import java.io.Writer;
29
30 import java.util.Set;
31
32
33 /**
34 * This interface should be implemented by the object which will be exchanged
35 * with a component in the state saving/restoring process. This is basically
36 * <code>java.util.Properties</code> with extension for other useful types of
37 * objects that are not strings. A <code>State</code> can be used to create
38 * and store other <code>State</code> object as well and in such way the
39 * hierarchy can be builded easily. For example a component can use this code
40 * snippet to produce a <code>State</code> object which has two child object
41 * 'Window' and 'Splitter'. This allows the component to easy distinguish
42 * between parts of the state later in process of restoring.
43 * <pre>
44 * <code>
45 * public State getState() {
46 * State state = StateFactory.createState();
47 * State s = state.createChild("Window");
48 * getWindow().setProperties(s);
49 * s = state.createChild("Splitter");
50 * getSplitter().setProperties(s);
51 * }
52 * </code>
53 * </pre>
54 * Beside that the enumeration of stored objects is added to allow different
55 * <code>StateStorage</code> objects to iterate over.
56 *
57 * @author dvitas
58 */
59 public interface State
60 {
61 /**
62 * Adds child State with given key.
63 *
64 * @param key the key under state is stored
65 * @param state the state to be added
66 */
67 public void putState(String key, State state);
68
69 /**
70 * Creates new child and adds it to contaiment with provided key.
71 *
72 * @param key the key of new state inside this containment
73 *
74 * @return new state contained with provided key
75 */
76 public State createState(String key);
77
78 /**
79 * DOCUMENT ME!
80 *
81 * @param key DOCUMENT ME!
82 * @param defaultValue DOCUMENT ME!
83 *
84 * @return DOCUMENT ME!
85 */
86 public boolean getBoolean(String key, boolean defaultValue);
87
88 /**
89 * DOCUMENT ME!
90 *
91 * @param key DOCUMENT ME!
92 *
93 * @return DOCUMENT ME!
94 */
95 public State getState(String key);
96
97 /**
98 * DOCUMENT ME!
99 *
100 * @param key DOCUMENT ME!
101 *
102 * @return DOCUMENT ME!
103 */
104 public Class getClass(String key);
105
106 /**
107 * DOCUMENT ME!
108 *
109 * @param key DOCUMENT ME!
110 *
111 * @return DOCUMENT ME!
112 */
113 public Color getColor(String key);
114
115 public Color[] getColorSeq(String key);
116
117 /**
118 * DOCUMENT ME!
119 *
120 * @param key DOCUMENT ME!
121 *
122 * @return DOCUMENT ME!
123 */
124 public Dimension getDimension(String key);
125
126 /**
127 * DOCUMENT ME!
128 *
129 * @param key DOCUMENT ME!
130 * @param defaultValue DOCUMENT ME!
131 *
132 * @return DOCUMENT ME!
133 */
134 public double getDouble(String key, double defaultValue);
135
136 /**
137 * DOCUMENT ME!
138 *
139 * @param key DOCUMENT ME!
140 *
141 * @return DOCUMENT ME!
142 */
143 public double[] getDoubleSeq(String key);
144
145 /**
146 * DOCUMENT ME!
147 *
148 * @param key DOCUMENT ME!
149 *
150 * @return DOCUMENT ME!
151 */
152 public Font getFont(String key);
153
154 public Font[] getFontSeq(String key);
155
156 /**
157 * Returns ID, which is used to distinguish different states.
158 *
159 * @return state identification
160 */
161 public String getID();
162
163 /**
164 * Sets ID to state.
165 *
166 * @param id the new ID string
167 */
168 public void setID(String id);
169
170 /**
171 * DOCUMENT ME!
172 *
173 * @param key DOCUMENT ME!
174 * @param defaultValue DOCUMENT ME!
175 *
176 * @return DOCUMENT ME!
177 */
178 public int getInt(String key, int defaultValue);
179
180 /**
181 * DOCUMENT ME!
182 *
183 * @param key DOCUMENT ME!
184 *
185 * @return DOCUMENT ME!
186 */
187 public int[] getIntSeq(String key);
188
189 /**
190 * DOCUMENT ME!
191 *
192 * @param key DOCUMENT ME!
193 *
194 * @return DOCUMENT ME!
195 */
196 public Object getObject(String key);
197
198 /**
199 * DOCUMENT ME!
200 *
201 * @param key DOCUMENT ME!
202 *
203 * @return DOCUMENT ME!
204 */
205 public Class getType(String key);
206
207 // convinient types
208 public Rectangle getRectangle(String key);
209
210 // basic types
211 public String getString(String key, String defaultValue);
212
213 // sequences
214 public String[] getStringSeq(String key);
215
216 // listing
217 public Set keySet();
218
219 /**
220 * DOCUMENT ME!
221 *
222 * @param key DOCUMENT ME!
223 * @param value DOCUMENT ME!
224 */
225 public void putBoolean(String key, boolean value);
226
227 /**
228 * DOCUMENT ME!
229 *
230 * @param key DOCUMENT ME!
231 * @param value DOCUMENT ME!
232 */
233 public void putClass(String key, Class value);
234
235 /**
236 * DOCUMENT ME!
237 *
238 * @param key DOCUMENT ME!
239 * @param value DOCUMENT ME!
240 */
241 public void putColor(String key, Color value);
242
243 public void putColorSeq(String key, Color[] value);
244
245 /**
246 * DOCUMENT ME!
247 *
248 * @param key DOCUMENT ME!
249 * @param value DOCUMENT ME!
250 */
251 public void putDimension(String key, Dimension value);
252
253 /**
254 * DOCUMENT ME!
255 *
256 * @param key DOCUMENT ME!
257 * @param value DOCUMENT ME!
258 */
259 public void putDouble(String key, double value);
260
261 /**
262 * DOCUMENT ME!
263 *
264 * @param key DOCUMENT ME!
265 * @param value DOCUMENT ME!
266 */
267 public void putDoubleSeq(String key, double[] value);
268
269 /**
270 * DOCUMENT ME!
271 *
272 * @param key DOCUMENT ME!
273 * @param value DOCUMENT ME!
274 */
275 public void putFont(String key, Font value);
276
277 public void putFontSeq(String key, Font[] value);
278
279 /**
280 * DOCUMENT ME!
281 *
282 * @param key DOCUMENT ME!
283 * @param value DOCUMENT ME!
284 */
285 public void putInt(String key, int value);
286
287 /**
288 * DOCUMENT ME!
289 *
290 * @param key DOCUMENT ME!
291 * @param value DOCUMENT ME!
292 */
293 public void putIntSeq(String key, int[] value);
294
295 /**
296 * DOCUMENT ME!
297 *
298 * @param key DOCUMENT ME!
299 * @param value DOCUMENT ME!
300 */
301 public void putRectangle(String key, Rectangle value);
302
303 /**
304 * DOCUMENT ME!
305 *
306 * @param key DOCUMENT ME!
307 * @param value DOCUMENT ME!
308 */
309 public void putString(String key, String value);
310
311 /**
312 * DOCUMENT ME!
313 *
314 * @param key DOCUMENT ME!
315 * @param value DOCUMENT ME!
316 */
317 public void putStringSeq(String key, String[] value);
318
319 /**
320 * DOCUMENT ME!
321 *
322 * @param writer DOCUMENT ME!
323 *
324 * @throws IOException DOCUMENT ME!
325 */
326 public void writeXML(Writer writer) throws IOException;
327 }
328
329 /* __oOo__ */