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 }