View Javadoc

1   package org.apache.turbine.services.localization;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.util.Locale;
20  import java.util.ResourceBundle;
21  import javax.servlet.http.HttpServletRequest;
22  
23  import org.apache.turbine.services.Service;
24  
25  /***
26   * <p>Provides localization functionality using the interface provided
27   * by <code>ResourceBundle</code>, plus leverages a "search path"
28   * style traversal of the <code>ResourceBundle</code> objects named by
29   * the <code>locale.default.bundles</code> to discover a value for a
30   * given key.</p>
31   *
32   * <p>It is suggested that one handle
33   * <a href="http://www.math.fu-berlin.de/~rene/www/java/tutorial/i18n/message/messageFormat.html">dealing with concatenated messages</a>
34   * using <code>MessageFormat</code> and properties files.</p>
35   *
36   * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
37   * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
38   * @author <a href="mailto:leonardr@collab.net">Leonard Richardson</a>
39   * @version $Id: LocalizationService.java 264148 2005-08-29 14:21:04Z henning $
40   */
41  public interface LocalizationService
42          extends Service
43  {
44      /***
45       * The name of this service.
46       */
47      String SERVICE_NAME = "LocalizationService";
48  
49      /***
50       * A constant for the HTTP <code>Accept-Language</code> header.
51       */
52      String ACCEPT_LANGUAGE = "Accept-Language";
53  
54      /***
55       * Retrieves the default language (as specified in the config
56       * file).
57       */
58      String getDefaultLanguage();
59  
60      /***
61       * Retrieves the default country (as specified in the config
62       * file).
63       */
64      String getDefaultCountry();
65  
66      /***
67       * Retrieves the name of the default bundle (as specified in the
68       * config file), or the first in the list if there are more than
69       * one.
70       */
71      String getDefaultBundleName();
72  
73      /***
74       * Retrieves the list of names of bundles to search by default for
75       * <code>ResourceBundle</code> keys (as specified in the config
76       * file).
77       *
78       * @return The list of configured bundle names.
79       */
80      String[] getBundleNames();
81  
82      /***
83       * Convenience method to get a default ResourceBundle.
84       *
85       * @return A localized ResourceBundle.
86       */
87      ResourceBundle getBundle();
88  
89      /***
90       * Returns a ResourceBundle given the bundle name and the default
91       * locale information supplied by the configuration.
92       *
93       * @param bundleName Name of bundle.
94       * @return A localized ResourceBundle.
95       */
96      ResourceBundle getBundle(String bundleName);
97  
98      /***
99       * Convenience method to get a ResourceBundle based on name and
100      * HTTP Accept-Language header.
101      *
102      * @param bundleName Name of bundle.
103      * @param languageHeader A String with the language header.
104      * @return A localized ResourceBundle.
105      */
106     ResourceBundle getBundle(String bundleName, String languageHeader);
107 
108     /***
109      * Convenience method to get a ResourceBundle based on HTTP
110      * Accept-Language header in HttpServletRequest.
111      *
112      * @param req The HTTP request to parse the
113      * <code>Accept-Language</code> of.
114      * @return A localized ResourceBundle.
115      */
116     ResourceBundle getBundle(HttpServletRequest req);
117 
118     /***
119      * Convenience method to get a ResourceBundle based on name and
120      * HTTP Accept-Language header in HttpServletRequest.
121      *
122      * @param bundleName Name of bundle.
123      * @param req The HTTP request to parse the
124      * <code>Accept-Language</code> of.
125      * @return A localized ResourceBundle.
126      */
127     ResourceBundle getBundle(String bundleName, HttpServletRequest req);
128 
129     /***
130      * Convenience method to get a ResourceBundle based on name and
131      * Locale.
132      *
133      * @param bundleName Name of bundle.
134      * @param locale A Locale.
135      * @return A localized ResourceBundle.
136      */
137     ResourceBundle getBundle(String bundleName, Locale locale);
138 
139     /***
140      * Attempts to pull the <code>Accept-Language</code> header out of
141      * the <code>HttpServletRequest</code> object and then parse it.
142      * If the header is not present, it will return a
143      * <code>null</code> <code>Locale</code>.
144      *
145      * @param req The HTTP request to parse the
146      * <code>Accept-Language</code> of.
147      * @return The parsed locale.
148      */
149     Locale getLocale(HttpServletRequest req);
150 
151     /***
152      * This method parses the <code>Accept-Language</code> header and
153      * attempts to create a <code>Locale</code> out of it.
154      *
155      * @param languageHeader The <code>Accept-Language</code> HTTP
156      * header.
157      * @return The parsed locale.
158      */
159     Locale getLocale(String languageHeader);
160 
161     /***
162      * This method sets the name of the defaultBundle.
163      *
164      * @param defaultBundle Name of default bundle.
165      */
166     void setBundle(String defaultBundle);
167 
168     /***
169      * Tries very hard to return a value, looking first in the
170      * specified bundle, then searching list of default bundles
171      * (giving precedence to earlier bundles over later bundles).
172      *
173      * @param bundleName Name of the bundle to look in first.
174      * @param locale Locale to get text for.
175      * @param key Name of the text to retrieve.
176      * @return Localized text.
177      */
178     String getString(String bundleName, Locale locale, String key);
179 
180 }