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}