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.MissingResourceException;
026 import java.util.ResourceBundle;
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 * @author <a href="mailto:mcconnell@apache.org">Stephen McConnell</a>
043 * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
044 * @version $Id: LocalizationService.java 535465 2007-05-05 06:58:06Z tv $
045 */
046 public interface SimpleLocalizationService
047 {
048 String ROLE = SimpleLocalizationService.class.getName();
049 String SERVICE_NAME = ROLE;
050
051 /**
052 * Retrieves the default language (as specified in the config
053 * file).
054 */
055 String getDefaultLanguage();
056
057 /**
058 * Retrieves the default country (as specified in the config
059 * file).
060 */
061 String getDefaultCountry();
062
063 /**
064 * Retrieves the default Locale (as created from default
065 * language and default country).
066 */
067 Locale getDefaultLocale();
068
069 /**
070 * Retrieves the name of the default bundle (as specified in the
071 * config file), or the first in the list if there are more than
072 * one.
073 */
074 String getDefaultBundleName();
075
076 /**
077 * Retrieves the list of names of bundles to search by default for
078 * <code>ResourceBundle</code> keys (as specified in the config
079 * file).
080 *
081 * @return The list of configured bundle names.
082 */
083 String[] getBundleNames();
084
085 /**
086 * Convenience method to get the default <code>ResourceBundle</code>.
087 *
088 * @return A localized <code>ResourceBundle</code>.
089 */
090 ResourceBundle getBundle();
091
092 /**
093 * Returns a ResourceBundle given the bundle name and the default
094 * locale information supplied by the configuration.
095 *
096 * @param bundleName Name of bundle.
097 * @return A localized ResourceBundle.
098 */
099 ResourceBundle getBundle(String bundleName);
100
101 /**
102 * Convenience method to get a ResourceBundle based on name and
103 * Locale.
104 *
105 * @param bundleName Name of bundle.
106 * @param locale A Locale.
107 * @return A localized ResourceBundle.
108 */
109 ResourceBundle getBundle(String bundleName, Locale locale);
110
111 /**
112 * Tries very hard to return a value, looking first in the
113 * specified bundle, then searching list of default bundles
114 * (giving precedence to earlier bundles over later bundles).
115 *
116 * @param bundleName Name of the bundle to look in first.
117 * @param locale Locale to get text for.
118 * @param key Name of the text to retrieve.
119 * @return Localized text.
120 */
121 String getString(String bundleName, Locale locale, String key) throws MissingResourceException;
122
123 /**
124 * This method sets the name of the defaultBundle.
125 *
126 * @param defaultBundle Name of default bundle.
127 */
128 void setBundle(String defaultBundle);
129
130 /**
131 * Formats a localized value using the provided object.
132 *
133 * @param bundleName The bundle in which to look for the localizable text.
134 * @param locale The locale for which to format the text.
135 * @param key The identifier for the localized text to retrieve,
136 * @param arg1 The object to use as {0} when formatting the localized text.
137 * @return Formatted localized text.
138 * @see #format(String, Locale, String, Object[])
139 */
140 String format(String bundleName, Locale locale,
141 String key, Object arg1);
142
143 /**
144 * Formats a localized value using the provided objects.
145 *
146 * @param bundleName The bundle in which to look for the localizable text.
147 * @param locale The locale for which to format the text.
148 * @param key The identifier for the localized text to retrieve,
149 * @param arg1 The object to use as {0} when formatting the localized text.
150 * @param arg2 The object to use as {1} when formatting the localized text.
151 * @return Formatted localized text.
152 * @see #format(String, Locale, String, Object[])
153 */
154 String format(String bundleName, Locale locale,
155 String key, Object arg1, Object arg2);
156
157 /**
158 * Formats a localized value using the provided objects.
159 *
160 * @param bundleName The bundle in which to look for the localizable text.
161 * @param locale The locale for which to format the text.
162 * @param key The identifier for the localized text to retrieve,
163 * @param args The objects to use as {0}, {1}, etc. when
164 * formatting the localized text.
165 * @return Formatted localized text.
166 */
167 String format(String bundleName, Locale locale,
168 String key, Object[] args);
169 }