src/be/nikiroo/utils/resources/Bundle.java

   1 package be.nikiroo.utils.resources;
   2
   3 import java.io.BufferedWriter;
   4 import java.io.File;
   5 import java.io.FileInputStream;
   6 import java.io.FileOutputStream;
   7 import java.io.IOException;
   8 import java.io.InputStreamReader;
   9 import java.io.OutputStreamWriter;
  10 import java.io.Reader;
  11 import java.io.Writer;
  12 import java.lang.reflect.Field;
  13 import java.util.ArrayList;
  14 import java.util.HashMap;
  15 import java.util.List;
  16 import java.util.Locale;
  17 import java.util.Map;
  18 import java.util.MissingResourceException;
  19 import java.util.PropertyResourceBundle;
  20 import java.util.ResourceBundle;
  21
  22 /**
  23  * This class encapsulate a {@link ResourceBundle} in UTF-8. It allows to
  24  * retrieve values associated to an enumeration, and allows some additional
  25  * methods.
  26  * <p>
  27  * It also sports a writable change map, and you can save back the
  28  * {@link Bundle} to file with {@link Bundle#updateFile(String)}.
  29  *
  30  * @param <E>
  31  *            the enum to use to get values out of this class
  32  *
  33  * @author niki
  34  */
  35
  36 public class Bundle<E extends Enum<E>> {
  37         /** The type of E. */
  38         protected Class<E> type;
  39         /**
  40          * The {@link Enum} associated to this {@link Bundle} (all the keys used in
  41          * this {@link Bundle} will be of this type).
  42          */
  43         protected Enum<?> keyType;
  44
  45         private TransBundle<E> descriptionBundle;
  46
  47         /** R/O map */
  48         private Map<String, String> map;
  49         /** R/W map */
  50         private Map<String, String> changeMap;
  51
  52         /**
  53          * Create a new {@link Bundles} of the given name.
  54          *
  55          * @param type
  56          *            a runtime instance of the class of E
  57          * @param name
  58          *            the name of the {@link Bundles}
  59          * @param descriptionBundle
  60          *            the description {@link TransBundle}, that is, a
  61          *            {@link TransBundle} dedicated to the description of the values
  62          *            of the given {@link Bundle} (can be NULL)
  63          */
  64         protected Bundle(Class<E> type, Enum<?> name,
  65                         TransBundle<E> descriptionBundle) {
  66                 this.type = type;
  67                 this.keyType = name;
  68                 this.descriptionBundle = descriptionBundle;
  69
  70                 this.map = new HashMap<String, String>();
  71                 this.changeMap = new HashMap<String, String>();
  72                 setBundle(name, Locale.getDefault(), false);
  73         }
  74
  75         /**
  76          * Return the value associated to the given id as a {@link String}.
  77          *
  78          * @param id
  79          *            the id of the value to get
  80          *
  81          * @return the associated value, or NULL if not found (not present in the
  82          *         resource file)
  83          */
  84         public String getString(E id) {
  85                 return getString(id.name());
  86         }
  87
  88         /**
  89          * Set the value associated to the given id as a {@link String}.
  90          *
  91          * @param id
  92          *            the id of the value to set
  93          * @param value
  94          *            the value
  95          *
  96          */
  97         public void setString(E id, String value) {
  98                 setString(id.name(), value);
  99         }
 100
 101         /**
 102          * Return the value associated to the given id as a {@link String} suffixed
 103          * with the runtime value "_suffix" (that is, "_" and suffix).
 104          * <p>
 105          * Will only accept suffixes that form an existing id.
 106          *
 107          * @param id
 108          *            the id of the value to get
 109          * @param suffix
 110          *            the runtime suffix
 111          *
 112          * @return the associated value, or NULL if not found (not present in the
 113          *         resource file)
 114          */
 115         public String getStringX(E id, String suffix) {
 116                 String key = id.name()
 117                                 + (suffix == null ? "" : "_" + suffix.toUpperCase());
 118
 119                 try {
 120                         id = Enum.valueOf(type, key);
 121                         return getString(id);
 122                 } catch (IllegalArgumentException e) {
 123
 124                 }
 125
 126                 return null;
 127         }
 128
 129         /**
 130          * Set the value associated to the given id as a {@link String} suffixed
 131          * with the runtime value "_suffix" (that is, "_" and suffix).
 132          * <p>
 133          * Will only accept suffixes that form an existing id.
 134          *
 135          * @param id
 136          *            the id of the value to set
 137          * @param suffix
 138          *            the runtime suffix
 139          * @param value
 140          *            the value
 141          */
 142         public void setStringX(E id, String suffix, String value) {
 143                 String key = id.name()
 144                                 + (suffix == null ? "" : "_" + suffix.toUpperCase());
 145
 146                 try {
 147                         id = Enum.valueOf(type, key);
 148                         setString(id, value);
 149                 } catch (IllegalArgumentException e) {
 150
 151                 }
 152         }
 153
 154         /**
 155          * Return the value associated to the given id as a {@link Boolean}.
 156          *
 157          * @param id
 158          *            the id of the value to get
 159          *
 160          * @return the associated value
 161          */
 162         public Boolean getBoolean(E id) {
 163                 String str = getString(id);
 164                 return BundleHelper.parseBoolean(str);
 165         }
 166
 167         /**
 168          * Return the value associated to the given id as a {@link Boolean}.
 169          *
 170          * @param id
 171          *            the id of the value to get
 172          * @param def
 173          *            the default value when it is not present in the config file or
 174          *            if it is not a boolean value
 175          *
 176          * @return the associated value
 177          */
 178         public boolean getBoolean(E id, boolean def) {
 179                 Boolean b = getBoolean(id);
 180                 if (b != null)
 181                         return b;
 182
 183                 return def;
 184         }
 185
 186         /**
 187          * Set the value associated to the given id as a {@link Boolean}.
 188          *
 189          * @param id
 190          *            the id of the value to set
 191          * @param value
 192          *            the value
 193          *
 194          */
 195         public void setBoolean(E id, boolean value) {
 196                 setString(id.name(), BundleHelper.fromBoolean(value));
 197         }
 198
 199
 200         /**
 201          * Return the value associated to the given id as an {@link Integer}.
 202          *
 203          * @param id
 204          *            the id of the value to get
 205          *
 206          * @return the associated value
 207          */
 208         public Integer getInteger(E id) {
 209                 return BundleHelper.parseInteger(getString(id));
 210         }
 211
 212         /**
 213          * Return the value associated to the given id as an int.
 214          *
 215          * @param id
 216          *            the id of the value to get
 217          * @param def
 218          *            the default value when it is not present in the config file or
 219          *            if it is not a int value
 220          *
 221          * @return the associated value
 222          */
 223         public int getInteger(E id, int def) {
 224                 Integer i = getInteger(id);
 225                 if (i != null)
 226                         return i;
 227
 228                 return def;
 229         }
 230
 231         /**
 232          * Set the value associated to the given id as a {@link Integer}.
 233          *
 234          * @param id
 235          *            the id of the value to set
 236          * @param value
 237          *            the value
 238          *
 239          */
 240         public void setInteger(E id, int value) {
 241                 setString(id.name(), BundleHelper.fromInteger(value));
 242         }
 243
 244         /**
 245          * Return the value associated to the given id as a {@link Character}.
 246          *
 247          * @param id
 248          *            the id of the value to get
 249          *
 250          * @return the associated value
 251          */
 252         public Character getCharacter(E id) {
 253                 return BundleHelper.parseCharacter(getString(id));
 254         }
 255
 256         /**
 257          * Return the value associated to the given id as a {@link Character}.
 258          *
 259          * @param id
 260          *            the id of the value to get
 261          * @param def
 262          *            the default value when it is not present in the config file or
 263          *            if it is not a char value
 264          *
 265          * @return the associated value
 266          */
 267         public char getCharacter(E id, char def) {
 268                 Character car = getCharacter(id);
 269                 if (car != null)
 270                         return car;
 271
 272                 return def;
 273         }
 274
 275         /**
 276          * Return the value associated to the given id as a colour if it is found
 277          * and can be parsed.
 278          * <p>
 279          * The returned value is an ARGB value.
 280          *
 281          * @param id
 282          *            the id of the value to get
 283          *
 284          * @return the associated value
 285          */
 286         public Integer getColor(E id) {
 287                 return BundleHelper.parseColor(getString(id));
 288         }
 289
 290         /**
 291          * Set the value associated to the given id as a colour.
 292          * <p>
 293          * The value is a BGRA value.
 294          *
 295          * @param id
 296          *            the id of the value to set
 297          * @param color
 298          *            the new colour
 299          */
 300         public void setColor(E id, Integer color) {
 301                 setString(id, BundleHelper.fromColor(color));
 302         }
 303
 304         /**
 305          * Return the value associated to the given id as a list of values if it is
 306          * found and can be parsed.
 307          *
 308          * @param id
 309          *            the id of the value to get
 310          *
 311          * @return the associated list, empty if the value is empty, NULL if it is
 312          *         not found or cannot be parsed as a list
 313          */
 314         public List<String> getList(E id) {
 315                 return BundleHelper.parseList(getString(id));
 316         }
 317
 318         /**
 319          * Set the value associated to the given id as a list of values.
 320          *
 321          * @param id
 322          *            the id of the value to set
 323          * @param list
 324          *            the new list of values
 325          */
 326         public void setList(E id, List<String> list) {
 327                 setString(id, BundleHelper.fromList(list));
 328         }
 329
 330         /**
 331          * Create/update the .properties file.
 332          * <p>
 333          * Will use the most likely candidate as base if the file does not already
 334          * exists and this resource is translatable (for instance, "en_US" will use
 335          * "en" as a base if the resource is a translation file).
 336          * <p>
 337          * Will update the files in {@link Bundles#getDirectory()}; it <b>MUST</b>
 338          * be set.
 339          *
 340          * @throws IOException
 341          *             in case of IO errors
 342          */
 343         public void updateFile() throws IOException {
 344                 updateFile(Bundles.getDirectory());
 345         }
 346
 347         /**
 348          * Create/update the .properties file.
 349          * <p>
 350          * Will use the most likely candidate as base if the file does not already
 351          * exists and this resource is translatable (for instance, "en_US" will use
 352          * "en" as a base if the resource is a translation file).
 353          *
 354          * @param path
 355          *            the path where the .properties files are, <b>MUST NOT</b> be
 356          *            NULL
 357          *
 358          * @throws IOException
 359          *             in case of IO errors
 360          */
 361         public void updateFile(String path) throws IOException {
 362                 File file = getUpdateFile(path);
 363
 364                 BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(
 365                                 new FileOutputStream(file), "UTF-8"));
 366
 367                 writeHeader(writer);
 368                 writer.write("\n");
 369                 writer.write("\n");
 370
 371                 for (Field field : type.getDeclaredFields()) {
 372                         Meta meta = field.getAnnotation(Meta.class);
 373                         if (meta != null) {
 374                                 E id = Enum.valueOf(type, field.getName());
 375                                 String info = getMetaInfo(meta);
 376
 377                                 if (info != null) {
 378                                         writer.write(info);
 379                                         writer.write("\n");
 380                                 }
 381
 382                                 writeValue(writer, id);
 383                         }
 384                 }
 385
 386                 writer.close();
 387         }
 388
 389         /**
 390          * Delete the .properties file.
 391          * <p>
 392          * Will use the most likely candidate as base if the file does not already
 393          * exists and this resource is translatable (for instance, "en_US" will use
 394          * "en" as a base if the resource is a translation file).
 395          * <p>
 396          * Will delete the files in {@link Bundles#getDirectory()}; it <b>MUST</b>
 397          * be set.
 398          *
 399          * @return TRUE if the file was deleted
 400          */
 401         public boolean deleteFile() {
 402                 return deleteFile(Bundles.getDirectory());
 403         }
 404
 405         /**
 406          * Delete the .properties file.
 407          * <p>
 408          * Will use the most likely candidate as base if the file does not already
 409          * exists and this resource is translatable (for instance, "en_US" will use
 410          * "en" as a base if the resource is a translation file).
 411          *
 412          * @param path
 413          *            the path where the .properties files are, <b>MUST NOT</b> be
 414          *            NULL
 415          *
 416          * @return TRUE if the file was deleted
 417          */
 418         public boolean deleteFile(String path) {
 419                 File file = getUpdateFile(path);
 420                 return file.delete();
 421         }
 422
 423         /**
 424          * The description {@link TransBundle}, that is, a {@link TransBundle}
 425          * dedicated to the description of the values of the given {@link Bundle}
 426          * (can be NULL).
 427          *
 428          * @return the description {@link TransBundle}
 429          */
 430         public TransBundle<E> getDescriptionBundle() {
 431                 return descriptionBundle;
 432         }
 433
 434         /**
 435          * Reload the {@link Bundle} data files.
 436          *
 437          * @param resetToDefault
 438          *            reset to the default configuration (do not look into the
 439          *            possible user configuration files, only take the original
 440          *            configuration)
 441          */
 442         public void reload(boolean resetToDefault) {
 443                 setBundle(keyType, Locale.getDefault(), resetToDefault);
 444         }
 445
 446         /**
 447          * Check if the internal map contains the given key.
 448          *
 449          * @param key
 450          *            the key to check for
 451          *
 452          * @return true if it does
 453          */
 454         protected boolean containsKey(String key) {
 455                 return changeMap.containsKey(key) || map.containsKey(key);
 456         }
 457
 458         /**
 459          * Get the value for the given key if it exists in the internal map, or NULL
 460          * if not.
 461          *
 462          * @param key
 463          *            the key to check for
 464          *
 465          * @return the value, or NULL
 466          */
 467         protected String getString(String key) {
 468                 if (changeMap.containsKey(key)) {
 469                         return changeMap.get(key);
 470                 }
 471
 472                 if (map.containsKey(key)) {
 473                         return map.get(key);
 474                 }
 475
 476                 return null;
 477         }
 478
 479         /**
 480          * Set the value for this key, in the change map (it is kept in memory, not
 481          * yet on disk).
 482          *
 483          * @param key
 484          *            the key
 485          * @param value
 486          *            the associated value
 487          */
 488         protected void setString(String key, String value) {
 489                 changeMap.put(key, value == null ? null : value.trim());
 490         }
 491
 492         /**
 493          * Return formated, display-able information from the {@link Meta} field
 494          * given. Each line will always starts with a "#" character.
 495          *
 496          * @param meta
 497          *            the {@link Meta} field
 498          *
 499          * @return the information to display or NULL if none
 500          */
 501         protected String getMetaInfo(Meta meta) {
 502                 String desc = meta.description();
 503                 boolean group = meta.group();
 504                 Meta.Format format = meta.format();
 505                 String[] list = meta.list();
 506                 boolean nullable = meta.nullable();
 507                 String def = meta.def();
 508                 String info = meta.info();
 509                 boolean array = meta.array();
 510
 511                 // Default, empty values -> NULL
 512                 if (desc.length() + list.length + info.length() + def.length() == 0
 513                                 && !group && nullable && format == Meta.Format.STRING) {
 514                         return null;
 515                 }
 516
 517                 StringBuilder builder = new StringBuilder();
 518                 builder.append("# ").append(desc);
 519                 if (desc.length() > 20) {
 520                         builder.append("\n#");
 521                 }
 522
 523                 if (group) {
 524                         builder.append("This item is used as a group, its content is not expected to be used.");
 525                 } else {
 526                         builder.append(" (FORMAT: ").append(format)
 527                                         .append(nullable ? "" : " (required)");
 528                         builder.append(") ").append(info);
 529
 530                         if (list.length > 0) {
 531                                 builder.append("\n# ALLOWED VALUES:");
 532                                 for (String value : list) {
 533                                         builder.append(" \"").append(value).append("\"");
 534                                 }
 535                         }
 536
 537                         if (array) {
 538                                 builder.append("\n# (This item accept a list of comma-separated values)");
 539                         }
 540                 }
 541
 542                 return builder.toString();
 543         }
 544
 545         /**
 546          * The display name used in the <tt>.properties file</tt>.
 547          *
 548          * @return the name
 549          */
 550         protected String getBundleDisplayName() {
 551                 return keyType.toString();
 552         }
 553
 554         /**
 555          * Write the header found in the configuration <tt>.properties</tt> file of
 556          * this {@link Bundles}.
 557          *
 558          * @param writer
 559          *            the {@link Writer} to write the header in
 560          *
 561          * @throws IOException
 562          *             in case of IO error
 563          */
 564         protected void writeHeader(Writer writer) throws IOException {
 565                 writer.write("# " + getBundleDisplayName() + "\n");
 566                 writer.write("#\n");
 567         }
 568
 569         /**
 570          * Write the given id to the config file, i.e., "MY_ID = my_curent_value"
 571          * followed by a new line
 572          *
 573          * @param writer
 574          *            the {@link Writer} to write into
 575          * @param id
 576          *            the id to write
 577          *
 578          * @throws IOException
 579          *             in case of IO error
 580          */
 581         protected void writeValue(Writer writer, E id) throws IOException {
 582                 writeValue(writer, id.name(), getString(id));
 583         }
 584
 585         /**
 586          * Write the given data to the config file, i.e., "MY_ID = my_curent_value"
 587          * followed by a new line
 588          *
 589          * @param writer
 590          *            the {@link Writer} to write into
 591          * @param id
 592          *            the id to write
 593          * @param value
 594          *            the id's value
 595          *
 596          * @throws IOException
 597          *             in case of IO error
 598          */
 599         protected void writeValue(Writer writer, String id, String value)
 600                         throws IOException {
 601                 writer.write(id);
 602                 writer.write(" = ");
 603
 604                 if (value == null) {
 605                         value = "";
 606                 }
 607
 608                 String[] lines = value.replaceAll("\t", "\\\\\\t").split("\n");
 609                 for (int i = 0; i < lines.length; i++) {
 610                         writer.write(lines[i]);
 611                         if (i < lines.length - 1) {
 612                                 writer.write("\\n\\");
 613                         }
 614                         writer.write("\n");
 615                 }
 616         }
 617
 618         /**
 619          * Return the source file for this {@link Bundles} from the given path.
 620          *
 621          * @param path
 622          *            the path where the .properties files are
 623          *
 624          * @return the source {@link File}
 625          */
 626         protected File getUpdateFile(String path) {
 627                 return new File(path, keyType.name() + ".properties");
 628         }
 629
 630         /**
 631          * Change the currently used bundle, and reset all changes.
 632          *
 633          * @param name
 634          *            the name of the bundle to load
 635          * @param locale
 636          *            the {@link Locale} to use
 637          * @param resetToDefault
 638          *            reset to the default configuration (do not look into the
 639          *            possible user configuration files, only take the original
 640          *            configuration)
 641          */
 642         protected void setBundle(Enum<?> name, Locale locale, boolean resetToDefault) {
 643                 changeMap.clear();
 644                 String dir = Bundles.getDirectory();
 645                 String bname = type.getPackage().getName() + "." + name.name();
 646
 647                 boolean found = false;
 648                 if (!resetToDefault && dir != null) {
 649                         // Look into Bundles.getDirectory() for .properties files
 650                         try {
 651                                 File file = getPropertyFile(dir, name.name(), locale);
 652                                 if (file != null) {
 653                                         Reader reader = new InputStreamReader(new FileInputStream(
 654                                                         file), "UTF8");
 655                                         resetMap(new PropertyResourceBundle(reader));
 656                                         found = true;
 657                                 }
 658                         } catch (IOException e) {
 659                                 e.printStackTrace();
 660                         }
 661                 }
 662
 663                 if (!found) {
 664                         // Look into the package itself for resources
 665                         try {
 666                                 resetMap(ResourceBundle
 667                                                 .getBundle(bname, locale, type.getClassLoader(),
 668                                                                 new FixedResourceBundleControl()));
 669                                 found = true;
 670                         } catch (MissingResourceException e) {
 671                         } catch (Exception e) {
 672                                 e.printStackTrace();
 673                         }
 674                 }
 675
 676                 if (!found) {
 677                         // We have no bundle for this Bundle
 678                         System.err.println("No bundle found for: " + bname);
 679                         resetMap(null);
 680                 }
 681         }
 682
 683         /**
 684          * Reset the backing map to the content of the given bundle, or with default
 685          * valiues if bundle is NULL.
 686          *
 687          * @param bundle
 688          *            the bundle to copy
 689          */
 690         protected void resetMap(ResourceBundle bundle) {
 691                 this.map.clear();
 692                 for (Field field : type.getDeclaredFields()) {
 693                         try {
 694                                 Meta meta = field.getAnnotation(Meta.class);
 695                                 if (meta != null) {
 696                                         E id = Enum.valueOf(type, field.getName());
 697
 698                                         String value;
 699                                         if (bundle != null) {
 700                                                 value = bundle.getString(id.name());
 701                                         } else {
 702                                                 value = meta.def();
 703                                         }
 704
 705                                         this.map.put(id.name(), value == null ? null : value.trim());
 706                                 }
 707                         } catch (MissingResourceException e) {
 708                         }
 709                 }
 710         }
 711
 712         /**
 713          * Take a snapshot of the changes in memory in this {@link Bundle} made by
 714          * the "set" methods ( {@link Bundle#setString(Enum, String)}...) at the
 715          * current time.
 716          *
 717          * @return a snapshot to use with {@link Bundle#restoreSnapshot(Object)}
 718          */
 719         public Object takeSnapshot() {
 720                 return new HashMap<String, String>(changeMap);
 721         }
 722
 723         /**
 724          * Restore a snapshot taken with {@link Bundle}, or reset the current
 725          * changes if the snapshot is NULL.
 726          *
 727          * @param snap
 728          *            the snapshot or NULL
 729          */
 730         @SuppressWarnings("unchecked")
 731         public void restoreSnapshot(Object snap) {
 732                 if (snap == null) {
 733                         changeMap.clear();
 734                 } else {
 735                         if (snap instanceof Map) {
 736                                 changeMap = (Map<String, String>) snap;
 737                         } else {
 738                                 throw new RuntimeException(
 739                                                 "Restoring changes in a Bundle must be done on a changes snapshot, "
 740                                                                 + "or NULL to discard current changes");
 741                         }
 742                 }
 743         }
 744
 745         /**
 746          * Return the resource file that is closer to the {@link Locale}.
 747          *
 748          * @param dir
 749          *            the directory to look into
 750          * @param name
 751          *            the file base name (without <tt>.properties</tt>)
 752          * @param locale
 753          *            the {@link Locale}
 754          *
 755          * @return the closest match or NULL if none
 756          */
 757         private File getPropertyFile(String dir, String name, Locale locale) {
 758                 List<String> locales = new ArrayList<String>();
 759                 if (locale != null) {
 760                         String country = locale.getCountry() == null ? "" : locale
 761                                         .getCountry();
 762                         String language = locale.getLanguage() == null ? "" : locale
 763                                         .getLanguage();
 764                         if (!language.isEmpty() && !country.isEmpty()) {
 765                                 locales.add("_" + language + "-" + country);
 766                         }
 767                         if (!language.isEmpty()) {
 768                                 locales.add("_" + language);
 769                         }
 770                 }
 771
 772                 locales.add("");
 773
 774                 File file = null;
 775                 for (String loc : locales) {
 776                         file = new File(dir, name + loc + ".properties");
 777                         if (file.exists()) {
 778                                 break;
 779                         }
 780
 781                         file = null;
 782                 }
 783
 784                 return file;
 785         }
 786 }