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    }