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

All Known Subinterfaces:
  ConstantsWithLookup

    public interface Constants

extends Localizable

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 the name of each constant accessor is assumed to match the name of a property defined in a properties file. 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);
>     }

It is also possible to change the property name bound to a constant accessor using the `gwt.key` doc comment. For example,

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

>       /**
>        * @gwt.key fmt.sep.thousands
>        * @return the localized thousands separator
>        */
>       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...
--- | ---
`String` | A plain string value
`String[]` | A comma-separated array of strings; use '`\\,`' to escape commas
`int` | An `int` value, checked during compilation
`float` | A `float` value, checked during compilation
`double` | A `double` value, checked during compilation
`boolean` | A `boolean` value ("true" or "false"), checked during compilation
`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

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"`.

### 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 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`.

>     <!--                                                                        -->
>     <!-- 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   -->
>     <!-- 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. License for the specific language governing permissions and   -->
>     <!-- limitations under the License.                                         -->

>     <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)`.

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