01: /*
02: * Copyright 2007 Google Inc.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
05: * use this file except in compliance with the License. You may obtain a copy of
06: * the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
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.5.0/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: }
|