001 /** 002 * Copyright (c) 2000-2013 Liferay, Inc. All rights reserved. 003 * 004 * This library is free software; you can redistribute it and/or modify it under 005 * the terms of the GNU Lesser General Public License as published by the Free 006 * Software Foundation; either version 2.1 of the License, or (at your option) 007 * any later version. 008 * 009 * This library is distributed in the hope that it will be useful, but WITHOUT 010 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 011 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 012 * details. 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 import javax.servlet.http.HttpServletRequest; 026 027 /** 028 * Stores and retrieves localized strings from XML, and provides utility methods 029 * for updating localizations from JSON, portlet requests, and maps. Used for 030 * adding localization to strings, most often for model properties. 031 * 032 * <p> 033 * Localized values are cached in this class rather than in the value object 034 * since value objects get flushed from cache fairly quickly. Though lookups 035 * performed on a key based on an XML file are slower than lookups done at the 036 * value object level in general, the value object will get flushed at a rate 037 * which works against the performance gain. The cache is a soft hash map which 038 * prevents memory leaks within the system while enabling the cache to live 039 * longer than in a weak hash map. 040 * </p> 041 * 042 * @author Alexander Chow 043 * @author Jorge Ferrer 044 * @author Mauro Mariuzzo 045 * @author Julio Camarero 046 * @author Brian Wing Shun Chan 047 */ 048 public interface Localization { 049 050 /** 051 * Deserializes the JSON object into a map of locales and localized strings. 052 * 053 * @param jsonObject the JSON object 054 * @return the locales and localized strings 055 */ 056 public Object deserialize(JSONObject jsonObject); 057 058 /** 059 * Returns the available locales from the localizations XML. 060 * 061 * @param xml the localizations XML 062 * @return the language IDs of the available locales 063 */ 064 public String[] getAvailableLocales(String xml); 065 066 /** 067 * Returns a valid default locale for importing a localized entity. 068 * 069 * @param className the class name of the entity 070 * @param classPK the primary keys of the entity 071 * @param contentDefaultLocale the default Locale of the entity 072 * @param contentAvailableLocales the available locales of the entity 073 * @return the valid locale 074 */ 075 public Locale getDefaultImportLocale( 076 String className, long classPK, Locale contentDefaultLocale, 077 Locale[] contentAvailableLocales); 078 079 /** 080 * Returns the default locale from the localizations XML. 081 * 082 * @param xml the localizations XML 083 * @return the language ID of the default locale, or the system default 084 * locale if the default locale cannot be retrieved from the XML 085 */ 086 public String getDefaultLocale(String xml); 087 088 /** 089 * Returns the localized string from the localizations XML in the language. 090 * Uses the default language if no localization exists for the requested 091 * language. 092 * 093 * @param xml the localizations XML 094 * @param requestedLanguageId the ID of the language 095 * @return the localized string 096 */ 097 public String getLocalization(String xml, String requestedLanguageId); 098 099 /** 100 * Returns the localized string from the localizations XML in the language, 101 * optionally using the default language if the no localization exists for 102 * the requested language. 103 * 104 * @param xml the localizations XML 105 * @param requestedLanguageId the ID of the language 106 * @param useDefault whether to use the default language if no localization 107 * exists for the requested language 108 * @return the localized string. If <code>useDefault</code> is 109 * <code>false</code> and no localization exists for the requested 110 * language, an empty string will be returned. 111 */ 112 public String getLocalization( 113 String xml, String requestedLanguageId, boolean useDefault); 114 115 /** 116 * Returns a map of locales and localized strings for the parameter in the 117 * request. 118 * 119 * @param request the request 120 * @param parameter the prefix of the parameters containing the localized 121 * strings. Each localization will be loaded from a parameter with 122 * this prefix, followed by an underscore, and the language ID. 123 * @return the locales and localized strings 124 */ 125 public Map<Locale, String> getLocalizationMap( 126 HttpServletRequest request, String parameter); 127 128 /** 129 * Returns a map of locales and localized strings for the parameter in the 130 * preferences container. 131 * 132 * @param preferences the preferences container 133 * @param parameter the prefix of the parameters containing the localized 134 * strings. Each localization will be loaded from a parameter with 135 * this prefix, followed by an underscore, and the language ID. 136 * @return the locales and localized strings 137 */ 138 public Map<Locale, String> getLocalizationMap( 139 PortletPreferences preferences, String parameter); 140 141 /** 142 * Returns a map of locales and localized strings for the parameter in the 143 * portlet request. 144 * 145 * @param portletRequest the portlet request 146 * @param parameter the prefix of the parameters containing the localized 147 * strings. Each localization will be loaded from a parameter with 148 * this prefix, followed by an underscore, and the language ID. 149 * @return the locales and localized strings 150 */ 151 public Map<Locale, String> getLocalizationMap( 152 PortletRequest portletRequest, String parameter); 153 154 /** 155 * Returns a map of locales and localized strings from the localizations 156 * XML. 157 * 158 * @param xml the localizations XML 159 * @return the locales and localized strings 160 */ 161 public Map<Locale, String> getLocalizationMap(String xml); 162 163 public Map<Locale, String> getLocalizationMap( 164 String xml, boolean useDefault); 165 166 public Map<Locale, String> getLocalizationMap( 167 String bundleName, ClassLoader classLoader, String key, 168 boolean includeBetaLocales); 169 170 /** 171 * Returns a map of locales and localized strings for the given languageIds 172 * and values. 173 * 174 * @param languageIds the languageIds of the localized Strings 175 * @param values the localized strings for the different languageId 176 * @return the map of locales and values for the given parameters 177 */ 178 public Map<Locale, String> getLocalizationMap( 179 String[] languageIds, String[] values); 180 181 /** 182 * Returns the localizations XML for the parameter in the portlet request, 183 * attempting to get data from the preferences container when it is not 184 * available in the portlet request. 185 * 186 * @param preferences the preferences container 187 * @param portletRequest the portlet request 188 * @param parameter the prefix of the parameters containing the localized 189 * strings. Each localization will be loaded from a parameter with 190 * this prefix, followed by an underscore, and the language ID. 191 * @return the locales and localized strings 192 */ 193 public String getLocalizationXmlFromPreferences( 194 PortletPreferences preferences, PortletRequest portletRequest, 195 String parameter); 196 197 /** 198 * @deprecated As of 6.2.0, replaced by {@link 199 * #getLocalizationMap(PortletRequest, String)} 200 */ 201 public Map<Locale, String> getLocalizedParameter( 202 PortletRequest portletRequest, String parameter); 203 204 /** 205 * Returns the localized preferences key in the language. Generally this is 206 * just the preferences key, followed by an underscore, and the language ID. 207 * 208 * @param key the preferences key 209 * @param languageId the ID of the language 210 * @return the localized preferences key 211 */ 212 public String getPreferencesKey(String key, String languageId); 213 214 /** 215 * Returns the localized preferences value for the key in the language. Uses 216 * the default language if no localization exists for the requested 217 * language. 218 * 219 * @param preferences the preferences container 220 * @param key the preferences key 221 * @param languageId the ID of the language 222 * @return the localized preferences value 223 */ 224 public String getPreferencesValue( 225 PortletPreferences preferences, String key, String languageId); 226 227 /** 228 * Returns the localized preferences value for the key in the language, 229 * optionally using the default language if the no localization exists for 230 * the requested language. 231 * 232 * @param preferences the preferences container 233 * @param key the preferences key 234 * @param languageId the ID of the language 235 * @param useDefault whether to use the default language if no localization 236 * exists for the requested language 237 * @return the localized preferences value. If <code>useDefault</code> is 238 * <code>false</code> and no localization exists for the requested 239 * language, an empty string will be returned. 240 */ 241 public String getPreferencesValue( 242 PortletPreferences preferences, String key, String languageId, 243 boolean useDefault); 244 245 /** 246 * Returns the localized preferences values for the key in the language. 247 * Uses the default language if no localization exists for the requested 248 * language. 249 * 250 * @param preferences the preferences container 251 * @param key the preferences key 252 * @param languageId the ID of the language 253 * @return the localized preferences values 254 */ 255 public String[] getPreferencesValues( 256 PortletPreferences preferences, String key, String languageId); 257 258 /** 259 * Returns the localized preferences values for the key in the language, 260 * optionally using the default language if the no localization exists for 261 * the requested language. 262 * 263 * @param preferences the preferences container 264 * @param key the preferences key 265 * @param languageId the ID of the language 266 * @param useDefault whether to use the default language if no localization 267 * exists for the requested language 268 * @return the localized preferences values. If <code>useDefault</code> is 269 * <code>false</code> and no localization exists for the requested 270 * language, an empty array will be returned. 271 */ 272 public String[] getPreferencesValues( 273 PortletPreferences preferences, String key, String languageId, 274 boolean useDefault); 275 276 /** 277 * Removes the localization for the language from the localizations XML. 278 * Stores the localized strings as characters in the XML. 279 * 280 * @param xml the localizations XML 281 * @param key the name of the localized string, such as "Title" 282 * @param requestedLanguageId the ID of the language 283 * @return the localizations XML with the language removed 284 */ 285 public String removeLocalization( 286 String xml, String key, String requestedLanguageId); 287 288 /** 289 * Removes the localization for the language from the localizations XML, 290 * optionally storing the localized strings as CDATA in the XML. 291 * 292 * @param xml the localizations XML 293 * @param key the name of the localized string, such as "Title" 294 * @param requestedLanguageId the ID of the language 295 * @param cdata whether to store localized strings as CDATA in the XML 296 * @return the localizations XML with the language removed 297 */ 298 public String removeLocalization( 299 String xml, String key, String requestedLanguageId, boolean cdata); 300 301 /** 302 * Removes the localization for the language from the localizations XML, 303 * optionally storing the localized strings as CDATA in the XML. 304 * 305 * @param xml the localizations XML 306 * @param key the name of the localized string, such as "Title" 307 * @param requestedLanguageId the ID of the language 308 * @param cdata whether to store localized strings as CDATA in the XML 309 * @param localized whether there is a localized field 310 * @return the localizations XML with the language removed 311 */ 312 public String removeLocalization( 313 String xml, String key, String requestedLanguageId, boolean cdata, 314 boolean localized); 315 316 /** 317 * Sets the localized preferences values for the parameter in the portlet 318 * request. 319 * 320 * @param portletRequest the portlet request 321 * @param preferences the preferences container 322 * @param parameter the prefix of the parameters containing the localized 323 * strings. Each localization will be loaded from a parameter with 324 * this prefix, followed by an underscore, and the language ID. 325 * @throws Exception if an exception occurred 326 */ 327 public void setLocalizedPreferencesValues( 328 PortletRequest portletRequest, PortletPreferences preferences, 329 String parameter) 330 throws Exception; 331 332 /** 333 * Sets the localized preferences value for the key in the language. 334 * 335 * @param preferences the preferences container 336 * @param key the preferences key 337 * @param languageId the ID of the language 338 * @param value the localized value 339 * @throws Exception if an exception occurred 340 */ 341 public void setPreferencesValue( 342 PortletPreferences preferences, String key, String languageId, 343 String value) 344 throws Exception; 345 346 /** 347 * Sets the localized preferences values for the key in the language. 348 * 349 * @param preferences the preferences container 350 * @param key the preferences key 351 * @param languageId the ID of the language 352 * @param values the localized values 353 * @throws Exception if an exception occurred 354 */ 355 public void setPreferencesValues( 356 PortletPreferences preferences, String key, String languageId, 357 String[] values) 358 throws Exception; 359 360 /** 361 * Updates the localized string for all the available languages in the 362 * localizations XML for the map of locales and localized strings and 363 * changes the default language. Stores the localized strings as characters 364 * in the XML. 365 * 366 * @param localizationMap the locales and localized strings 367 * @param xml the localizations XML 368 * @param key the name of the localized string, such as "Title" 369 * @param defaultLanguageId the ID of the default language 370 * @return the updated localizations XML 371 */ 372 public String updateLocalization( 373 Map<Locale, String> localizationMap, String xml, String key, 374 String defaultLanguageId); 375 376 /** 377 * Updates the localized string for the system default language in the 378 * localizations XML. Stores the localized strings as characters in the XML. 379 * 380 * @param xml the localizations XML 381 * @param key the name of the localized string, such as "Title" 382 * @param value the localized string 383 * @return the updated localizations XML 384 */ 385 public String updateLocalization(String xml, String key, String value); 386 387 /** 388 * Updates the localized string for the language in the localizations XML. 389 * Stores the localized strings as characters in the XML. 390 * 391 * @param xml the localizations XML 392 * @param key the name of the localized string, such as "Title" 393 * @param value the localized string 394 * @param requestedLanguageId the ID of the language 395 * @return the updated localizations XML 396 */ 397 public String updateLocalization( 398 String xml, String key, String value, String requestedLanguageId); 399 400 /** 401 * Updates the localized string for the language in the localizations XML 402 * and changes the default language. Stores the localized strings as 403 * characters in the XML. 404 * 405 * @param xml the localizations XML 406 * @param key the name of the localized string, such as "Title" 407 * @param value the localized string 408 * @param requestedLanguageId the ID of the language 409 * @param defaultLanguageId the ID of the default language 410 * @return the updated localizations XML 411 */ 412 public String updateLocalization( 413 String xml, String key, String value, String requestedLanguageId, 414 String defaultLanguageId); 415 416 /** 417 * Updates the localized string for the language in the localizations XML 418 * and changes the default language, optionally storing the localized 419 * strings as CDATA in the XML. 420 * 421 * @param xml the localizations XML 422 * @param key the name of the localized string, such as "Title" 423 * @param value the localized string 424 * @param requestedLanguageId the ID of the language 425 * @param defaultLanguageId the ID of the default language 426 * @param cdata whether to store localized strings as CDATA in the XML 427 * @return the updated localizations XML 428 */ 429 public String updateLocalization( 430 String xml, String key, String value, String requestedLanguageId, 431 String defaultLanguageId, boolean cdata); 432 433 /** 434 * Updates the localized string for the language in the localizations XML 435 * and changes the default language, optionally storing the localized 436 * strings as CDATA in the XML. 437 * 438 * @param xml the localizations XML 439 * @param key the name of the localized string, such as "Title" 440 * @param value the localized string 441 * @param requestedLanguageId the ID of the language 442 * @param defaultLanguageId the ID of the default language 443 * @param cdata whether to store localized strings as CDATA in the XML 444 * @param localized whether there is a localized field 445 * @return the updated localizations XML 446 */ 447 public String updateLocalization( 448 String xml, String key, String value, String requestedLanguageId, 449 String defaultLanguageId, boolean cdata, boolean localized); 450 451 }