KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > google > gwt > i18n > client > Messages


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
17 package com.google.gwt.i18n.client;
18
19 /**
20  * A tag interface that facilitates locale-sensitive, compile-time binding of
21  * messages supplied from properties files. Using
22  * <code>GWT.create(<i>class</i>)</code> to "instantiate" an interface that
23  * extends <code>Messages</code> returns an instance of an automatically
24  * generated subclass that is implemented using message templates from a
25  * property file selected based on locale. Message templates are based on a
26  * subset of the format used by <a
27  * HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/text/MessageFormat.html"><code>MessageFormat</code></a>.
28  *
29  * <p>
30  * Locale is specified at run time using a meta tag or query string as described
31  * for {@link com.google.gwt.i18n.client.Localizable}.
32  * </p>
33  *
34  * <h3>Extending <code>Messages</code></h3>
35  * To use <code>Messages</code>, begin by defining an interface that extends
36  * it. Each interface method is referred to as a <i>message accessor</i>, and
37  * the name of each message accessor is assumed to match the name of a property
38  * defined in a properties file. For example,
39  *
40  * {@example com.google.gwt.examples.i18n.GameStatusMessages}
41  *
42  * expects to find properties named <code>turnsLeft</code> and
43  * <code>currentScore</code> in an associated properties file, formatted as
44  * message templates taking two arguments and one argument, respectively. For
45  * example, the following properties would correctly bind to the
46  * <code>GameStatusMessages</code> interface:
47  *
48  * {@gwt.include com/google/gwt/examples/i18n/GameStatusMessages.properties}
49  *
50  * <p>
51  * The following example demonstrates how to use constant accessors defined in
52  * the interface above:
53  *
54  * {@example com.google.gwt.examples.i18n.GameStatusMessagesExample#beginNewGameRound(String)}
55  * </p>
56  *
57  * <p>
58  * It is possible to change the property name bound to a message accessor using
59  * the <code>gwt.key</code> doc comment, exactly as is done for constant
60  * accessors. See {@link Constants} for an example.
61  * </p>
62  *
63  * <h3>Defining Message Accessors</h3>
64  * Message accessors must be of the form
65  *
66  * <pre>String methodName(<i>optional-params</i>)</pre>
67  *
68  * and parameters may be of any type. Arguments are converted into strings at
69  * runtime using Java string concatenation syntax (the '+' operator), which
70  * uniformly handles primitives, <code>null</code>, and invoking
71  * <code>toString()</code> to format objects.
72  *
73  * <p>
74  * Compile-time checks are performed to ensure that the number of placeholders
75  * in a message template (e.g. <code>{0}</code>) matches the number of
76  * parameters supplied.
77  * </p>
78  *
79  * <h3>Binding to Properties Files</h3>
80  * Interfaces extending <code>Messages</code> are bound to properties file
81  * using the same algorithm as interfaces extending <code>Constants</code>.
82  * See the documentation for {@link Constants} for a description of the
83  * algorithm.
84  *
85  * <h3>Required Module</h3>
86  * Modules that use this interface should inherit
87  * <code>com.google.gwt.i18n.I18N</code>.
88  *
89  * {@gwt.include com/google/gwt/examples/i18n/InheritsExample.gwt.xml}
90  *
91  * <h3>Note</h3>
92  * You should not directly implement this interface or interfaces derived from
93  * it since an implementation is generated automatically when message interfaces
94  * are created using {@link com.google.gwt.core.client.GWT#create(Class)}.
95  */
96 public interface Messages extends Localizable {
97 }
98
Popular Tags