001 /** 002 * Copyright (c) 2000-2011 Liferay, Inc. All rights reserved. 003 * 004 * The contents of this file are subject to the terms of the Liferay Enterprise 005 * Subscription License ("License"). You may not use this file except in 006 * compliance with the License. You can obtain a copy of the License by 007 * contacting Liferay, Inc. See the License for the specific language governing 008 * permissions and limitations under the License, including but not limited to 009 * distribution rights of the Software. 010 * 011 * 012 * 013 */ 014 015 package com.liferay.portal.kernel.util; 016 017 import com.liferay.portal.kernel.json.JSONObject; 018 019 import java.util.Locale; 020 import java.util.Map; 021 022 import javax.portlet.PortletPreferences; 023 import javax.portlet.PortletRequest; 024 025 /** 026 * Stores and retrieves localized strings from XML, and provides utility methods 027 * for updating localizations from JSON, portlet requests, and maps. Used for 028 * adding localization to strings, most often for model properties. 029 * 030 * <p> 031 * Localized values are cached in this class rather than in the value object 032 * since value objects get flushed from cache fairly quickly. Though lookups 033 * performed on a key based on an XML file are slower than lookups done at the 034 * value object level in general, the value object will get flushed at a rate 035 * which works against the performance gain. The cache is a soft hash map which 036 * prevents memory leaks within the system while enabling the cache to live 037 * longer than in a weak hash map. 038 * </p> 039 * 040 * @author Alexander Chow 041 * @author Jorge Ferrer 042 * @author Mauro Mariuzzo 043 * @author Julio Camarero 044 * @author Brian Wing Shun Chan 045 */ 046 public interface Localization { 047 048 /** 049 * Deserializes the JSON object into a map of locales and localized strings. 050 * 051 * @param jsonObject the JSON object 052 * @return the locales and localized strings 053 */ 054 public Object deserialize(JSONObject jsonObject); 055 056 /** 057 * Returns the available locales from the localizations XML 058 * 059 * @param xml the localizations XML 060 * @return the language IDs of the available locales 061 */ 062 public String[] getAvailableLocales(String xml); 063 064 /** 065 * Returns the default locale from the localizations XML. 066 * 067 * @param xml the localizations XML 068 * @return the language ID of the default locale, or the system default 069 * locale if the default locale cannot be retrieved from the XML 070 */ 071 public String getDefaultLocale(String xml); 072 073 /** 074 * Returns the localized string from the localizations XML in the language. 075 * Uses the default language if no localization exists for the requested 076 * language. 077 * 078 * @param xml the localizations XML 079 * @param requestedLanguageId the ID of the language 080 * @return the localized string 081 */ 082 public String getLocalization(String xml, String requestedLanguageId); 083 084 /** 085 * Returns the localized string from the localizations XML in the language, 086 * optionally using the default language if the no localization exists for 087 * the requested language. 088 * 089 * @param xml the localizations XML 090 * @param requestedLanguageId the ID of the language 091 * @param useDefault whether to use the default language if no localization 092 * exists for the requested language 093 * @return the localized string. If <code>useDefault</code> is 094 * <code>false</code> and no localization exists for the requested 095 * language, an empty string will be returned. 096 */ 097 public String getLocalization( 098 String xml, String requestedLanguageId, boolean useDefault); 099 100 /** 101 * Returns a map of locales and localized strings for the parameter in the 102 * preferences container. 103 * 104 * @param preferences the preferences container 105 * @param parameter the prefix of the parameters containing the localized 106 * strings. Each localization will be loaded from a parameter with 107 * this prefix, followed by an underscore, and the language ID. 108 * @return the locales and localized strings 109 */ 110 public Map<Locale, String> getLocalizationMap( 111 PortletPreferences preferences, String parameter); 112 113 /** 114 * Returns a map of locales and localized strings for the parameter in the 115 * portlet request. 116 * 117 * @param portletRequest the portlet request 118 * @param parameter the prefix of the parameters containing the localized 119 * strings. Each localization will be loaded from a parameter with 120 * this prefix, followed by an underscore, and the language ID. 121 * @return the locales and localized strings 122 */ 123 public Map<Locale, String> getLocalizationMap( 124 PortletRequest portletRequest, String parameter); 125 126 /** 127 * Returns a map of locales and localized strings from the localizations 128 * XML. 129 * 130 * @param xml the localizations XML 131 * @return the locales and localized strings 132 */ 133 public Map<Locale, String> getLocalizationMap(String xml); 134 135 /** 136 * Returns the localizations XML for the parameter in the portlet request, 137 * attempting to get data from the preferences container when it is not 138 * available in the portlet request. 139 * 140 * @param preferences the preferences container 141 * @param portletRequest the portlet request 142 * @param parameter the prefix of the parameters containing the localized 143 * strings. Each localization will be loaded from a parameter with 144 * this prefix, followed by an underscore, and the language ID. 145 * @return the locales and localized strings 146 */ 147 public String getLocalizationXmlFromPreferences( 148 PortletPreferences preferences, PortletRequest portletRequest, 149 String parameter); 150 151 /** 152 * @deprecated Use {@link #getLocalizationMap(PortletRequest, String)} 153 * instead. 154 */ 155 public Map<Locale, String> getLocalizedParameter( 156 PortletRequest portletRequest, String parameter); 157 158 /** 159 * Returns the localized preferences key in the language. Generally this is 160 * just the preferences key, followed by an underscore, and the language ID. 161 * 162 * @param key the preferences key 163 * @param languageId the ID of the language 164 * @return the localized preferences key 165 */ 166 public String getPreferencesKey(String key, String languageId); 167 168 /** 169 * Returns the localized preferences value for the key in the language. Uses 170 * the default language if no localization exists for the requested 171 * language. 172 * 173 * @param preferences the preferences container 174 * @param key the preferences key 175 * @param languageId the ID of the language 176 * @return the localized preferences value 177 */ 178 public String getPreferencesValue( 179 PortletPreferences preferences, String key, String languageId); 180 181 /** 182 * Returns the localized preferences value for the key in the language, 183 * optionally using the default language if the no localization exists for 184 * the requested language. 185 * 186 * @param preferences the preferences container 187 * @param key the preferences key 188 * @param languageId the ID of the language 189 * @param useDefault whether to use the default language if no localization 190 * exists for the requested language 191 * @return the localized preferences value. If <code>useDefault</code> is 192 * <code>false</code> and no localization exists for the requested 193 * language, an empty string will be returned. 194 */ 195 public String getPreferencesValue( 196 PortletPreferences preferences, String key, String languageId, 197 boolean useDefault); 198 199 /** 200 * Returns the localized preferences values for the key in the language. 201 * Uses the default language if no localization exists for the requested 202 * language. 203 * 204 * @param preferences the preferences container 205 * @param key the preferences key 206 * @param languageId the ID of the language 207 * @return the localized preferences values 208 */ 209 public String[] getPreferencesValues( 210 PortletPreferences preferences, String key, String languageId); 211 212 /** 213 * Returns the localized preferences values for the key in the language, 214 * optionally using the default language if the no localization exists for 215 * the requested language. 216 * 217 * @param preferences the preferences container 218 * @param key the preferences key 219 * @param languageId the ID of the language 220 * @param useDefault whether to use the default language if no localization 221 * exists for the requested language 222 * @return the localized preferences values. If <code>useDefault</code> is 223 * <code>false</code> and no localization exists for the requested 224 * language, an empty array will be returned. 225 */ 226 public String[] getPreferencesValues( 227 PortletPreferences preferences, String key, String languageId, 228 boolean useDefault); 229 230 /** 231 * Removes the localization for the language from the localizations XML. 232 * Stores the localized strings as characters in the XML. 233 * 234 * @param xml the localizations XML 235 * @param key the name of the localized string, such as "Title" 236 * @param requestedLanguageId the ID of the language 237 * @return the localizations XML with the language removed 238 */ 239 public String removeLocalization( 240 String xml, String key, String requestedLanguageId); 241 242 /** 243 * Removes the localization for the language from the localizations XML, 244 * optionally storing the localized strings as CDATA in the XML. 245 * 246 * @param xml the localizations XML 247 * @param key the name of the localized string, such as "Title" 248 * @param requestedLanguageId the ID of the language 249 * @param cdata whether to store localized strings as CDATA in the XML 250 * @return the localizations XML with the language removed 251 */ 252 public String removeLocalization( 253 String xml, String key, String requestedLanguageId, boolean cdata); 254 255 /** 256 * Removes the localization for the language from the localizations XML, 257 * optionally storing the localized strings as CDATA in the XML. 258 * 259 * @param xml the localizations XML 260 * @param key the name of the localized string, such as "Title" 261 * @param requestedLanguageId the ID of the language 262 * @param cdata whether to store localized strings as CDATA in the XML 263 * @param localized whether there is a localized field 264 * @return the localizations XML with the language removed 265 */ 266 public String removeLocalization( 267 String xml, String key, String requestedLanguageId, boolean cdata, 268 boolean localized); 269 270 /** 271 * Sets the localized preferences values for the parameter in the portlet 272 * request. 273 * 274 * @param portletRequest the portlet request 275 * @param preferences the preferences container 276 * @param parameter the prefix of the parameters containing the localized 277 * strings. Each localization will be loaded from a parameter with 278 * this prefix, followed by an underscore, and the language ID. 279 * @throws Exception if an exception occurred 280 */ 281 public void setLocalizedPreferencesValues ( 282 PortletRequest portletRequest, PortletPreferences preferences, 283 String parameter) 284 throws Exception; 285 286 /** 287 * Sets the localized preferences value for the key in the language. 288 * 289 * @param preferences the preferences container 290 * @param key the preferences key 291 * @param languageId the ID of the language 292 * @param value the localized value 293 * @throws Exception if an exception occurred 294 */ 295 public void setPreferencesValue( 296 PortletPreferences preferences, String key, String languageId, 297 String value) 298 throws Exception; 299 300 /** 301 * Sets the localized preferences values for the key in the language. 302 * 303 * @param preferences the preferences container 304 * @param key the preferences key 305 * @param languageId the ID of the language 306 * @param values the localized values 307 * @throws Exception if an exception occurred 308 */ 309 public void setPreferencesValues( 310 PortletPreferences preferences, String key, String languageId, 311 String[] values) 312 throws Exception; 313 314 /** 315 * Updates the localized string for the system default language in the 316 * localizations XML. Stores the localized strings as characters in the XML. 317 * 318 * @param xml the localizations XML 319 * @param key the name of the localized string, such as "Title" 320 * @param value the localized string 321 * @return the updated localizations XML 322 */ 323 public String updateLocalization(String xml, String key, String value); 324 325 /** 326 * Updates the localized string for the language in the localizations XML. 327 * Stores the localized strings as characters in the XML. 328 * 329 * @param xml the localizations XML 330 * @param key the name of the localized string, such as "Title" 331 * @param value the localized string 332 * @param requestedLanguageId the ID of the language 333 * @return the updated localizations XML 334 */ 335 public String updateLocalization( 336 String xml, String key, String value, String requestedLanguageId); 337 338 /** 339 * Updates the localized string for the language in the localizations XML 340 * and changes the default language. Stores the localized strings as 341 * characters in the XML. 342 * 343 * @param xml the localizations XML 344 * @param key the name of the localized string, such as "Title" 345 * @param value the localized string 346 * @param requestedLanguageId the ID of the language 347 * @param defaultLanguageId the ID of the default language 348 * @return the updated localizations XML 349 */ 350 public String updateLocalization( 351 String xml, String key, String value, String requestedLanguageId, 352 String defaultLanguageId); 353 354 /** 355 * Updates the localized string for the language in the localizations XML 356 * and changes the default language, optionally storing the localized 357 * strings as CDATA in the XML. 358 * 359 * @param xml the localizations XML 360 * @param key the name of the localized string, such as "Title" 361 * @param value the localized string 362 * @param requestedLanguageId the ID of the language 363 * @param defaultLanguageId the ID of the default language 364 * @param cdata whether to store localized strings as CDATA in the XML 365 * @return the updated localizations XML 366 */ 367 public String updateLocalization( 368 String xml, String key, String value, String requestedLanguageId, 369 String defaultLanguageId, boolean cdata); 370 371 /** 372 * Updates the localized string for the language in the localizations XML 373 * and changes the default language, optionally storing the localized 374 * strings as CDATA in the XML. 375 * 376 * @param xml the localizations XML 377 * @param key the name of the localized string, such as "Title" 378 * @param value the localized string 379 * @param requestedLanguageId the ID of the language 380 * @param defaultLanguageId the ID of the default language 381 * @param cdata whether to store localized strings as CDATA in the XML 382 * @param localized whether there is a localized field 383 * @return the updated localizations XML 384 */ 385 public String updateLocalization( 386 String xml, String key, String value, String requestedLanguageId, 387 String defaultLanguageId, boolean cdata, boolean localized); 388 389 }