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}