Google Web Toolkit
Search Google Code:

# Interface Constants

public interface Constants
extends Localizable
// Extended by `ConstantsWithLookup`
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).