001    // Copyright 2007, 2008, 2009 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.Locale;
018    
019    /**
020     * Manages the persistent locale stored in the browser (inside the URL).
021     *
022     * @see LocalizationSetter#setLocaleFromLocaleName(String)
023     * @see org.apache.tapestry5.services.LocalizationSetter
024     * @see org.apache.tapestry5.services.ComponentEventLinkEncoder
025     */
026    public interface PersistentLocale
027    {
028        /**
029         * Sets the locale value that will be encoded into the response. This must match a locale configured via {@link
030         * org.apache.tapestry5.SymbolConstants#SUPPORTED_LOCALES}.
031         *
032         * @throws IllegalArgumentException if the locale is not valid
033         */
034        void set(Locale locale);
035    
036        /**
037         * Gets the locale obtained from the request, or null if the response did not indicate a specific locale (in which
038         * case the active locale may have been determined from request headers).
039         */
040        Locale get();
041    
042        /**
043         * @return true if a locale was present in the request URL; false otherwise.
044         */
045        boolean isSet();
046    }