Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.gwt.i18n.client
Interface Constants

All Superinterfaces:
  Localizable, LocalizableResource

All Known Subinterfaces:
  ConstantsWithLookup

    public interface Constants

extends LocalizableResource

A tag interface that facilitates locale-sensitive, compile-time binding of constant values supplied from properties files. Using `GWT.create(class)` to "instantiate" an interface that extends `Constants` returns an instance of an automatically generated subclass that is implemented using values from a property file selected based on locale.

Locale is specified at run time using a meta tag or query string as described for `Localizable`.

### Extending `Constants`

To use `Constants`, begin by defining an interface that extends it. Each interface method is referred to as a constant accessor, 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 `@Key` annotation or a different generation method using `@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,

>     public interface NumberFormatConstants extends Constants {
>       /**
>        * @return the localized decimal separator
>        */
>       String decimalSeparator();

>       /**
>        * @return the localized thousands separator
>        */
>       String thousandsSeparator();
>     }

expects to find properties named `decimalSeparator` and `thousandsSeparator` in an associated properties file. For example, the following properties would be used for a German locale:

>     decimalSeparator = ,
>     thousandsSeparator = .

The following example demonstrates how to use constant accessors defined in the interface above:

>     public void useNumberFormatConstants() {
>       NumberFormatConstants constants = (NumberFormatConstants) GWT.create(NumberFormatConstants.class);
>       String decimalSep = constants.decimalSeparator();
>       String thousandsSep = constants.thousandsSeparator();
>       String msg = "Decimals are separated using '" + decimalSep + "'";
>       msg += ", and thousands are separated using '" + thousandsSep + "'";
>       showMessage(msg);
>     }

Here is the same example using annotations to store the default values:

>     public interface NumberFormatConstantsAnnot extends Constants {
>       /**
>        * @return the localized decimal separator
>        */
>       @DefaultStringValue(".")
>       String decimalSeparator();

>       /**
>        * @return the localized thousands separator
>        */
>       @DefaultStringValue(",")
>       String thousandsSeparator();
>     }

It is also possible to change the property name bound to a constant accessor using the `@Key` annotation. For example,

>     public interface NumberFormatConstantsWithAltKey extends Constants {
>       /**
>        * @return the localized decimal separator
>        */
>       @Key("fmt.sep.decimal")
>       String decimalSeparator();

>       /**
>        * @return the localized thousands separator
>        */
>       @Key("fmt.sep.thousands")
>       String thousandsSeparator();
>     }

would match the names of the following properties:

>     fmt.sep.decimal = .
>     fmt.sep.thousands = ,

### Defining Constant Accessors

Constant accessors must be of the form

    T methodName()

where `T` is one of the return types in the following table:

If the return type is... | The property value is interpreted as... | Annotation to use for default value
--- | --- | ---
`String` | A plain string value | `@DefaultStringValue`
`String[]` | A comma-separated array of strings; use '`\\,`' to escape commas | `@DefaultStringArrayValue`
`int` | An `int` value, checked during compilation | `@DefaultIntValue`
`float` | A `float` value, checked during compilation | `@DefaultFloatValue`
`double` | A `double` value, checked during compilation | `@DefaultDoubleValue`
`boolean` | A `boolean` value ("true" or "false"), checked during compilation | `@DefaultBooleanValue`
`Map` | 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 | `@DefaultStringMapValue`

As an example of a `Map`, for the following property file:

     a = X
     b = Y
     c = Z
     someMap = a, b, c

the constant accessor `someMap()` would return a `Map` that maps `"a"` onto `"X"`, `"b"` onto `"Y"`, and `"c"` onto `"Z"`. Iterating through this `Map` will return the keys or entries in declaration order.

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:

>     public interface AnnotConstants extends Constants {
>       int CURRENCY_DECIMALS = 2;

>       @DefaultStringValue("Orange")
>       @Meaning("the color")
>       String orange();

>       @DefaultStringValue("Red")
>       String red();

>       @DefaultIntValue(CURRENCY_DECIMALS)
>       int currencyDecimals();

>       @DefaultIntValue(CURRENCY_DECIMALS * 2)
>       int extraCurrencyDecimals();

>       @DefaultStringArrayValue({"zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine"})
>       String[] numberNames();

>       @DefaultDoubleValue(3.14159)
>       double pi();

>       @DefaultStringMapValue({"key1", "comma,value", "comma,key", "value2"})
>       Map map();
>     }

### Binding to Properties Files

If an interface `org.example.foo.Intf` extends `Constants` and the following code is used to create an object from `Intf` as follows:

    Intf constants = (Intf)GWT.create(Intf.class);

then `constants` 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 (`org/example/foo/`), (2) have a base filename matching the interface name (`Intf`), and (3) have a suffix that most closely matches the locale. Suffixes are matched as follows:

If `locale` is... | The properties file that binds to `org.example.foo.Intf` is...
--- | ---
unspecified | `org/example/foo/Intf.properties`
`x` | `org/example/foo/Intf_x.properties` if it exists and defines the property being sought, otherwise treated as if `locale` were unspecified
`x_Y` | `org/example/foo/Intf_x_Y.properties` if it exists and defines the property being sought, otherwise treated as if `locale` were `x`

where `x` and `Y` are language and locale codes, as described in the documentation for `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.

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.

### Required Module

Modules that use this interface should inherit `com.google.gwt.i18n.I18N`.

>     <module>
>       <!-- other inherited modules, such as com.google.gwt.user.User -->
>       <inherits name="com.google.gwt.i18n.I18N"/>
>       <!-- additional module settings -->
>     </module>

### Note

You should not directly implement this interface or interfaces derived from it since an implementation is generated automatically when message interfaces are created using `GWT.create(Class)`.

Nested Class Summary
`static interface` | `Constants.DefaultBooleanValue` Default boolean value to be used if no translation is found (and also used as the source for translation).
`static interface` | `Constants.DefaultDoubleValue` Default double value to be used if no translation is found (and also used as the source for translation).
`static interface` | `Constants.DefaultFloatValue` Default float value to be used if no translation is found (and also used as the source for translation).
`static interface` | `Constants.DefaultIntValue` Default integer value to be used if no translation is found (and also used as the source for translation).
`static interface` | `Constants.DefaultStringArrayValue` Default string array value to be used if no translation is found (and also used as the source for translation).
`static interface` | `Constants.DefaultStringMapValue` Default string map value to be used if no translation is found (and also used as the source for translation).
`static interface` | `Constants.DefaultStringValue` Default string value to be used if no translation is found (and also used as the source for translation).

Nested classes/interfaces inherited from interface com.google.gwt.i18n.client.LocalizableResource
`LocalizableResource.DefaultLocale, LocalizableResource.Description, LocalizableResource.Generate, LocalizableResource.GeneratedFrom, LocalizableResource.GenerateKeys, LocalizableResource.Key, LocalizableResource.Meaning`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD