001    package org.apache.fulcrum.localization;
002    
003    
004    /*
005     * Licensed to the Apache Software Foundation (ASF) under one
006     * or more contributor license agreements.  See the NOTICE file
007     * distributed with this work for additional information
008     * regarding copyright ownership.  The ASF licenses this file
009     * to you under the Apache License, Version 2.0 (the
010     * "License"); you may not use this file except in compliance
011     * with the License.  You may obtain a copy of the License at
012     *
013     *   http://www.apache.org/licenses/LICENSE-2.0
014     *
015     * Unless required by applicable law or agreed to in writing,
016     * software distributed under the License is distributed on an
017     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018     * KIND, either express or implied.  See the License for the
019     * specific language governing permissions and limitations
020     * under the License.
021     */
022    
023    
024    import java.util.Locale;
025    import java.util.ResourceBundle;
026    
027    import javax.servlet.http.HttpServletRequest;
028    
029    /**
030     * <p>Provides localization functionality using the interface provided
031     * by <code>ResourceBundle</code>, plus leverages a "search path"
032     * style traversal of the <code>ResourceBundle</code> objects named by
033     * the <code>locale.default.bundles</code> to discover a value for a
034     * given key.</p>
035     *
036     * <p>It is suggested that one handle
037     * <a href="http://www.math.fu-berlin.de/~rene/www/java/tutorial/i18n/message/messageFormat.html">dealing with concatenated messages</a>
038     * using <code>MessageFormat</code> and properties files.</p>
039     *
040     * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
041     * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
042     * @author <a href="mailto:leonardr@collab.net">Leonard Richardson</a>
043     * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
044     * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
045     * @version $Id: LocalizationService.java 645885 2008-04-08 12:50:57Z tv $
046     */
047    public interface LocalizationService extends SimpleLocalizationService
048    {
049        String ROLE = LocalizationService.class.getName();
050        String SERVICE_NAME = ROLE;
051    
052        /**
053         * A constant for the HTTP <code>Accept-Language</code> header.
054         */
055        String ACCEPT_LANGUAGE = "Accept-Language";
056    
057        /**
058         * Convenience method to get a ResourceBundle based on name and
059         * HTTP <code>Accept-Language</code> header.
060         *
061         * @param bundleName Name of bundle.
062         * @param languageHeader A String with the language header.
063         * @return A localized ResourceBundle.
064         */
065        ResourceBundle getBundle(String bundleName, String languageHeader);
066    
067        /**
068         * Convenience method to get a ResourceBundle based on HTTP
069         * Accept-Language header in HttpServletRequest.
070         *
071         * @param req The HTTP request to parse the
072         * <code>Accept-Language</code> of.
073         * @return A localized ResourceBundle.
074         */
075        ResourceBundle getBundle(HttpServletRequest req);
076    
077        /**
078         * Convenience method to get a <code>ResourceBundle</code> based
079         * on name and HTTP <code>Accept-Language</code> header from a
080         * <code>HttpServletRequest</code>.
081         *
082         * @param bundleName Name of bundle.
083         * @param req The HTTP request to parse the
084         * <code>Accept-Language</code> of.
085         * @return A localized ResourceBundle.
086         */
087        ResourceBundle getBundle(String bundleName, HttpServletRequest req);
088    
089        /**
090         * Attempts to pull the <code>Accept-Language</code> header out of
091         * the <code>HttpServletRequest</code> object and then parse it.
092         * If the header is not present, it will return a
093         * <code>null</code> <code>Locale</code>.
094         *
095         * @param req The HTTP request to parse the
096         * <code>Accept-Language</code> of.
097         * @return The parsed locale.
098         */
099        Locale getLocale(HttpServletRequest req);
100    
101        /**
102         * Parses the <code>Accept-Language</code> header and attempts to
103         * create a <code>Locale</code> from it.
104         *
105         * @param header The language header (i.e. <code>en, es;q=0.8,
106         * zh-TW;q=0.1</code>), or <code>null</code> for the locale
107         * corresponding to the default language and country.
108         * @return The parsed locale, or a locale corresponding to the
109         * language and country defaults.
110         */
111        Locale getLocale(String languageHeader);
112    }