| 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
com.google.gwt.i18n.client.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,
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:
The following example demonstrates how to use constant accessors defined in
the interface above:
It is also possible to change the property name bound to a constant accessor
using the gwt.key doc comment. For example,
would match the names of the following properties:
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
com.google.gwt.i18n.client.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.
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
com.google.gwt.core.client.GWT.create(Class) .
|