    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005// http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5.services;
    014
    015import java.util.List;
    016import java.util.Locale;
    017
    018import org.apache.tapestry5.SelectModel;
    019import org.apache.tapestry5.http.services.Request;
    020import org.apache.tapestry5.ioc.annotations.IncompatibleChange;
    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 *
    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     *
    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    @IncompatibleChange(release = "5.4", details = "typo is method name corrected")
    056    void setNonPersistentLocaleFromLocaleName(String localeName);
    057
    058    /**
    059     * Allows the locale to be set from the locale of the client as determined from the request headers (which may
    060     * be narrowed or defaulted to a supported locale). Does not set the persistent locale.
    061     *
    062     * @param request
    063     *            incoming request
    064     * @since 5.8.3
    065     */
    066    void setNonPersistentLocaleFromRequest(Request request);
    067
    068    /**
    069     * Returns a list of supported locales, as per the {@link org.apache.tapestry5.SymbolConstants#SUPPORTED_LOCALES}
    070     * symbol.
    071     *
    072     * @since 5.2.0
    073     */
    074    List<Locale> getSupportedLocales();
    075
    076    /**
    077     * Checks to see if the indicated locale name is a supported locale name (that may have been
    078     * incorporated into a request path). This is an important part of
    079     * {@linkplain ComponentEventLinkEncoder#decodePageRenderRequest(Request) decoding a request}.
    080     *
    081     * @since 5.2.0
    082     */
    083    boolean isSupportedLocaleName(String localeName);
    084
    085    /**
    086     * Returns the supported locales packaged as a model. The label for each locale comes from
    087     * {@link Locale#getDisplayName(Locale)} (in that locale).
    088     *
    089     * @since 5.2.0
    090     */
    091    SelectModel getSupportedLocalesModel();
    092
    093    /**
    094     * Converts a locale name into a Locale. The result is cached.
    095     *
    096     * @since 5.2.0
    097     */
    098    Locale toLocale(String localeName);
    099}