    001// Copyright 2006, 2009, 2010, 2012 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
    015package org.apache.tapestry5.services;
    016
    017import java.util.List;
    018import java.util.Locale;
    019
    020import org.apache.tapestry5.SelectModel;
    021import org.apache.tapestry5.ioc.annotations.IncompatibleChange;
    022
    023/**
    024 * Sets the thread's locale given a desired locale. Note that the desired locale is just a hint. It will try to honor it
    025 * but there is no guarantee that it will be used as is.
    026 * <p/>
    027 * Localization is controlled by the {@link org.apache.tapestry5.SymbolConstants#SUPPORTED_LOCALES} symbol.
    028 */
    029public interface LocalizationSetter
    030{
    031    /**
    032     * Determines if the provided potential locale name (presumably, extracted from a request URL) is a supported locale
    033     * name. A call to this method will always set the {@link org.apache.tapestry5.ioc.services.ThreadLocale} (either
    034     * to the provided locale, if supported, or to the default locale). If the locale name is supported, it will also
    035     * set the {@link org.apache.tapestry5.services.PersistentLocale} (which may affect how page and event links are
    036     * generated, to persist the selected locale across requests).
    037     * <p/>
    038     * Note that locale names <strong>are</strong> case sensitive.
    039     *
    040     * @param localeName
    041     *            name of locale to check (which may be blank or not a locale name)
    042     * @return true if the locale name is supported and the {@link org.apache.tapestry5.services.PersistentLocale} was
    043     *         set
    044     * @since 5.1.0.0
    045     */
    046    boolean setLocaleFromLocaleName(String localeName);
    047
    048    /**
    049     * Allows the locale to be set from a specified locale name (which may be narrowed or defaulted to a support
    050     * locale). Does not set the persistent locale.
    051     *
    052     * @param localeName
    053     *            locale in effect for this request
    054     * @since 5.1.0.0
    055     */
    056    @IncompatibleChange(release = "5.4", details = "typo is method name corrected")
    057    void setNonPersistentLocaleFromLocaleName(String localeName);
    058
    059    /**
    060     * Returns a list of supported locales, as per the {@link org.apache.tapestry5.SymbolConstants#SUPPORTED_LOCALES}
    061     * symbol.
    062     *
    063     * @since 5.2.0
    064     */
    065    List<Locale> getSupportedLocales();
    066
    067    /**
    068     * Checks to see if the indicated locale name is a supported locale name (that may have been
    069     * incorporated into a request path). This is an important part of
    070     * {@linkplain ComponentEventLinkEncoder#decodePageRenderRequest(Request) decoding a request}.
    071     *
    072     * @since 5.2.0
    073     */
    074    boolean isSupportedLocaleName(String localeName);
    075
    076    /**
    077     * Returns the supported locales packaged as a model. The label for each locale comes from
    078     * {@link Locale#getDisplayName(Locale)} (in that locale).
    079     *
    080     * @since 5.2.0
    081     */
    082    SelectModel getSupportedLocalesModel();
    083
    084    /**
    085     * Converts a locale name into a Locale. The result is cached.
    086     *
    087     * @since 5.2.0
    088     */
    089    Locale toLocale(String localeName);
    090}