Constants


1   /*
2    * Copyright 2006 Google Inc.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5    * use this file except in compliance with the License. You may obtain a copy of
6    * the License at
7    * 
8    * http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations under
14   * the License.
15   */
16  package com.google.gwt.i18n.client;
17  
18  /**
19   * A tag interface that facilitates locale-sensitive, compile-time binding of
20   * constant values supplied from properties files. Using
21   * <code>GWT.create(<i>class</i>)</code> to "instantiate" an interface that
22   * extends <code>Constants</code> returns an instance of an automatically
23   * generated subclass that is implemented using values from a property file
24   * selected based on locale.
25   * 
26   * <p>
27   * Locale is specified at run time using a meta tag or query string as described
28   * for {@link com.google.gwt.i18n.client.Localizable}.
29   * </p>
30   * 
31   * <h3>Extending <code>Constants</code></h3>
32   * To use <code>Constants</code>, begin by defining an interface that extends
33   * it. Each interface method is referred to as a <i>constant accessor</i>, and
34   * the name of each constant accessor is assumed to match the name of a property
35   * defined in a properties file. For example,
36   * 
37   * {@example com.google.gwt.examples.i18n.NumberFormatConstants}
38   * 
39   * expects to find properties named <code>decimalSeparator</code> and
40   * <code>thousandsSeparator</code> in an associated properties file. For
41   * example, the following properties would be used for a German locale:
42   * 
43   * {@gwt.include com/google/gwt/examples/i18n/NumberFormatConstants_de_DE.properties}
44   * 
45   * <p>
46   * The following example demonstrates how to use constant accessors defined in
47   * the interface above:
48   * 
49   * {@example com.google.gwt.examples.i18n.NumberFormatConstantsExample#useNumberFormatConstants()}
50   * </p>
51   * 
52   * <p>
53   * It is also possible to change the property name bound to a constant accessor
54   * using the <code>gwt.key</code> doc comment. For example,
55   * {@example com.google.gwt.examples.i18n.NumberFormatConstantsWithAltKey}
56   * 
57   * would match the names of the following properties:
58   * 
59   * {@gwt.include com/google/gwt/examples/i18n/NumberFormatConstantsWithAltKey_en.properties}
60   * </p>
61   * 
62   * <h3>Defining Constant Accessors</h3>
63   * Constant accessors must be of the form
64   * 
65   * <pre>T methodName()</pre>
66   * 
67   * where <code>T</code> is one of the return types in the following table:
68   * 
69   * <table>
70   * <tr>
71   * <th><nobr>If the return type is...&#160;&#160;&#160;</nobr></th>
72   * <th>The property value is interpreted as...</th>
73   * </tr>
74   * 
75   * <tr>
76   * <td><code>String</code></td>
77   * <td>A plain string value</td>
78   * </tr>
79   * 
80   * <tr>
81   * <td><code>String[]</code></td>
82   * <td>A comma-separated array of strings; use '<code>\\,</code>' to escape
83   * commas</td>
84   * </tr>
85   * 
86   * <tr>
87   * <td><code>int</code></td>
88   * <td>An <code>int</code> value, checked during compilation</td>
89   * </tr>
90   * 
91   * <tr>
92   * <td><code>float</code></td>
93   * <td>A <code>float</code> value, checked during compilation</td>
94   * </tr>
95   * 
96   * <tr>
97   * <td><code>double</code></td>
98   * <td>A <code>double</code> value, checked during compilation</td>
99   * </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...&#160;&#160;</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 }
199
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags