Java tutorial
/* * Copyright 2008 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 * messages supplied from various sources.Using * <code>GWT.create(<i>class</i>)</code> to "instantiate" an interface that * extends <code>Messages</code> returns an instance of an automatically * generated subclass that is implemented using message templates selected based * on locale. Message templates are based on a subset of the format used by <a * href="http://download.oracle.com/javase/1.5.0/docs/api/java/text/MessageFormat.html"> * <code>MessageFormat</code></a>. Note in particular that single quotes are * used to quote other characters, and should be doubled for a literal single * quote. * * <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>Messages</code></h3> * To use <code>Messages</code>, begin by defining an interface that extends * it. Each interface method is referred to as a <i>message accessor</i>, and * its corresponding message template 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}. Additionally, if * plural forms are used on a given method the plural form is added as a suffix * to the key, such as <code>widgets[one]</code> for the singular version of * the <code>widgets</code> message. The resulting key is used to find * translated versions of the message from any supported input file, such as * Java properties files. For example, * * {@example com.google.gwt.examples.i18n.GameStatusMessages} * * expects to find properties named <code>turnsLeft</code> and * <code>currentScore</code> in an associated properties file, formatted as * message templates taking two arguments and one argument, respectively. For * example, the following properties would correctly bind to the * <code>GameStatusMessages</code> interface: * * {@gwt.include com/google/gwt/examples/i18n/GameStatusMessages.properties} * * <p> * The following example demonstrates how to use constant accessors defined in * the interface above: * * {@example com.google.gwt.examples.i18n.GameStatusMessagesExample#beginNewGameRound(String)} * </p> * * <p>The following example shows how to use annotations to store the default strings * in the source file itself, rather than needing a properties file (you still need * properties files for the translated strings): * * {@example com.google.gwt.examples.i18n.GameStatusMessagesAnnot} * </p> * * <p>In this example, calling <code>msg.turnsLeft("John", 13)</code> would * return the string <code>"Turns left for player 'John': 13"</code>. * </p> * * <h3>Defining Message Accessors</h3> * Message accessors must be of the form * * <pre>String methodName(<i>optional-params</i>)</pre> * * and parameters may be of any type. Arguments are converted into strings at * runtime using Java string concatenation syntax (the '+' operator), which * uniformly handles primitives, <code>null</code>, and invoking * <code>toString()</code> to format objects. * * <p> * Compile-time checks are performed to ensure that the number of placeholders * in a message template (e.g. <code>{0}</code>) matches the number of * parameters supplied. * </p> * * <p> * Integral arguments may be used to select the proper plural form to use for * different locales. To do this, mark the particular argument with * {@code @PluralCount} (a plural rule may be specified with * {@code @PluralCount} if necessary, but you will almost never need to * do this). The actual plural forms for the default locale can be supplied in a * {@code @PluralText} annotation on the method, such as * <code>@PluralText({"one", "You have one widget"})</code>, or they can be * supplied in the properties file as {@code methodkey[one]=You have one widget}. Note * that non-default plural forms are not inherited between locales, because the * different locales may have different plural rules (especially {@code default} and * anything else and those which use different scripts such as {@code sr_Cyrl} and * {@code sr_Latn} [one of which would likely be the default], but also subtle cases * like {@code pt} and {@code pt_BR}). * </p> * * <p> * Additionally, individual arguments can be marked as optional (ie, GWT will * not give an error if a particular translation does not reference the * argument) with the {@code @Optional} annotation, and an example may be supplied to * the translator with the {@code @Example(String)} annotation. * </p> * * <h3>Complete Annotations Example</h3> * In addition to the default properties file, default text and additional * metadata may be stored in the source file itself using annotations. A * complete example of using annotations in this way is: * * <code><pre> * @Generate(format = "com.google.gwt.i18n.rebind.format.PropertiesFormat") * @DefaultLocale("en_US") * public interface MyMessages extends Messages { * @Key("1234") * @DefaultText("This is a plain string.") * String oneTwoThreeFour(); * * @DefaultText("You have {0} widgets") * @PluralText({"one", "You have one widget") * String widgetCount(@PluralCount int count); * * @DefaultText("No reference to the argument") * String optionalArg(@Optional String ignored); * * @DefaultText("Your cart total is {0,number,currency}") * @Description("The total value of the items in the shopping cart in local currency") * String totalAmount(@Example("$5.00") double amount); * * @Meaning("the color") * @DefaultMessage("orange") * String orangeColor(); * * @Meaning("the fruit") * @DefaultMessage("orange") * String orangeFruit(); * } * </pre></code> * * <h3>Binding to Properties Files</h3> * Interfaces extending <code>Messages</code> are bound to resource files * using the same algorithm as interfaces extending <code>Constants</code>. * See the documentation for {@link Constants} for a description of the * algorithm. * * <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 Messages extends LocalizableResource { /** * Provides alternate forms of a message, such as are needed when plural * forms are used or a placeholder has known gender. The selection of which * form to use is based on the value of the arguments marked * PluralCount and/or Select. * * <p>Example: * <code><pre> * @DefaultMessage("You have {0} widgets.") * @AlternateMessage({"one", "You have one widget.") * String example(@PluralCount int count); * </pre></code> * </p> * * <p>If multiple {@link PluralCount} or {@link Select} parameters are * supplied, the forms for each, in the order they appear in the parameter * list, are supplied separated by a vertical bar ("|"). Example: * <code><pre> * @DefaultMessage("You have {0} messages and {1} notifications.") * @AlternateMessage({ * "=0|=0", "You have no messages or notifications." * "=0|one", "You have a notification." * "one|=0", "You have a message." * "one|one", "You have one message and one notification." * "other|one", "You have {0} messages and one notification." * "one|other", "You have one message and {1} notifications." * }) * String messages(@PluralCount int msgCount, * @PluralCount int notifyCount); * </pre></code> * * Note that the number of permutations can grow quickly, and that the default * message is used when every {@link PluralCount} or {@link Select} would use * the "other" value. * </p> */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @Documented public @interface AlternateMessage { /** * An array of pairs of strings containing the strings for different forms. * * Each pair is the name of a form followed by the string in the source * locale for that form. Each form name is the name of a plural form if * {@link PluralCount} is used, or the matching value if {@link Select} is * used. An example for a locale that has "none", "one", and "other" plural * forms: * * <code><pre> * @DefaultMessage("{0} widgets") * @AlternateMessage({"none", "No widgets", "one", "One widget"}) * </pre> * * Note that the plural form "other" gets the translation specified in * {@code @DefaultMessage}, as does any {@code @Select} value not * listed. * * If more than one way of selecting a translation exists, they will be * combined, separated with {@code |}, in the order they are supplied as * arguments in the method. For example: * <code><pre> * @DefaultMessage("{0} gave away their {2} widgets") * @AlternateMesssage({ * "MALE|other", "{0} gave away his {2} widgets", * "FEMALE|other", "{0} gave away her {2} widgets", * "MALE|one", "{0} gave away his widget", * "FEMALE|one", "{0} gave away her widget", * "other|one", "{0} gave away their widget", * }) * String giveAway(String name, @Select Gender gender, * @PluralCount int count); * </pre></code> */ String[] value(); } /** * Default text to be used if no translation is found (and also used as the * source for translation). Format should be that expected by * {@link java.text.MessageFormat}. * * <p>Example: * <code><pre> * @DefaultMessage("Don''t panic - you have {0} widgets left") * String example(int count) * </pre></code> * </p> */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @Documented public @interface DefaultMessage { String value(); } /** * An example of the annotated parameter to assist translators. * * <p>Example: * <code><pre> * String example(@Example("/etc/passwd") String fileName) * </pre></code> * </p> */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.PARAMETER) public @interface Example { String value(); } /** * Ignored except on parameters also tagged with {@link PluralCount}, and * provides an offset to be subtracted from the value before a plural rule * is chosen or the value is formatted. Note that "=n" forms are evaluated * before this offset is applied. * * <p>Example: * <code><pre> * @PluralText({"=0", "No one has recommended this movie", * "=1", "{0} has recommended this movie", * "=2", "{0} and {1} have recommended this movie", * "one", "{0}, {1} and one other have recommended this movie"}) * @DefaultMessage("{0}, {1} and {2,number} others have recommended this movie") * String recommenders(@Optional String rec1, @Optional String rec2, * @PluralCount @Offset(2) int count); * </pre></code> * would result in * <code><pre> * recommenders("John", null, 1) => "John has..." * recommenders("John", "Jane", 3) => "John, Jane, and one other..." * recommenders("John", "Jane", 1402) => "John, Jane, and 1,400 others..." * </pre></code> * </p> */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.PARAMETER) public @interface Offset { int value(); } /** * Indicates the specified parameter is optional and need not appear in a * particular translation of this message. * * <p>Example: * <code><pre> * String example(@Optional int count) * </pre></code> * </p> */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.PARAMETER) public @interface Optional { } /** * Provides multiple plural forms based on a count. The selection of which * plural form is performed by a PluralRule implementation. * * This annotation is applied to a single parameter of a Messages subinterface * and indicates that parameter is to be used to choose the proper plural form * of the message. The parameter chosen must be of type short or int. * * Optionally, a class literal referring to a PluralRule implementation can be * supplied as the argument if the standard implementation is insufficient. * * <p>Example: * <code><pre> * @DefaultMessage("You have {0} widgets.") * @AlternateMessage({"one", "You have one widget."}) * String example(@PluralCount int count) * </pre></code> * </p> */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.PARAMETER) public @interface PluralCount { /** * The PluralRule implementation to use for this message. If not specified, * the GWT-supplied one is used instead, which should cover most use cases. * * <p>{@code PluralRule.class} is used as a default value here, which will * be replaced during code generation with the default implementation. * </p> */ // http://bugs.sun.com/view_bug.do?bug_id=6512707 Class<? extends PluralRule> value() default com.google.gwt.i18n.client.PluralRule.class; } /** * Provides multiple plural forms based on a count. The selection of which * plural form to use is based on the value of the argument marked * PluralCount, which may also specify an alternate plural rule to use. * * <p>Example: * <code><pre> * @DefaultMessage("You have {0} widgets.") * @PluralText({"one", "You have one widget.") * String example(@PluralCount int count) * </pre></code> * </p> * * @deprecated use {@link AlternateMessage} instead */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD) @Documented @Deprecated public @interface PluralText { /** * An array of pairs of strings containing the strings for different plural * forms. * * Each pair is the name of the plural form (as returned by * PluralForm.toString) followed by the string for that plural form. An * example for a locale that has "none", "one", and "other" plural forms: * * <code><pre> * @DefaultMessage("{0} widgets") * @PluralText({"none", "No widgets", "one", "One widget"}) * </pre> * * "other" must not be included in this array as it will map to the * DefaultMessage value. */ String[] value(); } /** * Provides multiple forms based on a dynamic parameter. * * This annotation is applied to a single parameter of a Messages subinterface * and indicates that parameter is to be used to choose the proper form of the * message. The parameter chosen must be of type Enum, String, boolean, or a * primitive integral type. This is frequently used to get proper gender for * translations to languages where surrounding words depend on the gender of * a person or noun. This also marks the parameter as {@link Optional}. * * <p>Example: * <code><pre> * @DefaultMessage("{0} likes their widgets.") * @AlternateMessage({ * "FEMALE", "{0} likes her widgets.", * "MALE", "{0} likes his widgets.", * }) * String example(String name, @Select Gender gender) * </pre></code> * </p> */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.PARAMETER) public @interface Select { } }