Parameters xref

View Javadoc

1   //
2   //Copyright (c) 2003, Caltha - Gajda, Krzewski, Mach, Potempski Sp.J.
3   //All rights reserved.
4   //
5   //Redistribution and use in source and binary forms, with or without modification, 
6   //are permitted provided that the following conditions are met:
7   //
8   //* Redistributions of source code must retain the above copyright notice, 
9   //this list of conditions and the following disclaimer.
10  //* Redistributions in binary form must reproduce the above copyright notice, 
11  //this list of conditions and the following disclaimer in the documentation 
12  //and/or other materials provided with the distribution.
13  //* Neither the name of the Caltha - Gajda, Krzewski, Mach, Potempski Sp.J. 
14  //nor the names of its contributors may be used to endorse or promote products 
15  //derived from this software without specific prior written permission.
16  //
17  //THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
18  //AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
19  //WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20  //IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
21  //INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
22  //BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
23  //OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
24  //WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
25  //ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
26  //POSSIBILITY OF SUCH DAMAGE.
27  //
28  
29  package org.objectledge.parameters;
30  
31  import java.util.Date;
32  import java.util.Set;
33  
34  /**
35   * A container of parameters.
36   *
37   *
38   * @author <a href="mailto:pablo@caltha.com">Pawel Potempski</a>
39   * @version $Id: Parameters.java,v 1.14 2005/12/20 09:09:32 pablo Exp $
40   */
41  public interface Parameters
42  {
43      /***
44       * Return the parameter with specified name. 
45       * 
46       * @param name the name of the parameter.
47       * @return the string value of the parameter.
48       */
49      public String get(String name);
50  
51      /***
52       * Return the parameter with specified name. 
53       * 
54       * @param name the name of the parameter.
55       * @param defaultValue the default value of the parameter.
56       * @return the string value of the parameter.
57       */
58      public String get(String name, String defaultValue);
59  
60      /***
61       * Return all values of the parameter with specified name as an array. 
62       * 
63       * @param name the name of the parameters.
64       * @return the array of the string values of the parameter.
65      */
66      public String[] getStrings(String name);
67  
68      /***
69       * Return the parameter with specified name. 
70       * 
71       * @param name the name of the parameter.
72       * @return the boolean value of the parameter.
73       */
74      public boolean getBoolean(String name);
75  
76      /***
77       * Return the parameter with specified name. 
78       * 
79       * @param name the name of the parameter.
80       * @param defaultValue the default value of the parameter.
81       * @return the boolean value of the parameter.
82       */
83      public boolean getBoolean(String name, boolean defaultValue);
84  
85  	/***
86  	 * Return all values of the parameter with specified name as an array. 
87  	 * 
88  	 * @param name the name of the parameters.
89  	 * @return the array of the boolean values of the parameter.
90  	*/
91  	public boolean[] getBooleans(String name);
92  
93      /***
94       * Return the parameter with specified name.
95       * The assumed String value of this parameter is a decimal representation of a Unix time-stamp.
96       * 
97       * @param name the name of the parameter.
98       * @return the date value of the parameter.
99       */
100     public Date getDate(String name);
101 
102     /***
103      * Return the parameter with specified name. 
104      * The assumed String value of this parameter is a decimal representation of a Unix time-stamp.
105      * 
106      * @param name the name of the parameter.
107      * @param defaultValue the default value of the parameter.
108      * @return the date value of the parameter.
109      */
110     public Date getDate(String name, Date defaultValue);
111 
112     /***
113      * Return all values of the parameter with specified name as an array. 
114      * The assumed String values of this parameter is are decimal representations of Unix
115      * time-stamps.
116      * 
117      * @param name the name of the parameters.
118      * @return the array of the date values of the parameter.
119     */
120     public Date[] getDates(String name);
121 
122     /***
123      * Return the parameter with specified name. 
124      * 
125      * @param name the name of the parameter.
126      * @return the float value of the parameter.
127      * @throws NumberFormatException if parameter is not a number.
128      */
129     public float getFloat(String name) throws NumberFormatException;
130 
131     /***
132      * Return the parameter with specified name. 
133      * 
134      * @param name the name of the parameter.
135      * @param defaultValue the default value of the parameter.
136      * @return the float value of the parameter.
137      */
138     public float getFloat(String name, float defaultValue);
139 
140 	/***
141 	 * Return all values of the parameter with specified name as an array. 
142 	 * 
143 	 * @param name the name of the parameters.
144 	 * @return the array of the float values of the parameter.
145 	 * @throws NumberFormatException if anyone of the values is not a number. 
146 	*/
147 	public float[] getFloats(String name) throws NumberFormatException;
148 
149     /***
150      * Return the parameter with specified name. 
151      * 
152      * @param name the name of the parameter.
153      * @return the integer value of the parameter.
154      * @throws NumberFormatException if parameter is not a number.
155      */
156     public int getInt(String name) throws NumberFormatException;
157 
158     /***
159      * Return the parameter with specified name. 
160      * 
161      * @param name the name of the parameter.
162      * @param defaultValue the default value of the parameter.
163      * @return the integer value of the parameter.
164      */
165     public int getInt(String name, int defaultValue);
166 
167 	/***
168 	 * Return all values of the parameter with specified name as an array. 
169 	 * 
170 	 * @param name the name of the parameters.
171 	 * @return the array of the integer values of the parameter.
172 	 * @throws NumberFormatException if anyone of the values is not a number.
173 	*/
174 	public int[] getInts(String name) throws NumberFormatException;
175 
176     /***
177      * Return the parameter with specified name. 
178      * 
179      * @param name the name of the parameter.
180      * @return the integer value of the parameter.
181      * @throws NumberFormatException if parameter is not a number.
182      */
183     public long getLong(String name) throws NumberFormatException;
184 
185 	/***
186 	 * Return the parameter as array of long values. 
187 	 * 
188 	 * @param name the name of the parameter.
189 	 * @return the array of parameter values.
190 	 * @throws NumberFormatException if parameter is not a number.
191 	 */
192 	public long[] getLongs(String name) throws NumberFormatException;
193 
194     /***
195      * Return the parameter with specified name. 
196      * 
197      * @param name the name of the parameter.
198      * @param defaultValue the default value of the parameter.
199      * @return the integer value of the parameter.
200      */
201     public long getLong(String name, long defaultValue);
202 
203     /***
204      * Return the names of all parameters.
205      * 
206      * @return the parameter names.
207      */
208     public String[] getParameterNames();
209 
210     /***
211      * Checks whether parameter is defined.
212      * 
213      * @param name the name of the parameter.
214      * @return <code>true</code> if parameter is defined.
215      */
216     public boolean isDefined(String name);
217 
218     /***
219      * Remove all parameters.
220      */
221     public void remove();
222 
223     /***
224      * Remove all parameters with a specified name.
225      *
226      * @param name the parameter name.
227      */
228     public void remove(String name);
229     
230     /***
231      * Remove all parameters with a specified name and string value.
232      *
233      * @param name the parameter name.
234      * @param value the parameter value.
235      */
236     public void remove(String name, String value);
237     
238     /***
239      * Remove all parameters with a specified name and value.
240      *
241      * @param name the parameter name.
242      * @param value the parameter value.
243      */
244     public void remove(String name, Date value);
245 
246     /***
247 	 * Remove all parameters with a specified name and value.
248 	 *
249 	 * @param name the parameter name.
250 	 * @param value the parameter value.
251 	 */
252 	public void remove(String name, float value);
253     
254 	/***
255 	 * Remove all parameters with a specified name and value.
256 	 *
257 	 * @param name the parameter name.
258 	 * @param value the parameter value.
259 	 */
260 	public void remove(String name, int value);
261         
262 	/***
263 	 * Remove all parameters with a specified name and value.
264 	 *
265 	 * @param name the parameter name.
266 	 * @param value the parameter value.
267 	 */
268 	public void remove(String name, long value);
269 	
270 	/***
271 	 * Remove all parameters with a name contained in given set.
272 	 *
273 	 * @param keys the set of keys.
274 	 */
275 	public void remove(Set<String> keys);
276 	
277 	/***
278 	 * Remove all except those with a keys specified in the set.
279 	 *
280 	 * @param keys the set of names.
281 	 */
282 	public void removeExcept(Set<String> keys);
283     
284     /***
285      * Set the parameter.
286      * 
287      * @param name the parameter name.
288      * @param value the parameter value.
289      */
290     public void set(String name, String value);
291     
292 	/***
293 	 * Set the parameter.
294 	 * 
295 	 * @param name the parameter name.
296 	 * @param values the parameter values.
297 	 */
298 	public void set(String name, String[] values);
299     
300 	/***
301 	 * Reset state to equal with given parameters.
302 	 * 
303 	 * @param parameters the source parameters.
304 	 */
305 	public void set(Parameters parameters);
306 	
307 	/***
308      * Set the parameter.
309      * 
310      * @param name the parameter name.
311      * @param value the parameter value.
312      */
313     public void set(String name, boolean value);
314 
315 	/***
316 	 * Set the parameter.
317 	 * 
318 	 * @param name the parameter name.
319 	 * @param values the parameter values.
320 	 */
321 	public void set(String name, boolean[] values);
322 
323 
324     /***
325      * Set the parameter.
326      * 
327      * @param name the parameter name.
328      * @param value the parameter value.
329      */
330     public void set(String name, Date value);
331 
332     /***
333      * Set the parameter.
334      * 
335      * @param name the parameter name.
336      * @param values the parameter values.
337      */
338     public void set(String name, Date[] values);
339     
340     /***
341      * Set the parameter.
342      * 
343      * @param name the parameter name.
344      * @param value the parameter value.
345      */
346     public void set(String name, float value);
347 
348 	/***
349 	 * Set the parameter.
350 	 * 
351 	 * @param name the parameter name.
352 	 * @param values the parameter values.
353 	 */
354 	public void set(String name, float[] values);
355 
356     /***
357      * Set the parameter.
358      * 
359      * @param name the parameter name.
360      * @param value the parameter value.
361      */
362     public void set(String name, int value);
363 
364 	/***
365 	 * Set the parameter.
366 	 * 
367 	 * @param name the parameter name.
368 	 * @param values the parameter values.
369 	 */
370 	public void set(String name, int[] values);
371 
372     /***
373      * Set the parameter.
374      * 
375      * @param name the parameter name.
376      * @param value the parameter value.
377      */
378     public void set(String name, long value);
379     
380 	/***
381 	 * Set the parameter.
382 	 * 
383 	 * @param name the parameter name.
384 	 * @param values the parameter values.
385 	 */
386 	public void set(String name, long[] values);
387 
388     /***
389      * Add the parameter.
390      *
391      * @param name the parameter name.
392      * @param value the parameter value.
393      */
394     public void add(String name, String value);
395     
396 	/***
397 	 * Add the parameter.
398 	 *
399 	 * @param name the parameter name.
400 	 * @param values the parameter values.
401 	 */
402 	public void add(String name, String[] values);
403 
404     /***
405      * Add the parameter.
406      *
407      * @param name the parameter name.
408      * @param value the parameter value.
409      */
410     public void add(String name, boolean value);
411     
412 	/***
413 	 * Add the parameter.
414 	 *
415 	 * @param name the parameter name.
416 	 * @param values the parameter values.
417 	 */
418 	public void add(String name, boolean[] values);
419 
420     /***
421      * Add the parameter.
422      *
423      * @param name the parameter name.
424      * @param value the parameter value.
425      */
426     public void add(String name, Date value);
427     
428     /***
429      * Add the parameter.
430      *
431      * @param name the parameter name.
432      * @param values the parameter values.
433      */
434     public void add(String name, Date[] values);
435 
436     /***
437      * Add the parameter.
438      *
439      * @param name the parameter name.
440      * @param value the parameter value.
441      */
442     public void add(String name, float value);
443     
444 	/***
445 	 * Add the parameter.
446 	 *
447 	 * @param name the parameter name.
448 	 * @param values the parameter values.
449 	 */
450 	public void add(String name, float[] values);
451 
452     /***
453      * Add the parameter.
454      *
455      * @param name the parameter name.
456      * @param value the parameter value.
457      */
458     public void add(String name, int value);
459     
460 	/***
461 	 * Add the parameter.
462 	 *
463 	 * @param name the parameter name.
464 	 * @param values the parameter values.
465 	 */
466 	public void add(String name, int[] values);
467 
468     /***
469      * Add the parameter.
470      *
471      * @param name the parameter name.
472      * @param value the parameter value.
473      */
474     public void add(String name, long value);
475 
476 	/***
477 	 * Add the parameter.
478 	 *
479 	 * @param name the parameter name.
480 	 * @param values the parameter values.
481 	 */
482 	public void add(String name, long[] values);
483 	
484     /***
485      * Adds all parameters from another container to this container.
486      *
487      * If overwrite is set to <code>true</code> all conflicting 
488      * parameters from this container will be replaced,
489      * otherwise all parameters from another container will be added.   
490      *
491      * @param parameters the parameters object.
492      * @param overwrite the overwrite switch.
493      */
494     public void add(Parameters parameters, boolean overwrite);
495 
496     /***
497      * Returns the contained properties as a parsable String.
498      *
499      * @return parsable String representation of the contained properties.
500      */
501     public String toString();
502 
503     /***
504      * Return a parameters object that represents a subset of parameters with specified prefix.
505      * 
506      * @param prefix the prefix. 
507      * @return the nested parameters object.
508      */
509     public Parameters getChild(String prefix);
510 
511 }