1 package org.apache.turbine.services.localization;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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 }