001: package org.apache.turbine.services.localization;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.util.Locale;
023: import java.util.ResourceBundle;
024: import javax.servlet.http.HttpServletRequest;
025:
026: import org.apache.turbine.services.Service;
027:
028: /**
029: * <p>Provides localization functionality using the interface provided
030: * by <code>ResourceBundle</code>, plus leverages a "search path"
031: * style traversal of the <code>ResourceBundle</code> objects named by
032: * the <code>locale.default.bundles</code> to discover a value for a
033: * given key.</p>
034: *
035: * <p>It is suggested that one handle
036: * <a href="http://www.math.fu-berlin.de/~rene/www/java/tutorial/i18n/message/messageFormat.html">dealing with concatenated messages</a>
037: * using <code>MessageFormat</code> and properties files.</p>
038: *
039: * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
040: * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>
041: * @author <a href="mailto:leonardr@collab.net">Leonard Richardson</a>
042: * @version $Id: LocalizationService.java 534527 2007-05-02 16:10:59Z tv $
043: */
044: public interface LocalizationService extends Service {
045: /**
046: * The name of this service.
047: */
048: String SERVICE_NAME = "LocalizationService";
049:
050: /**
051: * A constant for the HTTP <code>Accept-Language</code> header.
052: */
053: String ACCEPT_LANGUAGE = "Accept-Language";
054:
055: /**
056: * Retrieves the default language (as specified in the config
057: * file).
058: */
059: String getDefaultLanguage();
060:
061: /**
062: * Retrieves the default country (as specified in the config
063: * file).
064: */
065: String getDefaultCountry();
066:
067: /**
068: * Retrieves the name of the default bundle (as specified in the
069: * config file), or the first in the list if there are more than
070: * one.
071: */
072: String getDefaultBundleName();
073:
074: /**
075: * Retrieves the list of names of bundles to search by default for
076: * <code>ResourceBundle</code> keys (as specified in the config
077: * file).
078: *
079: * @return The list of configured bundle names.
080: */
081: String[] getBundleNames();
082:
083: /**
084: * Convenience method to get a default ResourceBundle.
085: *
086: * @return A localized ResourceBundle.
087: */
088: ResourceBundle getBundle();
089:
090: /**
091: * Returns a ResourceBundle given the bundle name and the default
092: * locale information supplied by the configuration.
093: *
094: * @param bundleName Name of bundle.
095: * @return A localized ResourceBundle.
096: */
097: ResourceBundle getBundle(String bundleName);
098:
099: /**
100: * Convenience method to get a ResourceBundle based on name and
101: * HTTP Accept-Language header.
102: *
103: * @param bundleName Name of bundle.
104: * @param languageHeader A String with the language header.
105: * @return A localized ResourceBundle.
106: */
107: ResourceBundle getBundle(String bundleName, String languageHeader);
108:
109: /**
110: * Convenience method to get a ResourceBundle based on HTTP
111: * Accept-Language header in HttpServletRequest.
112: *
113: * @param req The HTTP request to parse the
114: * <code>Accept-Language</code> of.
115: * @return A localized ResourceBundle.
116: */
117: ResourceBundle getBundle(HttpServletRequest req);
118:
119: /**
120: * Convenience method to get a ResourceBundle based on name and
121: * HTTP Accept-Language header in HttpServletRequest.
122: *
123: * @param bundleName Name of bundle.
124: * @param req The HTTP request to parse the
125: * <code>Accept-Language</code> of.
126: * @return A localized ResourceBundle.
127: */
128: ResourceBundle getBundle(String bundleName, HttpServletRequest req);
129:
130: /**
131: * Convenience method to get a ResourceBundle based on name and
132: * Locale.
133: *
134: * @param bundleName Name of bundle.
135: * @param locale A Locale.
136: * @return A localized ResourceBundle.
137: */
138: ResourceBundle getBundle(String bundleName, Locale locale);
139:
140: /**
141: * Attempts to pull the <code>Accept-Language</code> header out of
142: * the <code>HttpServletRequest</code> object and then parse it.
143: * If the header is not present, it will return a
144: * <code>null</code> <code>Locale</code>.
145: *
146: * @param req The HTTP request to parse the
147: * <code>Accept-Language</code> of.
148: * @return The parsed locale.
149: */
150: Locale getLocale(HttpServletRequest req);
151:
152: /**
153: * This method parses the <code>Accept-Language</code> header and
154: * attempts to create a <code>Locale</code> out of it.
155: *
156: * @param languageHeader The <code>Accept-Language</code> HTTP
157: * header.
158: * @return The parsed locale.
159: */
160: Locale getLocale(String languageHeader);
161:
162: /**
163: * This method sets the name of the defaultBundle.
164: *
165: * @param defaultBundle Name of default bundle.
166: */
167: void setBundle(String defaultBundle);
168:
169: /**
170: * Tries very hard to return a value, looking first in the
171: * specified bundle, then searching list of default bundles
172: * (giving precedence to earlier bundles over later bundles).
173: *
174: * @param bundleName Name of the bundle to look in first.
175: * @param locale Locale to get text for.
176: * @param key Name of the text to retrieve.
177: * @return Localized text.
178: */
179: String getString(String bundleName, Locale locale, String key);
180:
181: /**
182: * Formats a localized value using the provided object.
183: *
184: * @param bundleName The bundle in which to look for the localizable text.
185: * @param locale The locale for which to format the text.
186: * @param key The identifier for the localized text to retrieve,
187: * @param arg1 The object to use as {0} when formatting the localized text.
188: * @return Formatted localized text.
189: * @see #format(String, Locale, String, Object[])
190: */
191: String format(String bundleName, Locale locale, String key,
192: Object arg1);
193:
194: /**
195: * Formats a localized value using the provided objects.
196: *
197: * @param bundleName The bundle in which to look for the localizable text.
198: * @param locale The locale for which to format the text.
199: * @param key The identifier for the localized text to retrieve,
200: * @param arg1 The object to use as {0} when formatting the localized text.
201: * @param arg2 The object to use as {1} when formatting the localized text.
202: * @return Formatted localized text.
203: * @see #format(String, Locale, String, Object[])
204: */
205: String format(String bundleName, Locale locale, String key,
206: Object arg1, Object arg2);
207:
208: /**
209: * Formats a localized value using the provided objects.
210: *
211: * @param bundleName The bundle in which to look for the localizable text.
212: * @param locale The locale for which to format the text.
213: * @param key The identifier for the localized text to retrieve,
214: * @param args The objects to use as {0}, {1}, etc. when
215: * formatting the localized text.
216: * @return Formatted localized text.
217: */
218: String format(String bundleName, Locale locale, String key,
219: Object[] args);
220: }
|