com.google.gwt.i18n.shared.GwtLocale.java Source code

Introduction

Here is the source code for com.google.gwt.i18n.shared.GwtLocale.java

Source

/*
 * Copyright 2009 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 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. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.gwt.i18n.shared;

import java.util.List;

/**
 * Class representing GWT locales and conversion to/from other formats.
 *
 * These locales correspond to BCP47.
 */
public interface GwtLocale extends Comparable<GwtLocale> {

    String DEFAULT_LOCALE = "default";

    /**
     * The default comparison is a lexical ordering.
     */
    int compareTo(GwtLocale o);

    /**
     * Returns the list of aliases for this locale.  The canonical form of the
     * current locale is always first on the list.
     *
     * Language/region codes have changed over time, so some systems continue to
     * use the older codes.  Aliases allow GWT to use the official Unicode CLDR
     * locales while still interoperating with such systems.
     *
     * @return alias list
     */
    List<GwtLocale> getAliases();

    /**
     * Returns the locale as a fixed-format string suitable for use in searching
     * for localized resources.  The format is language_Script_REGION_VARIANT,
     * where language is a 2-8 letter code (possibly with 3-letter extensions),
     * script is a 4-letter code with an initial capital letter, region is a
     * 2-character country code or a 3-digit region code, and variant is a 5-8
     * character (may be 4 if the first character is numeric) code.  If a
     * component is missing, its preceding _ is also omitted.  If this is the
     * default locale, the empty string will be returned.
     *
     * @return String representing locale
     */
    String getAsString();

    /**
     * Returns this locale in canonical form.
     * <ul>
     *  <li>Deprecated language/region tags are replaced with official versions
     *  <li>Default scripts are removed (including region-specific defaults for
     *      Chinese)
     *  <li>no/nb/nn are normalized
     *  <li>Default region for zh_Hans and zh_Hant if none specified
     * </ul>
     *
     * @return GwtLocale instance
     */
    GwtLocale getCanonicalForm();

    /**
     * Returns the complete list of locales to search for the current locale.
     * This list will always start with the canonical form of this locale, and
     * end with "default", and include all appropriate aliases along the way.
     *
     * @return search list
     */
    List<GwtLocale> getCompleteSearchList();

    /**
     * Returns a list of locales to search for, in order of preference.  The
     * current locale is always first on the list.  Aliases are not included
     * in the list -- use {@link #getAliases} to expand those.
     *
     * @return inheritance list
     */
    List<GwtLocale> getInheritanceChain();

    /**
     * Returns the language portion of the locale, or null if none.
     */
    String getLanguage();

    /**
     * Returns the language portion of the locale, or the empty string if none.
     */
    String getLanguageNotNull();

    /**
     * Returns the region portion of the locale, or null if none.
     */
    String getRegion();

    /**
     * Returns the region portion of the locale, or the empty string if none.
     */
    String getRegionNotNull();

    /**
     * Returns the script portion of the locale, or null if none.
     */
    String getScript();

    /**
     * Returns the script portion of the locale, or the empty string if none.
     */
    String getScriptNotNull();

    /**
     * Returns the variant portion of the locale, or null if none.
     */
    String getVariant();

    /**
     * Returns the variant portion of the locale, or the empty string if none.
     */
    String getVariantNotNull();

    /**
     * Returns true if this locale inherits from the specified locale.  Note that
     * locale.inheritsFrom(locale) is false -- if you want that to be true, you
     * should just use locale.getInheritanceChain().contains(x).
     *
     * @param parent locale to test against
     * @return true if parent is an ancestor of this locale
     */
    boolean inheritsFrom(GwtLocale parent);

    /**
     * Returns true if this is the default or root locale.
     */
    boolean isDefault();

    /**
     * Returns a human readable string -- "default" or the same as getAsString().
     */
    String toString();

    /**
     * Checks if this locale uses the same script as another locale.
     *
     * @param other
     * @return true if the scripts are the same
     */
    boolean usesSameScript(GwtLocale other);
}