001 /** 002 * Copyright (c) 2000-present 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 import com.liferay.portal.kernel.settings.LocalizedValuesMap; 019 import com.liferay.portal.kernel.settings.Settings; 020 import com.liferay.portal.kernel.xml.Document; 021 022 import java.util.Locale; 023 import java.util.Map; 024 025 import javax.portlet.PortletPreferences; 026 import javax.portlet.PortletRequest; 027 028 import javax.servlet.http.HttpServletRequest; 029 030 /** 031 * Stores and retrieves localized strings from XML, and provides utility methods 032 * for updating localizations from JSON, portlet requests, and maps. Used for 033 * adding localization to strings, most often for model properties. 034 * 035 * <p> 036 * Localized values are cached in this class rather than in the value object 037 * since value objects get flushed from cache fairly quickly. Though lookups 038 * performed on a key based on an XML file are slower than lookups done at the 039 * value object level in general, the value object will get flushed at a rate 040 * which works against the performance gain. The cache is a soft hash map which 041 * prevents memory leaks within the system while enabling the cache to live 042 * longer than in a weak hash map. 043 * </p> 044 * 045 * @author Alexander Chow 046 * @author Jorge Ferrer 047 * @author Mauro Mariuzzo 048 * @author Julio Camarero 049 * @author Brian Wing Shun Chan 050 */ 051 public interface Localization { 052 053 /** 054 * Deserializes the JSON object into a map of locales and localized strings. 055 * 056 * @param jsonObject the JSON object 057 * @return the locales and localized strings 058 */ 059 public Object deserialize(JSONObject jsonObject); 060 061 public String[] getAvailableLanguageIds(Document document); 062 063 /** 064 * Returns the available locales from the localizations XML. 065 * 066 * @param xml the localizations XML 067 * @return the language IDs of the available locales 068 */ 069 public String[] getAvailableLanguageIds(String xml); 070 071 /** 072 * Returns a valid default locale for importing a localized entity. 073 * 074 * @param className the class name of the entity 075 * @param classPK the primary keys of the entity 076 * @param contentDefaultLocale the default Locale of the entity 077 * @param contentAvailableLocales the available locales of the entity 078 * @return the valid locale 079 */ 080 public Locale getDefaultImportLocale( 081 String className, long classPK, Locale contentDefaultLocale, 082 Locale[] contentAvailableLocales); 083 084 public String getDefaultLanguageId(Document document); 085 086 public String getDefaultLanguageId(Document document, Locale defaultLocale); 087 088 /** 089 * Returns the default locale from the localizations XML. 090 * 091 * @param xml the localizations XML 092 * @return the language ID of the default locale, or the system default 093 * locale if the default locale cannot be retrieved from the XML 094 */ 095 public String getDefaultLanguageId(String xml); 096 097 public String getDefaultLanguageId(String xml, Locale defaultLocale); 098 099 /** 100 * Returns the localized string from the localizations XML in the language. 101 * The default language is used if no localization exists for the requested 102 * language. 103 * 104 * @param xml the localizations XML 105 * @param requestedLanguageId the ID of the language 106 * @return the localized string 107 */ 108 public String getLocalization(String xml, String requestedLanguageId); 109 110 /** 111 * Returns the localized string from the localizations XML in the language, 112 * optionally using the default language if no localization exists for the 113 * requested language. 114 * 115 * @param xml the localizations XML 116 * @param requestedLanguageId the ID of the language 117 * @param useDefault whether to use the default language if no localization 118 * exists for the requested language 119 * @return the localized string, or an empty string if 120 * <code>useDefault</code> is <code>false</code> and no localization 121 * exists for the requested language 122 */ 123 public String getLocalization( 124 String xml, String requestedLanguageId, boolean useDefault); 125 126 /** 127 * Returns the localized string from the localizations XML in the language, 128 * optionally using the default language if no localization exists for the 129 * requested language. If no localization exists, the default value is 130 * returned. 131 * 132 * @param xml the localizations XML 133 * @param requestedLanguageId the ID of the language 134 * @param useDefault whether to use the default language if no localization 135 * exists for the requested language 136 * @param defaultValue the value returned if no localization exists 137 * @return the localized string, or the <code>defaultValue</code> if 138 * <code>useDefault</code> is <code>false</code> and no localization 139 * exists for the requested language 140 */ 141 public String getLocalization( 142 String xml, String requestedLanguageId, boolean useDefault, 143 String defaultValue); 144 145 /** 146 * Returns a map of locales and localized strings for the parameter in the 147 * request. 148 * 149 * @param request the request 150 * @param parameter the prefix of the parameters containing the localized 151 * strings. Each localization is loaded from a parameter with this 152 * prefix, followed by an underscore, and the language ID. 153 * @return the locales and localized strings 154 */ 155 public Map<Locale, String> getLocalizationMap( 156 HttpServletRequest request, String parameter); 157 158 /** 159 * Returns a map of locales and localized strings for the preference in the 160 * preferences container. 161 * 162 * @param preferences the preferences container 163 * @param preferenceName the prefix of the preference containing the 164 * localized strings. Each localization is loaded from a preference 165 * with this prefix, followed by an underscore, and the language ID. 166 * @return the locales and localized strings 167 */ 168 public Map<Locale, String> getLocalizationMap( 169 PortletPreferences preferences, String preferenceName); 170 171 /** 172 * Returns a map of locales and localized strings for the preference in the 173 * preferences container. If no localization exists for the preference in 174 * the default locale, the value of the property is used as the localization 175 * for it. 176 * 177 * @param preferences the preferences container 178 * @param preferenceName the prefix of the preference containing the 179 * localized strings. Each localization is loaded from a preference 180 * with this prefix, followed by an underscore, and the language ID. 181 * @param propertyName the name of the property whose value is used as the 182 * localization for the default locale, if no localization exists 183 * for it 184 * @return the locales and localized strings 185 */ 186 public Map<Locale, String> getLocalizationMap( 187 PortletPreferences preferences, String preferenceName, 188 String propertyName); 189 190 public Map<Locale, String> getLocalizationMap( 191 PortletPreferences preferences, String preferenceName, 192 String propertyName, String defaultPropertyValue, 193 ClassLoader classLoader); 194 195 /** 196 * Returns a map of locales and localized strings for the parameter in the 197 * portlet request. 198 * 199 * @param portletRequest the portlet request 200 * @param parameter the prefix of the parameters containing the localized 201 * strings. Each localization is loaded from a parameter with this 202 * prefix, followed by an underscore, and the language ID. 203 * @return the locales and localized strings 204 */ 205 public Map<Locale, String> getLocalizationMap( 206 PortletRequest portletRequest, String parameter); 207 208 public Map<Locale, String> getLocalizationMap( 209 PortletRequest portletRequest, String parameter, 210 Map<Locale, String> defaultValues); 211 212 /** 213 * Returns a map of locales and localized strings from the localizations 214 * XML. 215 * 216 * @param xml the localizations XML 217 * @return the locales and localized strings 218 */ 219 public Map<Locale, String> getLocalizationMap(String xml); 220 221 public Map<Locale, String> getLocalizationMap( 222 String xml, boolean useDefault); 223 224 public Map<Locale, String> getLocalizationMap( 225 String bundleName, ClassLoader classLoader, String key, 226 boolean includeBetaLocales); 227 228 /** 229 * Returns a map of locales and localized strings for the given languageIds 230 * and values. 231 * 232 * @param languageIds the languageIds of the localized Strings 233 * @param values the localized strings for the different languageId 234 * @return the map of locales and values for the given parameters 235 */ 236 public Map<Locale, String> getLocalizationMap( 237 String[] languageIds, String[] values); 238 239 /** 240 * Returns the localizations XML for the parameter from the portlet request, 241 * attempting to get data from the preferences container if it is not 242 * available in the portlet request. 243 * 244 * @param preferences the preferences container 245 * @param portletRequest the portlet request 246 * @param parameter the prefix of the parameters containing the localized 247 * strings. Each localization is loaded from a parameter with this 248 * prefix, followed by an underscore, and the language ID. 249 * @return the locales and localized strings 250 */ 251 public String getLocalizationXmlFromPreferences( 252 PortletPreferences preferences, PortletRequest portletRequest, 253 String parameter); 254 255 /** 256 * Returns the localizations XML for the parameter from the portlet request, 257 * attempting to get data from the preferences container if it is not 258 * available in the portlet request. If no localization exists in the 259 * default locale, the default value is used as the localization for it. 260 * 261 * @param preferences the preferences container 262 * @param portletRequest the portlet request 263 * @param parameter the prefix of the parameters containing the localized 264 * strings. Each localization is loaded from a parameter with this 265 * prefix, followed by an underscore, and the language ID. 266 * @param defaultValue the value used as the localization for the default 267 * locale, if no localization exists for it 268 * @return the locales and localized strings 269 */ 270 public String getLocalizationXmlFromPreferences( 271 PortletPreferences preferences, PortletRequest portletRequest, 272 String parameter, String defaultValue); 273 274 /** 275 * Returns the localizations XML for the prefixed parameter from the portlet 276 * request, attempting to get data from the preferences container if it is 277 * not available in the portlet request. If no localization exists for the 278 * the default locale, the default value is used as the localization for it. 279 * 280 * @param preferences the preferences container 281 * @param portletRequest the portlet request 282 * @param parameter the prefix of the parameters containing the localized 283 * strings. Each localization is loaded from a parameter with this 284 * prefix, followed by an underscore, and the language ID. 285 * @param prefix the value used in the request to prefix the parameter name 286 * @param defaultValue the value used as the localization for the default 287 * locale, if no localization exists for it 288 * @return the locales and localized strings, or the 289 * <code>defaultValue</code> if no localization exists 290 */ 291 public String getLocalizationXmlFromPreferences( 292 PortletPreferences preferences, PortletRequest portletRequest, 293 String parameter, String prefix, String defaultValue); 294 295 /** 296 * Returns the localized name in the language. The localized name is the 297 * name, followed by an underscore, and the language ID. 298 * 299 * @param name the name to be localized 300 * @param languageId the ID of the language 301 * @return the localized name for the language 302 */ 303 public String getLocalizedName(String name, String languageId); 304 305 /** 306 * @deprecated As of 6.2.0, replaced by {@link 307 * #getLocalizationMap(PortletRequest, String)} 308 */ 309 @Deprecated 310 public Map<Locale, String> getLocalizedParameter( 311 PortletRequest portletRequest, String parameter); 312 313 public Map<Locale, String> getMap(LocalizedValuesMap localizedValuesMap); 314 315 /** 316 * Returns the localized preferences key in the language. Generally this is 317 * just the preferences key, followed by an underscore, and the language ID. 318 * 319 * @param key the preferences key 320 * @param languageId the ID of the language 321 * @return the localized preferences key 322 * @deprecated As of 7.0.0, replaced by {@link #getLocalizedName(String, 323 * String)} 324 */ 325 @Deprecated 326 public String getPreferencesKey(String key, String languageId); 327 328 /** 329 * Returns the localized preferences value for the key in the language. The 330 * default language is used if no localization exists for the requested 331 * language. 332 * 333 * @param preferences the preferences container 334 * @param key the preferences key 335 * @param languageId the ID of the language 336 * @return the localized preferences value 337 */ 338 public String getPreferencesValue( 339 PortletPreferences preferences, String key, String languageId); 340 341 /** 342 * Returns the localized preferences value for the key in the language, 343 * optionally using the default language if no localization exists for the 344 * requested language. 345 * 346 * @param preferences the preferences container 347 * @param key the preferences key 348 * @param languageId the ID of the language 349 * @param useDefault whether to use the default language if no localization 350 * exists for the requested language 351 * @return the localized preferences value, or an empty string if 352 * <code>useDefault</code> is <code>false</code> and no localization 353 * exists for the requested language 354 */ 355 public String getPreferencesValue( 356 PortletPreferences preferences, String key, String languageId, 357 boolean useDefault); 358 359 /** 360 * Returns the localized preferences values for the key in the language. The 361 * default language is used if no localization exists for the requested 362 * language. 363 * 364 * @param preferences the preferences container 365 * @param key the preferences key 366 * @param languageId the ID of the language 367 * @return the localized preferences values 368 */ 369 public String[] getPreferencesValues( 370 PortletPreferences preferences, String key, String languageId); 371 372 /** 373 * Returns the localized preferences values for the key in the language, 374 * optionally using the default language if no localization exists for the 375 * requested language. 376 * 377 * @param preferences the preferences container 378 * @param key the preferences key 379 * @param languageId the ID of the language 380 * @param useDefault whether to use the default language if no localization 381 * exists for the requested language 382 * @return the localized preferences values, or an empty string if 383 * <code>useDefault</code> is <code>false</code> and no localization 384 * exists for the requested language 385 */ 386 public String[] getPreferencesValues( 387 PortletPreferences preferences, String key, String languageId, 388 boolean useDefault); 389 390 /** 391 * Returns the localized settings value for the key in the language. The 392 * default language is used if no localization exists for the requested 393 * language. 394 * 395 * @param settings the settings 396 * @param key the settings key 397 * @param languageId the ID of the language 398 * @return the localized settings value 399 */ 400 public String getSettingsValue( 401 Settings settings, String key, String languageId); 402 403 /** 404 * Returns the localized settings value for the key in the language, 405 * optionally using the default language if no localization exists for the 406 * requested language. 407 * 408 * @param settings the settings 409 * @param key the settings key 410 * @param languageId the ID of the language 411 * @param useDefault whether to use the default language if no localization 412 * exists for the requested language 413 * @return the localized settings value. If <code>useDefault</code> is 414 * <code>false</code> and no localization exists for the requested 415 * language, an empty string is returned. 416 */ 417 public String getSettingsValue( 418 Settings settings, String key, String languageId, boolean useDefault); 419 420 /** 421 * Returns the localized settings values for the key in the language. The 422 * default language is used if no localization exists for the requested 423 * language. 424 * 425 * @param settings the settings 426 * @param key the settings key 427 * @param languageId the ID of the language 428 * @return the localized settings values 429 */ 430 public String[] getSettingsValues( 431 Settings settings, String key, String languageId); 432 433 /** 434 * Returns the localized settings values for the key in the language, 435 * optionally using the default language if no localization exists for the 436 * requested language. 437 * 438 * @param settings the settings 439 * @param key the settings key 440 * @param languageId the ID of the language 441 * @param useDefault whether to use the default language if no localization 442 * exists for the requested language 443 * @return the localized settings values. If <code>useDefault</code> is 444 * <code>false</code> and no localization exists for the requested 445 * language, an empty array is returned. 446 */ 447 public String[] getSettingsValues( 448 Settings settings, String key, String languageId, boolean useDefault); 449 450 public String getXml(LocalizedValuesMap localizedValuesMap, String key); 451 452 /** 453 * Removes the localization for the language from the localizations XML. The 454 * localized strings are stored as characters in the XML. 455 * 456 * @param xml the localizations XML 457 * @param key the name of the localized string, such as "Title" 458 * @param requestedLanguageId the ID of the language 459 * @return the localizations XML with the language removed 460 */ 461 public String removeLocalization( 462 String xml, String key, String requestedLanguageId); 463 464 /** 465 * Removes the localization for the language from the localizations XML, 466 * optionally storing the localized strings as CDATA in the XML. 467 * 468 * @param xml the localizations XML 469 * @param key the name of the localized string, such as "Title" 470 * @param requestedLanguageId the ID of the language 471 * @param cdata whether to store localized strings as CDATA in the XML 472 * @return the localizations XML with the language removed 473 */ 474 public String removeLocalization( 475 String xml, String key, String requestedLanguageId, boolean cdata); 476 477 /** 478 * Removes the localization for the language from the localizations XML, 479 * optionally storing the localized strings as CDATA in the XML. 480 * 481 * @param xml the localizations XML 482 * @param key the name of the localized string, such as "Title" 483 * @param requestedLanguageId the ID of the language 484 * @param cdata whether to store localized strings as CDATA in the XML 485 * @param localized whether there is a localized field 486 * @return the localizations XML with the language removed 487 */ 488 public String removeLocalization( 489 String xml, String key, String requestedLanguageId, boolean cdata, 490 boolean localized); 491 492 /** 493 * Sets the localized preferences values for the parameter in the portlet 494 * request. 495 * 496 * @param portletRequest the portlet request 497 * @param preferences the preferences container 498 * @param parameter the prefix of the parameters containing the localized 499 * strings. Each localization is loaded from a parameter with this 500 * prefix, followed by an underscore, and the language ID. 501 * @throws Exception if an exception occurred 502 */ 503 public void setLocalizedPreferencesValues( 504 PortletRequest portletRequest, PortletPreferences preferences, 505 String parameter) 506 throws Exception; 507 508 /** 509 * Sets the localized preferences value for the key in the language. 510 * 511 * @param preferences the preferences container 512 * @param key the preferences key 513 * @param languageId the ID of the language 514 * @param value the localized value 515 * @throws Exception if an exception occurred 516 */ 517 public void setPreferencesValue( 518 PortletPreferences preferences, String key, String languageId, 519 String value) 520 throws Exception; 521 522 /** 523 * Sets the localized preferences values for the key in the language. 524 * 525 * @param preferences the preferences container 526 * @param key the preferences key 527 * @param languageId the ID of the language 528 * @param values the localized values 529 * @throws Exception if an exception occurred 530 */ 531 public void setPreferencesValues( 532 PortletPreferences preferences, String key, String languageId, 533 String[] values) 534 throws Exception; 535 536 /** 537 * Updates the localized string for all the available languages in the 538 * localizations XML for the map of locales and localized strings and 539 * changes the default language. The localized strings are stored as 540 * characters in the XML. 541 * 542 * @param localizationMap the locales and localized strings 543 * @param xml the localizations XML 544 * @param key the name of the localized string, such as "Title" 545 * @param defaultLanguageId the ID of the default language 546 * @return the updated localizations XML 547 */ 548 public String updateLocalization( 549 Map<Locale, String> localizationMap, String xml, String key, 550 String defaultLanguageId); 551 552 /** 553 * Updates the localized string for the system default language in the 554 * localizations XML. The localized strings are stored as characters in the 555 * XML. 556 * 557 * @param xml the localizations XML 558 * @param key the name of the localized string, such as "Title" 559 * @param value the localized string 560 * @return the updated localizations XML 561 */ 562 public String updateLocalization(String xml, String key, String value); 563 564 /** 565 * Updates the localized string for the language in the localizations XML. 566 * The localized strings are stored as characters in the XML. 567 * 568 * @param xml the localizations XML 569 * @param key the name of the localized string, such as "Title" 570 * @param value the localized string 571 * @param requestedLanguageId the ID of the language 572 * @return the updated localizations XML 573 */ 574 public String updateLocalization( 575 String xml, String key, String value, String requestedLanguageId); 576 577 /** 578 * Updates the localized string for the language in the localizations XML 579 * and changes the default language. The localized strings are stored as 580 * characters in the XML. 581 * 582 * @param xml the localizations XML 583 * @param key the name of the localized string, such as "Title" 584 * @param value the localized string 585 * @param requestedLanguageId the ID of the language 586 * @param defaultLanguageId the ID of the default language 587 * @return the updated localizations XML 588 */ 589 public String updateLocalization( 590 String xml, String key, String value, String requestedLanguageId, 591 String defaultLanguageId); 592 593 /** 594 * Updates the localized string for the language in the localizations XML 595 * and changes the default language, optionally storing the localized 596 * strings as CDATA in the XML. 597 * 598 * @param xml the localizations XML 599 * @param key the name of the localized string, such as "Title" 600 * @param value the localized string 601 * @param requestedLanguageId the ID of the language 602 * @param defaultLanguageId the ID of the default language 603 * @param cdata whether to store localized strings as CDATA in the XML 604 * @return the updated localizations XML 605 */ 606 public String updateLocalization( 607 String xml, String key, String value, String requestedLanguageId, 608 String defaultLanguageId, boolean cdata); 609 610 /** 611 * Updates the localized string for the language in the localizations XML 612 * and changes the default language, optionally storing the localized 613 * strings as CDATA in the XML. 614 * 615 * @param xml the localizations XML 616 * @param key the name of the localized string, such as "Title" 617 * @param value the localized string 618 * @param requestedLanguageId the ID of the language 619 * @param defaultLanguageId the ID of the default language 620 * @param cdata whether to store localized strings as CDATA in the XML 621 * @param localized whether there is a localized field 622 * @return the updated localizations XML 623 */ 624 public String updateLocalization( 625 String xml, String key, String value, String requestedLanguageId, 626 String defaultLanguageId, boolean cdata, boolean localized); 627 628 }