Java tutorial
/* * Copyright 2007 Google Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); you may not * use this file except in compliance with the License. You may obtain a copy of * the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the * License for the specific language governing permissions and limitations under * the License. */ package com.google.gwt.i18n.client; import com.google.gwt.core.client.JavaScriptObject; import java.util.ArrayList; import java.util.Collection; import java.util.HashMap; import java.util.HashSet; import java.util.Map; import java.util.MissingResourceException; import java.util.Set; /** * Provides dynamic string lookup of key/value string pairs defined in a * module's host HTML page. Each unique instance of <code>Dictionary</code> is * bound to a named JavaScript object that resides in the global namespace of * the host page's window object. The bound JavaScript object is used directly * as an associative array. * * <p> * For example, suppose you define the following JavaScript object in your host * page: * * {@gwt.include com/google/gwt/examples/i18n/ThemeDictionaryExample.js} * * You can then use a <code>Dictionary</code> to access the key/value pairs * above: * * {@example com.google.gwt.examples.i18n.ThemeDictionaryExample#useThemeDictionary()} * </p> * * <p> * Unlike the family of interfaces that extend * {@link com.google.gwt.i18n.client.Localizable} which support static * internationalization, the <code>Dictionary</code> class is fully dynamic. * As a result, a variety of error conditions (particularly those involving key * mismatches) cannot be caught until runtime. Similarly, the GWT compiler is * unable discard unused dictionary values since the structure cannot be * statically analyzed. * </p> * * <h3>A Caveat Regarding Locale</h3> * The module's host page completely determines the mappings defined for each * dictionary without regard to the <code>locale</code> client property. Thus, * <code>Dictionary</code> is the most flexible of the internationalization * types and may provide the simplest form of integration with existing * localization systems which were not specifically designed to use GWT's * <code>locale</code> client property. * * <p> * See {@link com.google.gwt.i18n.client.Localizable} for background on the * <code>locale</code> client property. * </p> * * <h3>Required Module</h3> * Modules that use this interface should inherit * <code>com.google.gwt.i18n.I18N</code>. * * {@gwt.include com/google/gwt/examples/i18n/InheritsExample.gwt.xml} */ public final class Dictionary { private static Map<String, Dictionary> cache = new HashMap<String, Dictionary>(); private static final int MAX_KEYS_TO_SHOW = 20; /** * Returns the <code>Dictionary</code> object associated with the given * name. * * @param name * @return specified dictionary * @throws MissingResourceException */ public static Dictionary getDictionary(String name) { Dictionary target = cache.get(name); if (target == null) { target = new Dictionary(name); cache.put(name, target); } return target; } static void resourceErrorBadType(String name) { throw new MissingResourceException( "'" + name + "' is not a JavaScript object and cannot be used as a Dictionary", null, name); } private JavaScriptObject dict; private String label; /** * Constructor for <code>Dictionary</code>. * * @param name name of linked JavaScript Object */ private Dictionary(String name) { if (name == null || "".equals(name)) { throw new IllegalArgumentException("Cannot create a Dictionary with a null or empty name"); } this.label = "Dictionary " + name; attach(name); if (dict == null) { throw new MissingResourceException("Cannot find JavaScript object with the name '" + name + "'", name, null); } } /** * Get the value associated with the given Dictionary key. * * We have to call Object.hasOwnProperty to verify that the value is * defined on this object, rather than a superclass, since normal Object * properties are also visible on this object. * * @param key to lookup * @return the value * @throws MissingResourceException if the value is not found */ public native String get(String key) /*-{ // In Firefox, jsObject.hasOwnProperty(key) requires a primitive string key = String(key); var map = this.@com.google.gwt.i18n.client.Dictionary::dict; var value = map[key]; if (value == null || !map.hasOwnProperty(key)) { this.@com.google.gwt.i18n.client.Dictionary::resourceError(Ljava/lang/String;)(key); } return String(value); }-*/; /** * The set of keys associated with this dictionary. * * @return the Dictionary set */ public Set<String> keySet() { HashSet<String> s = new HashSet<String>(); addKeys(s); return s; } @Override public String toString() { return label; } /** * Collection of values associated with this dictionary. * * @return the values */ public Collection<String> values() { ArrayList<String> s = new ArrayList<String>(); addValues(s); return s; } void resourceError(String key) { String error = "Cannot find '" + key + "' in " + this; throw new MissingResourceException(error, this.toString(), key); } private native void addKeys(HashSet<String> s) /*-{ var map = this.@com.google.gwt.i18n.client.Dictionary::dict for (var key in map) { if (map.hasOwnProperty(key)) { s.@java.util.HashSet::add(Ljava/lang/Object;)(key); } } }-*/; private native void addValues(ArrayList<String> s) /*-{ var map = this.@com.google.gwt.i18n.client.Dictionary::dict for (var key in map) { if (map.hasOwnProperty(key)) { var value = this.@com.google.gwt.i18n.client.Dictionary::get(Ljava/lang/String;)(key); s.@java.util.ArrayList::add(Ljava/lang/Object;)(value); } } }-*/; private native void attach(String name)/*-{ try { if (typeof($wnd[name]) != "object") { @com.google.gwt.i18n.client.Dictionary::resourceErrorBadType(Ljava/lang/String;)(name); } this.@com.google.gwt.i18n.client.Dictionary::dict = $wnd[name]; } catch(e) { @com.google.gwt.i18n.client.Dictionary::resourceErrorBadType(Ljava/lang/String;)(name); } }-*/; }