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 java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * A tag interface that facilitates locale-sensitive, compile-time binding of * constant values supplied from properties files. Using * <code>GWT.create(<i>class</i>)</code> to "instantiate" an interface that * extends <code>Constants</code> returns an instance of an automatically * generated subclass that is implemented using values from a property file * selected based on locale. * * <p> * Locale is specified at run time using a meta tag or query string as described * for {@link com.google.gwt.i18n.client.Localizable}. * </p> * * <h3>Extending <code>Constants</code></h3> * To use <code>Constants</code>, begin by defining an interface that extends * it. Each interface method is referred to as a <i>constant accessor</i>, and * its corresponding localized value is loaded based on the key for that method. * The default key is simply the unqualified name of the method, but can be specified * directly with an {@code @Key} annotation or a different generation method using * {@code @GenerateKeys}. Also, the default value can be specified in an annotation * rather than a default properties file (and some key generators may require the value * to be given in the source file via annotations). For example, * * {@example com.google.gwt.examples.i18n.NumberFormatConstants} * * expects to find properties named <code>decimalSeparator</code> and * <code>thousandsSeparator</code> in an associated properties file. For * example, the following properties would be used for a German locale: * * {@gwt.include com/google/gwt/examples/i18n/NumberFormatConstants_de_DE.properties} * * <p> * The following example demonstrates how to use constant accessors defined in * the interface above: * * {@example com.google.gwt.examples.i18n.NumberFormatConstantsExample#useNumberFormatConstants()} * </p> * * <p> * Here is the same example using annotations to store the default values: * * {@example com.google.gwt.examples.i18n.NumberFormatConstantsAnnot} * </p> * * <p> * It is also possible to change the property name bound to a constant accessor * using the {@code @Key} annotation. For example, * {@example com.google.gwt.examples.i18n.NumberFormatConstantsWithAltKey} * * would match the names of the following properties: * * {@gwt.include com/google/gwt/examples/i18n/NumberFormatConstantsWithAltKey_en.properties} * </p> * * <h3>Defining Constant Accessors</h3> * Constant accessors must be of the form * * <pre>T methodName()</pre> * * where <code>T</code> is one of the return types in the following table: * * <table> * <tr> * <th><nobr>If the return type is...   </nobr></th> * <th>The property value is interpreted as...</th> * <th>Annotation to use for default value</th> * </tr> * * <tr> * <td><code>String</code></td> * <td>A plain string value</td> * <td>{@code @DefaultStringValue}</td> * </tr> * * <tr> * <td><code>String[]</code></td> * <td>A comma-separated array of strings; use '<code>\\,</code>' to escape * commas</td> * <td>{@code @DefaultStringArrayValue}</td> * </tr> * * <tr> * <td><code>int</code></td> * <td>An <code>int</code> value, checked during compilation</td> * <td>{@code @DefaultIntValue}</td> * </tr> * * <tr> * <td><code>float</code></td> * <td>A <code>float</code> value, checked during compilation</td> * <td>{@code @DefaultFloatValue}</td> * </tr> * * <tr> * <td><code>double</code></td> * <td>A <code>double</code> value, checked during compilation</td> * <td>{@code @DefaultDoubleValue}</td> * </tr> * * <tr> * <td><code>boolean</code></td> * <td>A <code>boolean</code> value ("true" or "false"), checked during * compilation</td> * <td>{@code @DefaultBooleanValue}</td> * </tr> * * <tr> * <td><code>Map</code></td> * <td>A comma-separated list of property names, each of which is a key into a * generated map; the value mapped to given key is the value of the property * having named by that key</td> * <td>{@code @DefaultStringMapValue}</td> * </tr> * * </table> * * <p> * As an example of a <code>Map</code>, for the following property file: * </p> * * <pre> * a = X * b = Y * c = Z * someMap = a, b, c * </pre> * * <p> * the constant accessor <code>someMap()</code> would return a * <code>Map</code> that maps <code>"a"</code> onto <code>"X"</code>, * <code>"b"</code> onto <code>"Y"</code>, and <code>"c"</code> onto * <code>"Z"</code>. Iterating through this <code>Map</code> will return * the keys or entries in declaration order. * </p> * * <p>The benefit of using annotations, aside from not having to switch to * a different file to enter the default values, is that you can make use * of compile-time constants and not worrying about quoting commas. For example: * * {@example com.google.gwt.examples.i18n.AnnotConstants} * </p> * * <h3>Binding to Properties Files</h3> * If an interface <code>org.example.foo.Intf</code> extends * <code>Constants</code> and the following code is used to create an object * from <code>Intf</code> as follows: * * <pre class="code">Intf constants = (Intf)GWT.create(Intf.class);</pre> * * then <code>constants</code> will be assigned an instance of a generated * class whose constant accessors are implemented by extracting values from a * set of matching properties files. Property values are sought using a * best-match algorithm, and candidate properties files are those which (1) * reside in the same package as the interface (<code>org/example/foo/</code>), * (2) have a base filename matching the interface name (<code>Intf</code>), * and (3) have a suffix that most closely matches the locale. Suffixes are * matched as follows: * * <table> * * <tr> * <th align='left'><nobr>If <code>locale</code> is...  </nobr></th> * <th align='left'>The properties file that binds to * <code>org.example.foo.Intf</code> is...</th> * </tr> * * <tr> * <td><i>unspecified</i></td> * <td><code>org/example/foo/Intf.properties</code></td> * </tr> * * <tr> * <td><code>x</code></td> * <td><code>org/example/foo/Intf_x.properties</code> if it exists and * defines the property being sought, otherwise treated as if * <code>locale</code> were <i>unspecified</i></td> * </tr> * * <tr> * <td><code>x_Y</code></td> * <td><code>org/example/foo/Intf_x_Y.properties</code> if it exists and * defines the property being sought, otherwise treated as if * <code>locale</code> were <code>x</code></td> * </tr> * * </table> where <code>x</code> and <code>Y</code> are language and locale * codes, as described in the documentation for * {@link com.google.gwt.i18n.client.Localizable}. Note that default values * supplied in the source file in annotations take precedence over those in * the default properties file, if it is also present. * * <p> * Note that the matching algorithm is applied independently for each constant * accessor. It is therefore possible to create a hierarchy of related * properties files such that an unlocalized properties file acts as a baseline, * and locale-specific properties files may redefine a subset of those * properties, relying on the matching algorithm to prefer localized properties * while still finding unlocalized properties. * </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} * * <h3>Note</h3> * You should not directly implement this interface or interfaces derived from * it since an implementation is generated automatically when message interfaces * are created using {@link com.google.gwt.core.client.GWT#create(Class)}. */ public interface Constants extends LocalizableResource { /** * Default boolean value to be used if no translation is found (and also used as the * source for translation). No quoting (other than normal Java string quoting) * is done. */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @Documented public @interface DefaultBooleanValue { boolean value(); } /** * Default double value to be used if no translation is found (and also used as the * source for translation). No quoting (other than normal Java string quoting) * is done. */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @Documented public @interface DefaultDoubleValue { double value(); } /** * Default float value to be used if no translation is found (and also used as the * source for translation). No quoting (other than normal Java string quoting) * is done. */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @Documented public @interface DefaultFloatValue { float value(); } /** * Default integer value to be used if no translation is found (and also used as the * source for translation). No quoting (other than normal Java string quoting) * is done. */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @Documented public @interface DefaultIntValue { int value(); } /** * Default string array value to be used if no translation is found (and also * used as the source for translation). No quoting (other than normal Java * string quoting) is done. * * Note that in the corresponding properties/etc file, commas are used to separate * elements of the array unless they are preceded with a backslash. */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @Documented public @interface DefaultStringArrayValue { String[] value(); } /** * Default string map value to be used if no translation is found (and also * used as the source for translation). No quoting (other than normal Java * string quoting) is done. The strings for the map are supplied in key/value * pairs. * * Note that in the corresponding properties/etc file, new keys can be supplied * with the name of the method (or its corresponding key) listing the set of keys * for the map separated by commas (commas can be part of the keys by preceding * them with a backslash). In either case, further entries have keys matching * the key in this map. */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @Documented public @interface DefaultStringMapValue { /** * Must be key-value pairs. */ String[] value(); } /** * Default string value to be used if no translation is found (and also used as the * source for translation). No quoting (other than normal Java string quoting) * is done. */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @Documented public @interface DefaultStringValue { String value(); } }