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 }