001: /*
002: * Copyright 2007 Google Inc.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License. You may obtain a copy of
006: * the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013: * License for the specific language governing permissions and limitations under
014: * the License.
015: */
016: package com.google.gwt.i18n.client;
017:
018: /**
019: * A tag interface that facilitates locale-sensitive, compile-time binding of
020: * constant values supplied from properties files. Using
021: * <code>GWT.create(<i>class</i>)</code> to "instantiate" an interface that
022: * extends <code>Constants</code> returns an instance of an automatically
023: * generated subclass that is implemented using values from a property file
024: * selected based on locale.
025: *
026: * <p>
027: * Locale is specified at run time using a meta tag or query string as described
028: * for {@link com.google.gwt.i18n.client.Localizable}.
029: * </p>
030: *
031: * <h3>Extending <code>Constants</code></h3>
032: * To use <code>Constants</code>, begin by defining an interface that extends
033: * it. Each interface method is referred to as a <i>constant accessor</i>, and
034: * the name of each constant accessor is assumed to match the name of a property
035: * defined in a properties file. For example,
036: *
037: * {@example com.google.gwt.examples.i18n.NumberFormatConstants}
038: *
039: * expects to find properties named <code>decimalSeparator</code> and
040: * <code>thousandsSeparator</code> in an associated properties file. For
041: * example, the following properties would be used for a German locale:
042: *
043: * {@gwt.include com/google/gwt/examples/i18n/NumberFormatConstants_de_DE.properties}
044: *
045: * <p>
046: * The following example demonstrates how to use constant accessors defined in
047: * the interface above:
048: *
049: * {@example com.google.gwt.examples.i18n.NumberFormatConstantsExample#useNumberFormatConstants()}
050: * </p>
051: *
052: * <p>
053: * It is also possible to change the property name bound to a constant accessor
054: * using the <code>gwt.key</code> doc comment. For example,
055: * {@example com.google.gwt.examples.i18n.NumberFormatConstantsWithAltKey}
056: *
057: * would match the names of the following properties:
058: *
059: * {@gwt.include com/google/gwt/examples/i18n/NumberFormatConstantsWithAltKey_en.properties}
060: * </p>
061: *
062: * <h3>Defining Constant Accessors</h3>
063: * Constant accessors must be of the form
064: *
065: * <pre>T methodName()</pre>
066: *
067: * where <code>T</code> is one of the return types in the following table:
068: *
069: * <table>
070: * <tr>
071: * <th><nobr>If the return type is...   </nobr></th>
072: * <th>The property value is interpreted as...</th>
073: * </tr>
074: *
075: * <tr>
076: * <td><code>String</code></td>
077: * <td>A plain string value</td>
078: * </tr>
079: *
080: * <tr>
081: * <td><code>String[]</code></td>
082: * <td>A comma-separated array of strings; use '<code>\\,</code>' to escape
083: * commas</td>
084: * </tr>
085: *
086: * <tr>
087: * <td><code>int</code></td>
088: * <td>An <code>int</code> value, checked during compilation</td>
089: * </tr>
090: *
091: * <tr>
092: * <td><code>float</code></td>
093: * <td>A <code>float</code> value, checked during compilation</td>
094: * </tr>
095: *
096: * <tr>
097: * <td><code>double</code></td>
098: * <td>A <code>double</code> value, checked during compilation</td>
099: * </tr>
100: *
101: * <tr>
102: * <td><code>boolean</code></td>
103: * <td>A <code>boolean</code> value ("true" or "false"), checked during
104: * compilation</td>
105: * </tr>
106: *
107: * <tr>
108: * <td><code>Map</code></td>
109: * <td>A comma-separated list of property names, each of which is a key into a
110: * generated map; the value mapped to given key is the value of the property
111: * having named by that key</td>
112: * </tr>
113: *
114: * </table>
115: *
116: * As an example of a <code>Map</code>, for the following property file:
117: *
118: * <pre>
119: * a = X
120: * b = Y
121: * c = Z
122: * someMap = a, b, c
123: * </pre>
124: *
125: * the constant accessor <code>someMap()</code> would return a
126: * <code>Map</code> that maps <code>"a"</code> onto <code>"X"</code>,
127: * <code>"b"</code> onto <code>"Y"</code>, and <code>"c"</code> onto
128: * <code>"Z"</code>.
129: *
130: * <h3>Binding to Properties Files</h3>
131: * If an interface <code>org.example.foo.Intf</code> extends
132: * <code>Constants</code> and the following code is used to create an object
133: * from <code>Intf</code> as follows:
134: *
135: * <pre class="code">Intf constants = (Intf)GWT.create(Intf.class);</pre>
136: *
137: * then <code>constants</code> will be assigned an instance of a generated
138: * class whose constant accessors are implemented by extracting values from a
139: * set of matching properties files. Property values are sought using a
140: * best-match algorithm, and candidate properties files are those which (1)
141: * reside in the same package as the interface (<code>org/example/foo/</code>),
142: * (2) have a base filename matching the interface name (<code>Intf</code>),
143: * and (3) have a suffix that most closely matches the locale. Suffixes are
144: * matched as follows:
145: *
146: * <table>
147: *
148: * <tr>
149: * <th align='left'><nobr>If <code>locale</code> is...  </nobr></th>
150: * <th align='left'>The properties file that binds to
151: * <code>org.example.foo.Intf</code> is...</th>
152: * </tr>
153: *
154: * <tr>
155: * <td><i>unspecified</i></td>
156: * <td><code>org/example/foo/Intf.properties</code></td>
157: * </tr>
158: *
159: * <tr>
160: * <td><code>x</code></td>
161: * <td><code>org/example/foo/Intf_x.properties</code> if it exists and
162: * defines the property being sought, otherwise treated as if
163: * <code>locale</code> were <i>unspecified</i></td>
164: * </tr>
165: *
166: * <tr>
167: * <td><code>x_Y</code></td>
168: * <td><code>org/example/foo/Intf_x_Y.properties</code> if it exists and
169: * defines the property being sought, otherwise treated as if
170: * <code>locale</code> were <code>x</code></td>
171: * </tr>
172: *
173: * </table> where <code>x</code> and <code>Y</code> are language and locale
174: * codes, as described in the documentation for
175: * {@link com.google.gwt.i18n.client.Localizable}.
176: *
177: * <p>
178: * Note that the matching algorithm is applied independently for each constant
179: * accessor. It is therefore possible to create a hierarchy of related
180: * properties files such that an unlocalized properties file acts as a baseline,
181: * and locale-specific properties files may redefine a subset of those
182: * properties, relying on the matching algorithm to prefer localized properties
183: * while still finding unlocalized properties.
184: * </p>
185: *
186: * <h3>Required Module</h3>
187: * Modules that use this interface should inherit
188: * <code>com.google.gwt.i18n.I18N</code>.
189: *
190: * {@gwt.include com/google/gwt/examples/i18n/InheritsExample.gwt.xml}
191: *
192: * <h3>Note</h3>
193: * You should not directly implement this interface or interfaces derived from
194: * it since an implementation is generated automatically when message interfaces
195: * are created using {@link com.google.gwt.core.client.GWT#create(Class)}.
196: */
197: public interface Constants extends Localizable {
198: }
|