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