    001    // Copyright 2006, 2009, 2010 The Apache Software Foundation
    002    //
    003    // Licensed under the Apache License, Version 2.0 (the "License");
    004    // you may not use this file except in compliance with the License.
    005    // You may obtain a copy of the License at
    006    //
    007    // http://www.apache.org/licenses/LICENSE-2.0
    008    //
    009    // Unless required by applicable law or agreed to in writing, software
    010    // distributed under the License is distributed on an "AS IS" BASIS,
    011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012    // See the License for the specific language governing permissions and
    013    // limitations under the License.
    014
    015    package org.apache.tapestry5.services;
    016
    017    import java.util.List;
    018    import java.util.Locale;
    019
    020    import org.apache.tapestry5.SelectModel;
    021
    022    /**
    023     * Sets the thread's locale given a desired locale. Note that the desired locale is just a hint. It will try to honor it
    024     * but there is no guarantee that it will be used as is.
    025     * <p/>
    026     * Localization is controlled by the {@link org.apache.tapestry5.SymbolConstants#SUPPORTED_LOCALES} symbol.
    027     */
    028    public interface LocalizationSetter
    029    {
    030        /**
    031         * Determines if the provided potential locale name (presumably, extracted from a request URL) is a supported locale
    032         * name. A call to this method will always set the {@link org.apache.tapestry5.ioc.services.ThreadLocale} (either
    033         * to the provided locale, if supported, or to the default locale). If the locale name is supported, it will also
    034         * set the {@link org.apache.tapestry5.services.PersistentLocale} (which may affect how page and event links are
    035         * generated, to persist the selected locale across requests).
    036         * <p/>
    037         * Note that locale names <strong>are</strong> case sensitive.
    038         *
    039         * @param localeName
    040         *            name of locale to check (which may be blank or not a locale name)
    041         * @return true if the locale name is supported and the {@link org.apache.tapestry5.services.PersistentLocale} was
    042         *         set
    043         * @since 5.1.0.0
    044         */
    045        boolean setLocaleFromLocaleName(String localeName);
    046
    047        /**
    048         * Allows the locale to be set from a specified locale name (which may be narrowed or defaulted to a support
    049         * locale). Does not set the persistent locale.
    050         *
    051         * @param localeName
    052         *            locale in effect for this request
    053         * @since 5.1.0.0
    054         */
    055        void setNonPeristentLocaleFromLocaleName(String localeName);
    056
    057        /**
    058         * Returns a list of supported locales, as per the {@link org.apache.tapestry5.SymbolConstants#SUPPORTED_LOCALES}
    059         * symbol.
    060         *
    061         * @since 5.2.0
    062         */
    063        List<Locale> getSupportedLocales();
    064
    065        /**
    066         * Checks to see if the indicated locale name is a supported locale name (that may have been
    067         * incorporated into a request path). This is an important part of
    068         * {@linkplain ComponentEventLinkEncoder#decodePageRenderRequest(Request) decoding a request}.
    069         *
    070         * @since 5.2.0
    071         */
    072        boolean isSupportedLocaleName(String localeName);
    073
    074        /**
    075         * Returns the supported locales packaged as a model. The label for each locale comes from
    076         * {@link Locale#getDisplayName(Locale)} (in that locale).
    077         *
    078         * @since 5.2.0
    079         */
    080        SelectModel getSupportedLocalesModel();
    081
    082        /**
    083         * Converts a locale name into a Locale. The result is cached.
    084         *
    085         * @since 5.2.0
    086         */
    087        Locale toLocale(String localeName);
    088    }