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 }