resourcebundlesupport.java

JCommon is a Java class library that is used by JFreeChart, Pentaho Reporting and a few other projec

/* ========================================================================
 * JCommon : a free general purpose class library for the Java(tm) platform
 * ========================================================================
 *
 * (C) Copyright 2000-2008, by Object Refinery Limited and Contributors.
 *
 * Project Info:  http://www.jfree.org/jcommon/index.html
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
 * License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
 * USA.
 *
 * [Java is a trademark or registered trademark of Sun Microsystems, Inc.
 * in the United States and other countries.]
 *
 * ---------------------
 * ReadOnlyIterator.java
 * ---------------------
 * (C)opyright 2003-2008, by Thomas Morgner and Contributors.
 *
 * Original Author:  Thomas Morgner;
 * Contributor(s):   David Gilbert (for Object Refinery Limited);
 *
 * $Id: ResourceBundleSupport.java,v 1.12 2008/12/18 09:57:32 mungady Exp $
 *
 * Changes
 * -------
 * 18-Dec-2008 : Use ResourceBundleWrapper - see JFreeChart patch 1607918 by
 *               Jess Thrysoee (DG);
 *
 */

package org.jfree.util;

import java.awt.Image;
import java.awt.Toolkit;
import java.awt.event.InputEvent;
import java.awt.event.KeyEvent;
import java.awt.image.BufferedImage;
import java.lang.reflect.Field;
import java.net.URL;
import java.text.MessageFormat;
import java.util.Arrays;
import java.util.Locale;
import java.util.MissingResourceException;
import java.util.ResourceBundle;
import java.util.TreeMap;
import java.util.TreeSet;

import javax.swing.Icon;
import javax.swing.ImageIcon;
import javax.swing.JMenu;
import javax.swing.KeyStroke;

/**
 * An utility class to ease up using property-file resource bundles.
 * <p/>
 * The class support references within the resource bundle set to minimize the
 * occurence of duplicate keys. References are given in the format:
 * <pre>
 * a.key.name=@referenced.key
 * </pre>
 * <p/>
 * A lookup to a key in an other resource bundle should be written by
 * <pre>
 * a.key.name=@@[e-mail]
 * </pre>
 *
 * @author Thomas Morgner
 */
public class ResourceBundleSupport
{
  /**
   * The resource bundle that will be used for local lookups.
   */
  private ResourceBundle resources;

  /**
   * A cache for string values, as looking up the cache is faster than looking
   * up the value in the bundle.
   */
  private TreeMap cache;
  /**
   * The current lookup path when performing non local lookups. This prevents
   * infinite loops during such lookups.
   */
  private TreeSet lookupPath;

  /**
   * The name of the local resource bundle.
   */
  private String resourceBase;

  /**
   * The locale for this bundle.
   */
  private Locale locale;

  /**
   * Creates a new instance.
   *
   * @param locale  the locale.
   * @param baseName the base name of the resource bundle, a fully qualified
   *                 class name
   */
  public ResourceBundleSupport(final Locale locale, final String baseName)
  {
    this(locale, ResourceBundleWrapper.getBundle(baseName, locale), baseName);
  }

  /**
   * Creates a new instance.
   *
   * @param locale         the locale for which this resource bundle is
   *                       created.
   * @param resourceBundle the resourcebundle
   * @param baseName       the base name of the resource bundle, a fully
   *                       qualified class name
   */
  protected ResourceBundleSupport(final Locale locale,
                                  final ResourceBundle resourceBundle,
                                  final String baseName)
  {
    if (locale == null)
    {
      throw new NullPointerException("Locale must not be null");
    }
    if (resourceBundle == null)
    {
      throw new NullPointerException("Resources must not be null");
    }
    if (baseName == null)
    {
      throw new NullPointerException("BaseName must not be null");
    }
    this.locale = locale;
    this.resources = resourceBundle;
    this.resourceBase = baseName;
    this.cache = new TreeMap();
    this.lookupPath = new TreeSet();
  }

  /**
   * Creates a new instance.
   *
   * @param locale         the locale for which the resource bundle is
   *                       created.
   * @param resourceBundle the resourcebundle
   */
  public ResourceBundleSupport(final Locale locale,
                               final ResourceBundle resourceBundle)
  {
    this(locale, resourceBundle, resourceBundle.toString());
  }

  /**
   * Creates a new instance.
   *
   * @param baseName the base name of the resource bundle, a fully qualified
   *                 class name
   */
  public ResourceBundleSupport(final String baseName)
  {
    this(Locale.getDefault(), ResourceBundleWrapper.getBundle(baseName),
            baseName);
  }

  /**
   * Creates a new instance.
   *
   * @param resourceBundle the resourcebundle
   * @param baseName       the base name of the resource bundle, a fully
   *                       qualified class name
   */
  protected ResourceBundleSupport(final ResourceBundle resourceBundle,
                                  final String baseName)
  {
    this(Locale.getDefault(), resourceBundle, baseName);
  }

  /**
   * Creates a new instance.
   *
   * @param resourceBundle the resourcebundle
   */
  public ResourceBundleSupport(final ResourceBundle resourceBundle)
  {
    this(Locale.getDefault(), resourceBundle, resourceBundle.toString());
  }

  /**
   * The base name of the resource bundle.
   *
   * @return the resource bundle's name.
   */
  protected final String getResourceBase()
  {
    return this.resourceBase;
  }

  /**
   * Gets a string for the given key from this resource bundle or one of its
   * parents. If the key is a link, the link is resolved and the referenced
   * string is returned instead.
   *
   * @param key the key for the desired string
   * @return the string for the given key
   * @throws NullPointerException     if <code>key</code> is <code>null</code>
   * @throws MissingResourceException if no object for the given key can be
   *                                  found
   * @throws ClassCastException       if the object found for the given key is
   *                                  not a string
   */
  public synchronized String getString(final String key)
  {
    final String retval = (String) this.cache.get(key);
    if (retval != null)
    {
      return retval;
    }
    this.lookupPath.clear();
    return internalGetString(key);
  }

  /**
   * Performs the lookup for the given key. If the key points to a link the
   * link is resolved and that key is looked up instead.
   *
   * @param key the key for the string
   * @return the string for the given key
   */
  protected String internalGetString(final String key)
  {
    if (this.lookupPath.contains(key))
    {
      throw new MissingResourceException
          ("InfiniteLoop in resource lookup",
              getResourceBase(), this.lookupPath.toString());
    }
    final String fromResBundle = this.resources.getString(key);
    if (fromResBundle.startsWith("@@"))
    {
      // global forward ...
      final int idx = fromResBundle.indexOf('@', 2);
      if (idx == -1)
      {
        throw new MissingResourceException
            ("Invalid format for global lookup key.", getResourceBase(), key);
      }
      try
      {
        final ResourceBundle res = ResourceBundleWrapper.getBundle
            (fromResBundle.substring(2, idx));
        return res.getString(fromResBundle.substring(idx + 1));
      }
      catch (Exception e)
      {
        Log.error("Error during global lookup", e);
        throw new MissingResourceException
            ("Error during global lookup", getResourceBase(), key);
      }
    }
    else if (fromResBundle.startsWith("@"))
    {
      // local forward ...
      final String newKey = fromResBundle.substring(1);
      this.lookupPath.add(key);
      final String retval = internalGetString(newKey);

      this.cache.put(key, retval);
      return retval;
    }
    else
    {
      this.cache.put(key, fromResBundle);
      return fromResBundle;
    }
  }

  /**
   * Returns an scaled icon suitable for buttons or menus.
   *
   * @param key   the name of the resource bundle key
   * @param large true, if the image should be scaled to 24x24, or false for
   *              16x16
   * @return the icon.
   */
  public Icon getIcon(final String key, final boolean large)
  {
    final String name = getString(key);
    return createIcon(name, true, large);
  }

  /**
   * Returns an unscaled icon.
   *
   * @param key the name of the resource bundle key
   * @return the icon.
   */
  public Icon getIcon(final String key)
  {
    final String name = getString(key);
    return createIcon(name, false, false);
  }

  /**
   * Returns the mnemonic stored at the given resourcebundle key. The mnemonic
   * should be either the symbolic name of one of the KeyEvent.VK_* constants
   * (without the 'VK_') or the character for that key.
   * <p/>
   * For the enter key, the resource bundle would therefore either contain
   * "ENTER" or "\n".
   * <pre>
   * a.resourcebundle.key=ENTER
   * an.other.resourcebundle.key=\n
   * </pre>
   *
   * @param key the resourcebundle key
   * @return the mnemonic
   */
  public Integer getMnemonic(final String key)
  {
    final String name = getString(key);