Google Web Toolkit (Beta)
Search this site:

# Interface Messages

public interface Messages
extends Localizable
A tag interface that facilitates locale-sensitive, compile-time binding of messages supplied from properties files. Using `GWT.create(class)` to "instantiate" an interface that extends `Messages` returns an instance of an automatically generated subclass that is implemented using message templates from a property file selected based on locale. Message templates are based on a subset of the format used by `MessageFormat`.

Locale is specified at run time using a meta tag or query string as described for Localizable.

### Extending `Messages`

To use `Messages`, begin by defining an interface that extends it. Each interface method is referred to as a message accessor, and the name of each message accessor is assumed to match the name of a property defined in a properties file. For example,

    public interface GameStatusMessages extends Messages {
      /**
       * @param username the name of a player
       * @param numTurns the number of turns remaining
       * @return a message specifying the remaining turns for a player
       */
      String turnsLeft(String username, int numTurns);

      /**
       * @param numPoints the number of points
       * @return a message describing the current score for the current player
       */
      String currentScore(int numPoints);
    }

expects to find properties named `turnsLeft` and `currentScore` in an associated properties file, formatted as message templates taking two arguments and one argument, respectively. For example, the following properties would correctly bind to the `GameStatusMessages` interface:

    turnsLeft = Turns left for player ''{0}'': {1}
    currentScore = Current score: {0}

The following example demonstrates how to use constant accessors defined in the interface above:

    public void beginNewGameRound(String username) {
      GameStatusMessages messages = (GameStatusMessages) GWT.create(GameStatusMessages.class);

      // Tell the new player how many turns he or she has left.
      int turnsLeft = computeTurnsLeftForPlayer(username);
      showMessage(messages.turnsLeft(username, turnsLeft));

      // Tell the current player his or her score.
      int currentScore = computeScore(username);
      setCurrentPlayer(username);
      showMessage(messages.currentScore(currentScore));
    }

It is possible to change the property name bound to a message accessor using the `gwt.key` doc comment, exactly as is done for constant accessors. See Constants for an example.

### Defining Message Accessors

Message accessors must be of the form

    String methodName(optional-params)

and parameters may be of any type. Arguments are converted into strings at runtime using Java string concatenation syntax (the '+' operator), which uniformly handles primitives, `null`, and invoking `toString()` to format objects.

Compile-time checks are performed to ensure that the number of placeholders in a message template (e.g. `{0}`) matches the number of parameters supplied.

### Binding to Properties Files

Interfaces extending `Messages` are bound to properties file using the same algorithm as interfaces extending `Constants`. See the documentation for Constants for a description of the algorithm.

### Required Module

Modules that use this interface should inherit `com.google.gwt.i18n.I18N`.

    <!--                                                                        -->
    <!-- Copyright 2007 Google Inc.                                             -->
    <!-- Licensed under the Apache License, Version 2.0 (the "License"); you    -->
    <!-- may not use this file except in compliance with the License. You may   -->
    <!-- may obtain a copy of the License at                                    -->
    <!--                                                                        -->
    <!-- http://www.apache.org/licenses/LICENSE-2.0                             -->
    <!--                                                                        -->
    <!-- Unless required by applicable law or agreed to in writing, software    -->
    <!-- distributed under the License is distributed on an "AS IS" BASIS,      -->
    <!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or        -->
    <!-- implied. License for the specific language governing permissions and   -->
    <!-- limitations under the License.                                         -->

    <module>
      <!-- other inherited modules, such as com.google.gwt.user.User -->
      <inherits name="com.google.gwt.i18n.I18N"/>
      <!-- additional module settings -->
    </module>

### 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 GWT.create(Class).