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
20
21
22 import java.util.Locale;
23 import java.util.ResourceBundle;
24 import javax.servlet.http.HttpServletRequest;
25
26 import org.apache.turbine.services.Service;
27
28 /***
29 * <p>Provides localization functionality using the interface provided
30 * by <code>ResourceBundle</code>, plus leverages a "search path"
31 * style traversal of the <code>ResourceBundle</code> objects named by
32 * the <code>locale.default.bundles</code> to discover a value for a
33 * given key.</p>
34 *
35 * <p>It is suggested that one handle
36 * <a href="http://www.math.fu-berlin.de/~rene/www/java/tutorial/i18n/message/messageFormat.html">dealing with concatenated messages</a>
37 * using <code>MessageFormat</code> and properties files.</p>
38 *
39 * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
40 * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
41 * @author <a href="mailto:leonardr@collab.net">Leonard Richardson</a>
42 * @version $Id: LocalizationService.java 534527 2007-05-02 16:10:59Z tv $
43 */
44 public interface LocalizationService
45 extends Service
46 {
47 /***
48 * The name of this service.
49 */
50 String SERVICE_NAME = "LocalizationService";
51
52 /***
53 * A constant for the HTTP <code>Accept-Language</code> header.
54 */
55 String ACCEPT_LANGUAGE = "Accept-Language";
56
57 /***
58 * Retrieves the default language (as specified in the config
59 * file).
60 */
61 String getDefaultLanguage();
62
63 /***
64 * Retrieves the default country (as specified in the config
65 * file).
66 */
67 String getDefaultCountry();
68
69 /***
70 * Retrieves the name of the default bundle (as specified in the
71 * config file), or the first in the list if there are more than
72 * one.
73 */
74 String getDefaultBundleName();
75
76 /***
77 * Retrieves the list of names of bundles to search by default for
78 * <code>ResourceBundle</code> keys (as specified in the config
79 * file).
80 *
81 * @return The list of configured bundle names.
82 */
83 String[] getBundleNames();
84
85 /***
86 * Convenience method to get a default ResourceBundle.
87 *
88 * @return A localized ResourceBundle.
89 */
90 ResourceBundle getBundle();
91
92 /***
93 * Returns a ResourceBundle given the bundle name and the default
94 * locale information supplied by the configuration.
95 *
96 * @param bundleName Name of bundle.
97 * @return A localized ResourceBundle.
98 */
99 ResourceBundle getBundle(String bundleName);
100
101 /***
102 * Convenience method to get a ResourceBundle based on name and
103 * HTTP Accept-Language header.
104 *
105 * @param bundleName Name of bundle.
106 * @param languageHeader A String with the language header.
107 * @return A localized ResourceBundle.
108 */
109 ResourceBundle getBundle(String bundleName, String languageHeader);
110
111 /***
112 * Convenience method to get a ResourceBundle based on HTTP
113 * Accept-Language header in HttpServletRequest.
114 *
115 * @param req The HTTP request to parse the
116 * <code>Accept-Language</code> of.
117 * @return A localized ResourceBundle.
118 */
119 ResourceBundle getBundle(HttpServletRequest req);
120
121 /***
122 * Convenience method to get a ResourceBundle based on name and
123 * HTTP Accept-Language header in HttpServletRequest.
124 *
125 * @param bundleName Name of bundle.
126 * @param req The HTTP request to parse the
127 * <code>Accept-Language</code> of.
128 * @return A localized ResourceBundle.
129 */
130 ResourceBundle getBundle(String bundleName, HttpServletRequest req);
131
132 /***
133 * Convenience method to get a ResourceBundle based on name and
134 * Locale.
135 *
136 * @param bundleName Name of bundle.
137 * @param locale A Locale.
138 * @return A localized ResourceBundle.
139 */
140 ResourceBundle getBundle(String bundleName, Locale locale);
141
142 /***
143 * Attempts to pull the <code>Accept-Language</code> header out of
144 * the <code>HttpServletRequest</code> object and then parse it.
145 * If the header is not present, it will return a
146 * <code>null</code> <code>Locale</code>.
147 *
148 * @param req The HTTP request to parse the
149 * <code>Accept-Language</code> of.
150 * @return The parsed locale.
151 */
152 Locale getLocale(HttpServletRequest req);
153
154 /***
155 * This method parses the <code>Accept-Language</code> header and
156 * attempts to create a <code>Locale</code> out of it.
157 *
158 * @param languageHeader The <code>Accept-Language</code> HTTP
159 * header.
160 * @return The parsed locale.
161 */
162 Locale getLocale(String languageHeader);
163
164 /***
165 * This method sets the name of the defaultBundle.
166 *
167 * @param defaultBundle Name of default bundle.
168 */
169 void setBundle(String defaultBundle);
170
171 /***
172 * Tries very hard to return a value, looking first in the
173 * specified bundle, then searching list of default bundles
174 * (giving precedence to earlier bundles over later bundles).
175 *
176 * @param bundleName Name of the bundle to look in first.
177 * @param locale Locale to get text for.
178 * @param key Name of the text to retrieve.
179 * @return Localized text.
180 */
181 String getString(String bundleName, Locale locale, String key);
182
183 /***
184 * Formats a localized value using the provided object.
185 *
186 * @param bundleName The bundle in which to look for the localizable text.
187 * @param locale The locale for which to format the text.
188 * @param key The identifier for the localized text to retrieve,
189 * @param arg1 The object to use as {0} when formatting the localized text.
190 * @return Formatted localized text.
191 * @see #format(String, Locale, String, Object[])
192 */
193 String format(String bundleName, Locale locale,
194 String key, Object arg1);
195
196 /***
197 * Formats a localized value using the provided objects.
198 *
199 * @param bundleName The bundle in which to look for the localizable text.
200 * @param locale The locale for which to format the text.
201 * @param key The identifier for the localized text to retrieve,
202 * @param arg1 The object to use as {0} when formatting the localized text.
203 * @param arg2 The object to use as {1} when formatting the localized text.
204 * @return Formatted localized text.
205 * @see #format(String, Locale, String, Object[])
206 */
207 String format(String bundleName, Locale locale,
208 String key, Object arg1, Object arg2);
209
210 /***
211 * Formats a localized value using the provided objects.
212 *
213 * @param bundleName The bundle in which to look for the localizable text.
214 * @param locale The locale for which to format the text.
215 * @param key The identifier for the localized text to retrieve,
216 * @param args The objects to use as {0}, {1}, etc. when
217 * formatting the localized text.
218 * @return Formatted localized text.
219 */
220 String format(String bundleName, Locale locale,
221 String key, Object[] args);
222 }