resources/Bundle.java

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