Merge branch 'subtree'
[fanfix.git] / src / be / nikiroo / utils / resources / Bundle.java
... / ...
CommitLineData
1package be.nikiroo.utils.resources;
2
3import java.io.BufferedWriter;
4import java.io.File;
5import java.io.FileInputStream;
6import java.io.FileOutputStream;
7import java.io.IOException;
8import java.io.InputStreamReader;
9import java.io.OutputStreamWriter;
10import java.io.Reader;
11import java.io.Writer;
12import java.lang.reflect.Field;
13import java.util.ArrayList;
14import java.util.HashMap;
15import java.util.List;
16import java.util.Locale;
17import java.util.Map;
18import java.util.MissingResourceException;
19import java.util.PropertyResourceBundle;
20import java.util.ResourceBundle;
21
22import be.nikiroo.utils.resources.Meta.Format;
23
24/**
25 * This class encapsulate a {@link ResourceBundle} in UTF-8. It allows to
26 * retrieve values associated to an enumeration, and allows some additional
27 * methods.
28 * <p>
29 * It also sports a writable change map, and you can save back the
30 * {@link Bundle} to file with {@link Bundle#updateFile(String)}.
31 *
32 * @param <E>
33 * the enum to use to get values out of this class
34 *
35 * @author niki
36 */
37
38public class Bundle<E extends Enum<E>> {
39 /** The type of E. */
40 protected Class<E> type;
41 /**
42 * The {@link Enum} associated to this {@link Bundle} (all the keys used in
43 * this {@link Bundle} will be of this type).
44 */
45 protected Enum<?> keyType;
46
47 private TransBundle<E> descriptionBundle;
48
49 /** R/O map */
50 private Map<String, String> map;
51 /** R/W map */
52 private Map<String, String> changeMap;
53
54 /**
55 * Create a new {@link Bundles} of the given name.
56 *
57 * @param type
58 * a runtime instance of the class of E
59 * @param name
60 * the name of the {@link Bundles}
61 * @param descriptionBundle
62 * the description {@link TransBundle}, that is, a
63 * {@link TransBundle} dedicated to the description of the values
64 * of the given {@link Bundle} (can be NULL)
65 */
66 protected Bundle(Class<E> type, Enum<?> name,
67 TransBundle<E> descriptionBundle) {
68 this.type = type;
69 this.keyType = name;
70 this.descriptionBundle = descriptionBundle;
71
72 this.map = new HashMap<String, String>();
73 this.changeMap = new HashMap<String, String>();
74 setBundle(name, Locale.getDefault(), false);
75 }
76
77 /**
78 * Check if the setting is set into this {@link Bundle}.
79 *
80 * @param id
81 * the id of the setting to check
82 * @param includeDefaultValue
83 * TRUE to only return false when the setting is not set AND
84 * there is no default value
85 *
86 * @return TRUE if the setting is set
87 */
88 public boolean isSet(E id, boolean includeDefaultValue) {
89 return isSet(id.name(), includeDefaultValue);
90 }
91
92 /**
93 * Check if the setting is set into this {@link Bundle}.
94 *
95 * @param name
96 * the id of the setting to check
97 * @param includeDefaultValue
98 * TRUE to only return false when the setting is explicitly set
99 * to NULL (and not just "no set") in the change maps
100 *
101 * @return TRUE if the setting is set
102 */
103 protected boolean isSet(String name, boolean includeDefaultValue) {
104 if (getString(name, null) == null) {
105 if (!includeDefaultValue || getString(name, "") == null) {
106 return false;
107 }
108 }
109
110 return true;
111 }
112
113 /**
114 * Return the value associated to the given id as a {@link String}.
115 *
116 * @param id
117 * the id of the value to get
118 *
119 * @return the associated value, or NULL if not found (not present in the
120 * resource file)
121 */
122 public String getString(E id) {
123 return getString(id, null);
124 }
125
126 /**
127 * Return the value associated to the given id as a {@link String}.
128 * <p>
129 * If no value is associated, take the default one if any.
130 *
131 * @param id
132 * the id of the value to get
133 * @param def
134 * the default value when it is not present in the config file
135 *
136 * @return the associated value, or <tt>def</tt> if not found (not present
137 * in the resource file)
138 */
139 public String getString(E id, String def) {
140 return getString(id, def, -1);
141 }
142
143 /**
144 * Return the value associated to the given id as a {@link String}.
145 * <p>
146 * If no value is associated (or if it is empty!), take the default one if
147 * any.
148 *
149 * @param id
150 * the id of the value to get
151 * @param def
152 * the default value when it is not present in the config file
153 * @param item
154 * the item number to get for an array of values, or -1 for
155 * non-arrays
156 *
157 * @return the associated value, <tt>def</tt> if not found (not present in
158 * the resource file) or NULL if the item is specified (not -1) and
159 * does not exist
160 */
161 public String getString(E id, String def, int item) {
162 String rep = getString(id.name(), null);
163 if (rep == null) {
164 rep = getMetaDef(id.name());
165 }
166
167 if (rep.isEmpty()) {
168 return def;
169 }
170
171 if (item >= 0) {
172 List<String> values = BundleHelper.parseList(rep, item);
173 if (values != null && item < values.size()) {
174 return values.get(item);
175 }
176
177 return null;
178 }
179
180 return rep;
181 }
182
183 /**
184 * Set the value associated to the given id as a {@link String}.
185 *
186 * @param id
187 * the id of the value to set
188 * @param value
189 * the value
190 *
191 */
192 public void setString(E id, String value) {
193 setString(id.name(), value);
194 }
195
196 /**
197 * Set the value associated to the given id as a {@link String}.
198 *
199 * @param id
200 * the id of the value to set
201 * @param value
202 * the value
203 * @param item
204 * the item number to get for an array of values, or -1 for
205 * non-arrays
206 *
207 */
208 public void setString(E id, String value, int item) {
209 if (item < 0) {
210 setString(id.name(), value);
211 } else {
212 List<String> values = getList(id);
213 setString(id.name(), BundleHelper.fromList(values, value, item));
214 }
215 }
216
217 /**
218 * Return the value associated to the given id as a {@link String} suffixed
219 * with the runtime value "_suffix" (that is, "_" and suffix).
220 * <p>
221 * Will only accept suffixes that form an existing id.
222 * <p>
223 * If no value is associated, take the default one if any.
224 *
225 * @param id
226 * the id of the value to get
227 * @param suffix
228 * the runtime suffix
229 *
230 * @return the associated value, or NULL if not found (not present in the
231 * resource file)
232 */
233 public String getStringX(E id, String suffix) {
234 return getStringX(id, suffix, null, -1);
235 }
236
237 /**
238 * Return the value associated to the given id as a {@link String} suffixed
239 * with the runtime value "_suffix" (that is, "_" and suffix).
240 * <p>
241 * Will only accept suffixes that form an existing id.
242 * <p>
243 * If no value is associated, take the default one if any.
244 *
245 * @param id
246 * the id of the value to get
247 * @param suffix
248 * the runtime suffix
249 * @param def
250 * the default value when it is not present in the config file
251 *
252 * @return the associated value, or NULL if not found (not present in the
253 * resource file)
254 */
255 public String getStringX(E id, String suffix, String def) {
256 return getStringX(id, suffix, def, -1);
257 }
258
259 /**
260 * Return the value associated to the given id as a {@link String} suffixed
261 * with the runtime value "_suffix" (that is, "_" and suffix).
262 * <p>
263 * Will only accept suffixes that form an existing id.
264 * <p>
265 * If no value is associated, take the default one if any.
266 *
267 * @param id
268 * the id of the value to get
269 * @param suffix
270 * the runtime suffix
271 * @param def
272 * the default value when it is not present in the config file
273 * @param item
274 * the item number to get for an array of values, or -1 for
275 * non-arrays
276 *
277 * @return the associated value, <tt>def</tt> if not found (not present in
278 * the resource file), NULL if the item is specified (not -1) but
279 * does not exist and NULL if bad key
280 */
281 public String getStringX(E id, String suffix, String def, int item) {
282 String key = id.name()
283 + (suffix == null ? "" : "_" + suffix.toUpperCase());
284
285 try {
286 id = Enum.valueOf(type, key);
287 return getString(id, def, item);
288 } catch (IllegalArgumentException e) {
289 }
290
291 return null;
292 }
293
294 /**
295 * Set the value associated to the given id as a {@link String} suffixed
296 * with the runtime value "_suffix" (that is, "_" and suffix).
297 * <p>
298 * Will only accept suffixes that form an existing id.
299 *
300 * @param id
301 * the id of the value to set
302 * @param suffix
303 * the runtime suffix
304 * @param value
305 * the value
306 */
307 public void setStringX(E id, String suffix, String value) {
308 setStringX(id, suffix, value, -1);
309 }
310
311 /**
312 * Set the value associated to the given id as a {@link String} suffixed
313 * with the runtime value "_suffix" (that is, "_" and suffix).
314 * <p>
315 * Will only accept suffixes that form an existing id.
316 *
317 * @param id
318 * the id of the value to set
319 * @param suffix
320 * the runtime suffix
321 * @param value
322 * the value
323 * @param item
324 * the item number to get for an array of values, or -1 for
325 * non-arrays
326 */
327 public void setStringX(E id, String suffix, String value, int item) {
328 String key = id.name()
329 + (suffix == null ? "" : "_" + suffix.toUpperCase());
330
331 try {
332 id = Enum.valueOf(type, key);
333 setString(id, value, item);
334 } catch (IllegalArgumentException e) {
335 }
336 }
337
338 /**
339 * Return the value associated to the given id as a {@link Boolean}.
340 * <p>
341 * If no value is associated, take the default one if any.
342 *
343 * @param id
344 * the id of the value to get
345 *
346 * @return the associated value
347 */
348 public Boolean getBoolean(E id) {
349 return BundleHelper.parseBoolean(getString(id), -1);
350 }
351
352 /**
353 * Return the value associated to the given id as a {@link Boolean}.
354 * <p>
355 * If no value is associated, take the default one if any.
356 *
357 * @param id
358 * the id of the value to get
359 * @param def
360 * the default value when it is not present in the config file or
361 * if it is not a boolean value
362 *
363 * @return the associated value
364 */
365 public boolean getBoolean(E id, boolean def) {
366 Boolean value = getBoolean(id);
367 if (value != null) {
368 return value;
369 }
370
371 return def;
372 }
373
374 /**
375 * Return the value associated to the given id as a {@link Boolean}.
376 * <p>
377 * If no value is associated, take the default one if any.
378 *
379 * @param id
380 * the id of the value to get
381 * @param def
382 * the default value when it is not present in the config file or
383 * if it is not a boolean value
384 * @param item
385 * the item number to get for an array of values, or -1 for
386 * non-arrays
387 *
388 * @return the associated value
389 */
390 public Boolean getBoolean(E id, boolean def, int item) {
391 String value = getString(id);
392 if (value != null) {
393 return BundleHelper.parseBoolean(value, item);
394 }
395
396 return def;
397 }
398
399 /**
400 * Set the value associated to the given id as a {@link Boolean}.
401 *
402 * @param id
403 * the id of the value to set
404 * @param value
405 * the value
406 *
407 */
408 public void setBoolean(E id, boolean value) {
409 setBoolean(id, value, -1);
410 }
411
412 /**
413 * Set the value associated to the given id as a {@link Boolean}.
414 *
415 * @param id
416 * the id of the value to set
417 * @param value
418 * the value
419 * @param item
420 * the item number to get for an array of values, or -1 for
421 * non-arrays
422 *
423 */
424 public void setBoolean(E id, boolean value, int item) {
425 setString(id, BundleHelper.fromBoolean(value), item);
426 }
427
428 /**
429 * Return the value associated to the given id as an {@link Integer}.
430 * <p>
431 * If no value is associated, take the default one if any.
432 *
433 * @param id
434 * the id of the value to get
435 *
436 * @return the associated value
437 */
438 public Integer getInteger(E id) {
439 String value = getString(id);
440 if (value != null) {
441 return BundleHelper.parseInteger(value, -1);
442 }
443
444 return null;
445 }
446
447 /**
448 * Return the value associated to the given id as an int.
449 * <p>
450 * If no value is associated, take the default one if any.
451 *
452 * @param id
453 * the id of the value to get
454 * @param def
455 * the default value when it is not present in the config file or
456 * if it is not a int value
457 *
458 * @return the associated value
459 */
460 public int getInteger(E id, int def) {
461 Integer value = getInteger(id);
462 if (value != null) {
463 return value;
464 }
465
466 return def;
467 }
468
469 /**
470 * Return the value associated to the given id as an int.
471 * <p>
472 * If no value is associated, take the default one if any.
473 *
474 * @param id
475 * the id of the value to get
476 * @param def
477 * the default value when it is not present in the config file or
478 * if it is not a int value
479 * @param item
480 * the item number to get for an array of values, or -1 for
481 * non-arrays
482 *
483 * @return the associated value
484 */
485 public Integer getInteger(E id, int def, int item) {
486 String value = getString(id);
487 if (value != null) {
488 return BundleHelper.parseInteger(value, item);
489 }
490
491 return def;
492 }
493
494 /**
495 * Set the value associated to the given id as a {@link Integer}.
496 *
497 * @param id
498 * the id of the value to set
499 * @param value
500 * the value
501 *
502 */
503 public void setInteger(E id, int value) {
504 setInteger(id, value, -1);
505 }
506
507 /**
508 * Set the value associated to the given id as a {@link Integer}.
509 *
510 * @param id
511 * the id of the value to set
512 * @param value
513 * the value
514 * @param item
515 * the item number to get for an array of values, or -1 for
516 * non-arrays
517 *
518 */
519 public void setInteger(E id, int value, int item) {
520 setString(id, BundleHelper.fromInteger(value), item);
521 }
522
523 /**
524 * Return the value associated to the given id as a {@link Character}.
525 * <p>
526 * If no value is associated, take the default one if any.
527 *
528 * @param id
529 * the id of the value to get
530 *
531 * @return the associated value
532 */
533 public Character getCharacter(E id) {
534 return BundleHelper.parseCharacter(getString(id), -1);
535 }
536
537 /**
538 * Return the value associated to the given id as a {@link Character}.
539 * <p>
540 * If no value is associated, take the default one if any.
541 *
542 * @param id
543 * the id of the value to get
544 * @param def
545 * the default value when it is not present in the config file or
546 * if it is not a char value
547 *
548 * @return the associated value
549 */
550 public char getCharacter(E id, char def) {
551 Character value = getCharacter(id);
552 if (value != null) {
553 return value;
554 }
555
556 return def;
557 }
558
559 /**
560 * Return the value associated to the given id as a {@link Character}.
561 * <p>
562 * If no value is associated, take the default one if any.
563 *
564 * @param id
565 * the id of the value to get
566 * @param def
567 * the default value when it is not present in the config file or
568 * if it is not a char value
569 * @param item
570 * the item number to get for an array of values, or -1 for
571 * non-arrays
572 *
573 * @return the associated value
574 */
575 public Character getCharacter(E id, char def, int item) {
576 String value = getString(id);
577 if (value != null) {
578 return BundleHelper.parseCharacter(value, item);
579 }
580
581 return def;
582 }
583
584 /**
585 * Set the value associated to the given id as a {@link Character}.
586 *
587 * @param id
588 * the id of the value to set
589 * @param value
590 * the value
591 *
592 */
593 public void setCharacter(E id, char value) {
594 setCharacter(id, value, -1);
595 }
596
597 /**
598 * Set the value associated to the given id as a {@link Character}.
599 *
600 * @param id
601 * the id of the value to set
602 * @param value
603 * the value
604 * @param item
605 * the item number to get for an array of values, or -1 for
606 * non-arrays
607 *
608 */
609 public void setCharacter(E id, char value, int item) {
610 setString(id, BundleHelper.fromCharacter(value), item);
611 }
612
613 /**
614 * Return the value associated to the given id as a colour if it is found
615 * and can be parsed.
616 * <p>
617 * The returned value is an ARGB value.
618 * <p>
619 * If no value is associated, take the default one if any.
620 *
621 * @param id
622 * the id of the value to get
623 *
624 * @return the associated value
625 */
626 public Integer getColor(E id) {
627 return BundleHelper.parseColor(getString(id), -1);
628 }
629
630 /**
631 * Return the value associated to the given id as a colour if it is found
632 * and can be parsed.
633 * <p>
634 * The returned value is an ARGB value.
635 * <p>
636 * If no value is associated, take the default one if any.
637 *
638 * @param id
639 * the id of the value to get
640 * @param def
641 * the default value when it is not present in the config file or
642 * if it is not a char value
643 *
644 * @return the associated value
645 */
646 public int getColor(E id, int def) {
647 Integer value = getColor(id);
648 if (value != null) {
649 return value;
650 }
651
652 return def;
653 }
654
655 /**
656 * Return the value associated to the given id as a colour if it is found
657 * and can be parsed.
658 * <p>
659 * The returned value is an ARGB value.
660 * <p>
661 * If no value is associated, take the default one if any.
662 *
663 * @param id
664 * the id of the value to get
665 * @param def
666 * the default value when it is not present in the config file or
667 * if it is not a char value
668 * @param item
669 * the item number to get for an array of values, or -1 for
670 * non-arrays
671 *
672 * @return the associated value
673 */
674 public Integer getColor(E id, int def, int item) {
675 String value = getString(id);
676 if (value != null) {
677 return BundleHelper.parseColor(value, item);
678 }
679
680 return def;
681 }
682
683 /**
684 * Set the value associated to the given id as a colour.
685 * <p>
686 * The value is a BGRA value.
687 *
688 * @param id
689 * the id of the value to set
690 * @param color
691 * the new colour
692 */
693 public void setColor(E id, Integer color) {
694 setColor(id, color, -1);
695 }
696
697 /**
698 * Set the value associated to the given id as a Color.
699 *
700 * @param id
701 * the id of the value to set
702 * @param value
703 * the value
704 * @param item
705 * the item number to get for an array of values, or -1 for
706 * non-arrays
707 *
708 */
709 public void setColor(E id, int value, int item) {
710 setString(id, BundleHelper.fromColor(value), item);
711 }
712
713 /**
714 * Return the value associated to the given id as a list of values if it is
715 * found and can be parsed.
716 * <p>
717 * If no value is associated, take the default one if any.
718 *
719 * @param id
720 * the id of the value to get
721 *
722 * @return the associated list, empty if the value is empty, NULL if it is
723 * not found or cannot be parsed as a list
724 */
725 public List<String> getList(E id) {
726 return BundleHelper.parseList(getString(id), -1);
727 }
728
729 /**
730 * Return the value associated to the given id as a list of values if it is
731 * found and can be parsed.
732 * <p>
733 * If no value is associated, take the default one if any.
734 *
735 * @param id
736 * the id of the value to get
737 * @param def
738 * the default value when it is not present in the config file or
739 * if it is not a char value
740 *
741 * @return the associated list, empty if the value is empty, NULL if it is
742 * not found or cannot be parsed as a list
743 */
744 public List<String> getList(E id, List<String> def) {
745 List<String> value = getList(id);
746 if (value != null) {
747 return value;
748 }
749
750 return def;
751 }
752
753 /**
754 * Return the value associated to the given id as a list of values if it is
755 * found and can be parsed.
756 * <p>
757 * If no value is associated, take the default one if any.
758 *
759 * @param id
760 * the id of the value to get
761 * @param def
762 * the default value when it is not present in the config file or
763 * if it is not a char value
764 * @param item
765 * the item number to get for an array of values, or -1 for
766 * non-arrays
767 *
768 * @return the associated list, empty if the value is empty, NULL if it is
769 * not found or cannot be parsed as a list
770 */
771 public List<String> getList(E id, List<String> def, int item) {
772 String value = getString(id);
773 if (value != null) {
774 return BundleHelper.parseList(value, item);
775 }
776
777 return def;
778 }
779
780 /**
781 * Set the value associated to the given id as a list of values.
782 *
783 * @param id
784 * the id of the value to set
785 * @param list
786 * the new list of values
787 */
788 public void setList(E id, List<String> list) {
789 setList(id, list, -1);
790 }
791
792 /**
793 * Set the value associated to the given id as a {@link List}.
794 *
795 * @param id
796 * the id of the value to set
797 * @param value
798 * the value
799 * @param item
800 * the item number to get for an array of values, or -1 for
801 * non-arrays
802 *
803 */
804 public void setList(E id, List<String> value, int item) {
805 setString(id, BundleHelper.fromList(value), item);
806 }
807
808 /**
809 * Create/update the .properties file.
810 * <p>
811 * Will use the most likely candidate as base if the file does not already
812 * exists and this resource is translatable (for instance, "en_US" will use
813 * "en" as a base if the resource is a translation file).
814 * <p>
815 * Will update the files in {@link Bundles#getDirectory()}; it <b>MUST</b>
816 * be set.
817 *
818 * @throws IOException
819 * in case of IO errors
820 */
821 public void updateFile() throws IOException {
822 updateFile(Bundles.getDirectory());
823 }
824
825 /**
826 * Create/update the .properties file.
827 * <p>
828 * Will use the most likely candidate as base if the file does not already
829 * exists and this resource is translatable (for instance, "en_US" will use
830 * "en" as a base if the resource is a translation file).
831 *
832 * @param path
833 * the path where the .properties files are, <b>MUST NOT</b> be
834 * NULL
835 *
836 * @throws IOException
837 * in case of IO errors
838 */
839 public void updateFile(String path) throws IOException {
840 File file = getUpdateFile(path);
841
842 BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(
843 new FileOutputStream(file), "UTF-8"));
844
845 writeHeader(writer);
846 writer.write("\n");
847 writer.write("\n");
848
849 for (Field field : type.getDeclaredFields()) {
850 Meta meta = field.getAnnotation(Meta.class);
851 if (meta != null) {
852 E id = Enum.valueOf(type, field.getName());
853 String info = getMetaInfo(meta);
854
855 if (info != null) {
856 writer.write(info);
857 writer.write("\n");
858 }
859
860 writeValue(writer, id);
861 }
862 }
863
864 writer.close();
865 }
866
867 /**
868 * Delete the .properties file.
869 * <p>
870 * Will use the most likely candidate as base if the file does not already
871 * exists and this resource is translatable (for instance, "en_US" will use
872 * "en" as a base if the resource is a translation file).
873 * <p>
874 * Will delete the files in {@link Bundles#getDirectory()}; it <b>MUST</b>
875 * be set.
876 *
877 * @return TRUE if the file was deleted
878 */
879 public boolean deleteFile() {
880 return deleteFile(Bundles.getDirectory());
881 }
882
883 /**
884 * Delete the .properties file.
885 * <p>
886 * Will use the most likely candidate as base if the file does not already
887 * exists and this resource is translatable (for instance, "en_US" will use
888 * "en" as a base if the resource is a translation file).
889 *
890 * @param path
891 * the path where the .properties files are, <b>MUST NOT</b> be
892 * NULL
893 *
894 * @return TRUE if the file was deleted
895 */
896 public boolean deleteFile(String path) {
897 File file = getUpdateFile(path);
898 return file.delete();
899 }
900
901 /**
902 * The description {@link TransBundle}, that is, a {@link TransBundle}
903 * dedicated to the description of the values of the given {@link Bundle}
904 * (can be NULL).
905 *
906 * @return the description {@link TransBundle}
907 */
908 public TransBundle<E> getDescriptionBundle() {
909 return descriptionBundle;
910 }
911
912 /**
913 * Reload the {@link Bundle} data files.
914 *
915 * @param resetToDefault
916 * reset to the default configuration (do not look into the
917 * possible user configuration files, only take the original
918 * configuration)
919 */
920 public void reload(boolean resetToDefault) {
921 setBundle(keyType, Locale.getDefault(), resetToDefault);
922 }
923
924 /**
925 * Check if the internal map contains the given key.
926 *
927 * @param key
928 * the key to check for
929 *
930 * @return true if it does
931 */
932 protected boolean containsKey(String key) {
933 return changeMap.containsKey(key) || map.containsKey(key);
934 }
935
936 /**
937 * The default {@link Meta#def()} value for the given enumeration name.
938 *
939 * @param id
940 * the enumeration name (the "id")
941 *
942 * @return the def value in the {@link MetaInfo} or "" if none (never NULL)
943 */
944 protected String getMetaDef(String id) {
945 String rep = "";
946 try {
947 Meta meta = type.getDeclaredField(id).getAnnotation(Meta.class);
948 rep = meta.def();
949 } catch (NoSuchFieldException e) {
950 } catch (SecurityException e) {
951 }
952
953 if (rep == null) {
954 rep = "";
955 }
956
957 return rep;
958 }
959
960 /**
961 * Get the value for the given key if it exists in the internal map, or
962 * <tt>def</tt> if not.
963 * <p>
964 * DO NOT get the default meta value (MetaInfo.def()).
965 *
966 * @param key
967 * the key to check for
968 * @param def
969 * the default value when it is not present in the internal map
970 *
971 * @return the value, or <tt>def</tt> if not found
972 */
973 protected String getString(String key, String def) {
974 if (changeMap.containsKey(key)) {
975 return changeMap.get(key);
976 }
977
978 if (map.containsKey(key)) {
979 return map.get(key);
980 }
981
982 return def;
983 }
984
985 /**
986 * Set the value for this key, in the change map (it is kept in memory, not
987 * yet on disk).
988 *
989 * @param key
990 * the key
991 * @param value
992 * the associated value
993 */
994 protected void setString(String key, String value) {
995 changeMap.put(key, value == null ? null : value.trim());
996 }
997
998 /**
999 * Return formated, display-able information from the {@link Meta} field
1000 * given. Each line will always starts with a "#" character.
1001 *
1002 * @param meta
1003 * the {@link Meta} field
1004 *
1005 * @return the information to display or NULL if none
1006 */
1007 protected String getMetaInfo(Meta meta) {
1008 String desc = meta.description();
1009 boolean group = meta.group();
1010 Meta.Format format = meta.format();
1011 String[] list = meta.list();
1012 boolean nullable = meta.nullable();
1013 String def = meta.def();
1014 boolean array = meta.array();
1015
1016 // Default, empty values -> NULL
1017 if (desc.length() + list.length + def.length() == 0 && !group
1018 && nullable && format == Format.STRING) {
1019 return null;
1020 }
1021
1022 StringBuilder builder = new StringBuilder();
1023 for (String line : desc.split("\n")) {
1024 builder.append("# ").append(line).append("\n");
1025 }
1026
1027 if (group) {
1028 builder.append("# This item is used as a group, its content is not expected to be used.");
1029 } else {
1030 builder.append("# (FORMAT: ").append(format)
1031 .append(nullable ? "" : ", required");
1032 builder.append(") ");
1033
1034 if (list.length > 0) {
1035 builder.append("\n# ALLOWED VALUES: ");
1036 boolean first = true;
1037 for (String value : list) {
1038 if (!first) {
1039 builder.append(", ");
1040 }
1041 builder.append(BundleHelper.escape(value));
1042 first = false;
1043 }
1044 }
1045
1046 if (array) {
1047 builder.append("\n# (This item accepts a list of ^escaped comma-separated values)");
1048 }
1049 }
1050
1051 return builder.toString();
1052 }
1053
1054 /**
1055 * The display name used in the <tt>.properties file</tt>.
1056 *
1057 * @return the name
1058 */
1059 protected String getBundleDisplayName() {
1060 return keyType.toString();
1061 }
1062
1063 /**
1064 * Write the header found in the configuration <tt>.properties</tt> file of
1065 * this {@link Bundles}.
1066 *
1067 * @param writer
1068 * the {@link Writer} to write the header in
1069 *
1070 * @throws IOException
1071 * in case of IO error
1072 */
1073 protected void writeHeader(Writer writer) throws IOException {
1074 writer.write("# " + getBundleDisplayName() + "\n");
1075 writer.write("#\n");
1076 }
1077
1078 /**
1079 * Write the given data to the config file, i.e., "MY_ID = my_curent_value"
1080 * followed by a new line.
1081 * <p>
1082 * Will prepend a # sign if the is is not set (see
1083 * {@link Bundle#isSet(Enum, boolean)}).
1084 *
1085 * @param writer
1086 * the {@link Writer} to write into
1087 * @param id
1088 * the id to write
1089 *
1090 * @throws IOException
1091 * in case of IO error
1092 */
1093 protected void writeValue(Writer writer, E id) throws IOException {
1094 boolean set = isSet(id, false);
1095 writeValue(writer, id.name(), getString(id), set);
1096 }
1097
1098 /**
1099 * Write the given data to the config file, i.e., "MY_ID = my_curent_value"
1100 * followed by a new line.
1101 * <p>
1102 * Will prepend a # sign if the is is not set.
1103 *
1104 * @param writer
1105 * the {@link Writer} to write into
1106 * @param id
1107 * the id to write
1108 * @param value
1109 * the id's value
1110 * @param set
1111 * the value is set in this {@link Bundle}
1112 *
1113 * @throws IOException
1114 * in case of IO error
1115 */
1116 protected void writeValue(Writer writer, String id, String value,
1117 boolean set) throws IOException {
1118
1119 if (!set) {
1120 writer.write('#');
1121 }
1122
1123 writer.write(id);
1124 writer.write(" = ");
1125
1126 if (value == null) {
1127 value = "";
1128 }
1129
1130 String[] lines = value.replaceAll("\t", "\\\\\\t").split("\n");
1131 for (int i = 0; i < lines.length; i++) {
1132 writer.write(lines[i]);
1133 if (i < lines.length - 1) {
1134 writer.write("\\n\\");
1135 }
1136 writer.write("\n");
1137 }
1138 }
1139
1140 /**
1141 * Return the source file for this {@link Bundles} from the given path.
1142 *
1143 * @param path
1144 * the path where the .properties files are
1145 *
1146 * @return the source {@link File}
1147 */
1148 protected File getUpdateFile(String path) {
1149 return new File(path, keyType.name() + ".properties");
1150 }
1151
1152 /**
1153 * Change the currently used bundle, and reset all changes.
1154 *
1155 * @param name
1156 * the name of the bundle to load
1157 * @param locale
1158 * the {@link Locale} to use
1159 * @param resetToDefault
1160 * reset to the default configuration (do not look into the
1161 * possible user configuration files, only take the original
1162 * configuration)
1163 */
1164 protected void setBundle(Enum<?> name, Locale locale, boolean resetToDefault) {
1165 changeMap.clear();
1166 String dir = Bundles.getDirectory();
1167 String bname = type.getPackage().getName() + "." + name.name();
1168
1169 boolean found = false;
1170 if (!resetToDefault && dir != null) {
1171 // Look into Bundles.getDirectory() for .properties files
1172 try {
1173 File file = getPropertyFile(dir, name.name(), locale);
1174 if (file != null) {
1175 Reader reader = new InputStreamReader(new FileInputStream(
1176 file), "UTF-8");
1177 resetMap(new PropertyResourceBundle(reader));
1178 found = true;
1179 }
1180 } catch (IOException e) {
1181 e.printStackTrace();
1182 }
1183 }
1184
1185 if (!found) {
1186 // Look into the package itself for resources
1187 try {
1188 resetMap(ResourceBundle
1189 .getBundle(bname, locale, type.getClassLoader(),
1190 new FixedResourceBundleControl()));
1191 found = true;
1192 } catch (MissingResourceException e) {
1193 } catch (Exception e) {
1194 e.printStackTrace();
1195 }
1196 }
1197
1198 if (!found) {
1199 // We have no bundle for this Bundle
1200 System.err.println("No bundle found for: " + bname);
1201 resetMap(null);
1202 }
1203 }
1204
1205 /**
1206 * Reset the backing map to the content of the given bundle, or with NULL
1207 * values if bundle is NULL.
1208 *
1209 * @param bundle
1210 * the bundle to copy
1211 */
1212 protected void resetMap(ResourceBundle bundle) {
1213 this.map.clear();
1214 if (bundle != null) {
1215 for (Field field : type.getDeclaredFields()) {
1216 try {
1217 Meta meta = field.getAnnotation(Meta.class);
1218 if (meta != null) {
1219 E id = Enum.valueOf(type, field.getName());
1220 String value = bundle.getString(id.name());
1221 this.map.put(id.name(),
1222 value == null ? null : value.trim());
1223 }
1224 } catch (MissingResourceException e) {
1225 }
1226 }
1227 }
1228 }
1229
1230 /**
1231 * Take a snapshot of the changes in memory in this {@link Bundle} made by
1232 * the "set" methods ( {@link Bundle#setString(Enum, String)}...) at the
1233 * current time.
1234 *
1235 * @return a snapshot to use with {@link Bundle#restoreSnapshot(Object)}
1236 */
1237 public Object takeSnapshot() {
1238 return new HashMap<String, String>(changeMap);
1239 }
1240
1241 /**
1242 * Restore a snapshot taken with {@link Bundle}, or reset the current
1243 * changes if the snapshot is NULL.
1244 *
1245 * @param snap
1246 * the snapshot or NULL
1247 */
1248 @SuppressWarnings("unchecked")
1249 public void restoreSnapshot(Object snap) {
1250 if (snap == null) {
1251 changeMap.clear();
1252 } else {
1253 if (snap instanceof Map) {
1254 changeMap = (Map<String, String>) snap;
1255 } else {
1256 throw new RuntimeException(
1257 "Restoring changes in a Bundle must be done on a changes snapshot, "
1258 + "or NULL to discard current changes");
1259 }
1260 }
1261 }
1262
1263 /**
1264 * Return the resource file that is closer to the {@link Locale}.
1265 *
1266 * @param dir
1267 * the directory to look into
1268 * @param name
1269 * the file base name (without <tt>.properties</tt>)
1270 * @param locale
1271 * the {@link Locale}
1272 *
1273 * @return the closest match or NULL if none
1274 */
1275 private File getPropertyFile(String dir, String name, Locale locale) {
1276 List<String> locales = new ArrayList<String>();
1277 if (locale != null) {
1278 String country = locale.getCountry() == null ? "" : locale
1279 .getCountry();
1280 String language = locale.getLanguage() == null ? "" : locale
1281 .getLanguage();
1282 if (!language.isEmpty() && !country.isEmpty()) {
1283 locales.add("_" + language + "-" + country);
1284 }
1285 if (!language.isEmpty()) {
1286 locales.add("_" + language);
1287 }
1288 }
1289
1290 locales.add("");
1291
1292 File file = null;
1293 for (String loc : locales) {
1294 file = new File(dir, name + loc + ".properties");
1295 if (file.exists()) {
1296 break;
1297 }
1298
1299 file = null;
1300 }
1301
1302 return file;
1303 }
1304}