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
015package org.apache.tapestry5.services;
016
017import java.util.List;
018import java.util.Locale;
019
020import 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 */
028public 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}