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