001 /** 002 * Copyright (c) 2000-2013 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 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 public String getDefaultLanguageId(Document document, Locale defaultLocale); 085 086 /** 087 * Returns the default locale from the localizations XML. 088 * 089 * @param xml the localizations XML 090 * @return the language ID of the default locale, or the system default 091 * locale if the default locale cannot be retrieved from the XML 092 */ 093 public String getDefaultLanguageId(String xml); 094 095 public String getDefaultLanguageId(String xml, Locale defaultLocale); 096 097 /** 098 * Returns the localized string from the localizations XML in the language. 099 * Uses the default language if no localization exists for the requested 100 * language. 101 * 102 * @param xml the localizations XML 103 * @param requestedLanguageId the ID of the language 104 * @return the localized string 105 */ 106 public String getLocalization(String xml, String requestedLanguageId); 107 108 /** 109 * Returns the localized string from the localizations XML in the language, 110 * optionally using the default language if the no localization exists for 111 * the requested language. 112 * 113 * @param xml the localizations XML 114 * @param requestedLanguageId the ID of the language 115 * @param useDefault whether to use the default language if no localization 116 * exists for the requested language 117 * @return the localized string. If <code>useDefault</code> is 118 * <code>false</code> and no localization exists for the requested 119 * language, an empty string will be returned. 120 */ 121 public String getLocalization( 122 String xml, String requestedLanguageId, boolean useDefault); 123 124 /** 125 * Returns a map of locales and localized strings for the parameter in the 126 * request. 127 * 128 * @param request the request 129 * @param parameter the prefix of the parameters containing the localized 130 * strings. Each localization will be loaded from a parameter with 131 * this prefix, followed by an underscore, and the language ID. 132 * @return the locales and localized strings 133 */ 134 public Map<Locale, String> getLocalizationMap( 135 HttpServletRequest request, String parameter); 136 137 /** 138 * Returns a map of locales and localized strings for the parameter in the 139 * preferences container. 140 * 141 * @param preferences the preferences container 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 Map<Locale, String> getLocalizationMap( 148 PortletPreferences preferences, String parameter); 149 150 /** 151 * Returns a map of locales and localized strings for the parameter in the 152 * portlet request. 153 * 154 * @param portletRequest the portlet request 155 * @param parameter the prefix of the parameters containing the localized 156 * strings. Each localization will be loaded from a parameter with 157 * this prefix, followed by an underscore, and the language ID. 158 * @return the locales and localized strings 159 */ 160 public Map<Locale, String> getLocalizationMap( 161 PortletRequest portletRequest, String parameter); 162 163 /** 164 * Returns a map of locales and localized strings from the localizations 165 * XML. 166 * 167 * @param xml the localizations XML 168 * @return the locales and localized strings 169 */ 170 public Map<Locale, String> getLocalizationMap(String xml); 171 172 public Map<Locale, String> getLocalizationMap( 173 String xml, boolean useDefault); 174 175 public Map<Locale, String> getLocalizationMap( 176 String bundleName, ClassLoader classLoader, String key, 177 boolean includeBetaLocales); 178 179 /** 180 * Returns a map of locales and localized strings for the given languageIds 181 * and values. 182 * 183 * @param languageIds the languageIds of the localized Strings 184 * @param values the localized strings for the different languageId 185 * @return the map of locales and values for the given parameters 186 */ 187 public Map<Locale, String> getLocalizationMap( 188 String[] languageIds, String[] values); 189 190 /** 191 * Returns the localizations XML for the parameter in the portlet request, 192 * attempting to get data from the preferences container when it is not 193 * available in the portlet request. 194 * 195 * @param preferences the preferences container 196 * @param portletRequest the portlet request 197 * @param parameter the prefix of the parameters containing the localized 198 * strings. Each localization will be loaded from a parameter with 199 * this prefix, followed by an underscore, and the language ID. 200 * @return the locales and localized strings 201 */ 202 public String getLocalizationXmlFromPreferences( 203 PortletPreferences preferences, PortletRequest portletRequest, 204 String parameter); 205 206 public String getLocalizationXmlFromPreferences( 207 PortletPreferences preferences, PortletRequest portletRequest, 208 String parameter, String defaultValue); 209 210 /** 211 * @deprecated As of 6.2.0, replaced by {@link 212 * #getLocalizationMap(PortletRequest, String)} 213 */ 214 public Map<Locale, String> getLocalizedParameter( 215 PortletRequest portletRequest, String parameter); 216 217 /** 218 * Returns the localized preferences key in the language. Generally this is 219 * just the preferences key, followed by an underscore, and the language ID. 220 * 221 * @param key the preferences key 222 * @param languageId the ID of the language 223 * @return the localized preferences key 224 */ 225 public String getPreferencesKey(String key, String languageId); 226 227 /** 228 * Returns the localized preferences value for the key in the language. Uses 229 * the default language if no localization exists for the requested 230 * language. 231 * 232 * @param preferences the preferences container 233 * @param key the preferences key 234 * @param languageId the ID of the language 235 * @return the localized preferences value 236 */ 237 public String getPreferencesValue( 238 PortletPreferences preferences, String key, String languageId); 239 240 /** 241 * Returns the localized preferences value for the key in the language, 242 * optionally using the default language if the no localization exists for 243 * the requested language. 244 * 245 * @param preferences the preferences container 246 * @param key the preferences key 247 * @param languageId the ID of the language 248 * @param useDefault whether to use the default language if no localization 249 * exists for the requested language 250 * @return the localized preferences value. If <code>useDefault</code> is 251 * <code>false</code> and no localization exists for the requested 252 * language, an empty string will be returned. 253 */ 254 public String getPreferencesValue( 255 PortletPreferences preferences, String key, String languageId, 256 boolean useDefault); 257 258 /** 259 * Returns the localized preferences values for the key in the language. 260 * Uses the default language if no localization exists for the requested 261 * language. 262 * 263 * @param preferences the preferences container 264 * @param key the preferences key 265 * @param languageId the ID of the language 266 * @return the localized preferences values 267 */ 268 public String[] getPreferencesValues( 269 PortletPreferences preferences, String key, String languageId); 270 271 /** 272 * Returns the localized preferences values for the key in the language, 273 * optionally using the default language if the no localization exists for 274 * the requested language. 275 * 276 * @param preferences the preferences container 277 * @param key the preferences key 278 * @param languageId the ID of the language 279 * @param useDefault whether to use the default language if no localization 280 * exists for the requested language 281 * @return the localized preferences values. If <code>useDefault</code> is 282 * <code>false</code> and no localization exists for the requested 283 * language, an empty array will be returned. 284 */ 285 public String[] getPreferencesValues( 286 PortletPreferences preferences, String key, String languageId, 287 boolean useDefault); 288 289 /** 290 * Removes the localization for the language from the localizations XML. 291 * Stores the localized strings as characters in the XML. 292 * 293 * @param xml the localizations XML 294 * @param key the name of the localized string, such as "Title" 295 * @param requestedLanguageId the ID of the language 296 * @return the localizations XML with the language removed 297 */ 298 public String removeLocalization( 299 String xml, String key, String requestedLanguageId); 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 * @return the localizations XML with the language removed 310 */ 311 public String removeLocalization( 312 String xml, String key, String requestedLanguageId, boolean cdata); 313 314 /** 315 * Removes the localization for the language from the localizations XML, 316 * optionally storing the localized strings as CDATA in the XML. 317 * 318 * @param xml the localizations XML 319 * @param key the name of the localized string, such as "Title" 320 * @param requestedLanguageId the ID of the language 321 * @param cdata whether to store localized strings as CDATA in the XML 322 * @param localized whether there is a localized field 323 * @return the localizations XML with the language removed 324 */ 325 public String removeLocalization( 326 String xml, String key, String requestedLanguageId, boolean cdata, 327 boolean localized); 328 329 /** 330 * Sets the localized preferences values for the parameter in the portlet 331 * request. 332 * 333 * @param portletRequest the portlet request 334 * @param preferences the preferences container 335 * @param parameter the prefix of the parameters containing the localized 336 * strings. Each localization will be loaded from a parameter with 337 * this prefix, followed by an underscore, and the language ID. 338 * @throws Exception if an exception occurred 339 */ 340 public void setLocalizedPreferencesValues( 341 PortletRequest portletRequest, PortletPreferences preferences, 342 String parameter) 343 throws Exception; 344 345 /** 346 * Sets the localized preferences value for the key in the language. 347 * 348 * @param preferences the preferences container 349 * @param key the preferences key 350 * @param languageId the ID of the language 351 * @param value the localized value 352 * @throws Exception if an exception occurred 353 */ 354 public void setPreferencesValue( 355 PortletPreferences preferences, String key, String languageId, 356 String value) 357 throws Exception; 358 359 /** 360 * Sets the localized preferences values for the key in the language. 361 * 362 * @param preferences the preferences container 363 * @param key the preferences key 364 * @param languageId the ID of the language 365 * @param values the localized values 366 * @throws Exception if an exception occurred 367 */ 368 public void setPreferencesValues( 369 PortletPreferences preferences, String key, String languageId, 370 String[] values) 371 throws Exception; 372 373 /** 374 * Updates the localized string for all the available languages in the 375 * localizations XML for the map of locales and localized strings and 376 * changes the default language. Stores the localized strings as characters 377 * in the XML. 378 * 379 * @param localizationMap the locales and localized strings 380 * @param xml the localizations XML 381 * @param key the name of the localized string, such as "Title" 382 * @param defaultLanguageId the ID of the default language 383 * @return the updated localizations XML 384 */ 385 public String updateLocalization( 386 Map<Locale, String> localizationMap, String xml, String key, 387 String defaultLanguageId); 388 389 /** 390 * Updates the localized string for the system default language in the 391 * localizations XML. Stores the localized strings as characters in the XML. 392 * 393 * @param xml the localizations XML 394 * @param key the name of the localized string, such as "Title" 395 * @param value the localized string 396 * @return the updated localizations XML 397 */ 398 public String updateLocalization(String xml, String key, String value); 399 400 /** 401 * Updates the localized string for the language in the localizations XML. 402 * Stores the localized strings as characters in the XML. 403 * 404 * @param xml the localizations XML 405 * @param key the name of the localized string, such as "Title" 406 * @param value the localized string 407 * @param requestedLanguageId the ID of the language 408 * @return the updated localizations XML 409 */ 410 public String updateLocalization( 411 String xml, String key, String value, String requestedLanguageId); 412 413 /** 414 * Updates the localized string for the language in the localizations XML 415 * and changes the default language. Stores the localized strings as 416 * characters in the XML. 417 * 418 * @param xml the localizations XML 419 * @param key the name of the localized string, such as "Title" 420 * @param value the localized string 421 * @param requestedLanguageId the ID of the language 422 * @param defaultLanguageId the ID of the default language 423 * @return the updated localizations XML 424 */ 425 public String updateLocalization( 426 String xml, String key, String value, String requestedLanguageId, 427 String defaultLanguageId); 428 429 /** 430 * Updates the localized string for the language in the localizations XML 431 * and changes the default language, optionally storing the localized 432 * strings as CDATA in the XML. 433 * 434 * @param xml the localizations XML 435 * @param key the name of the localized string, such as "Title" 436 * @param value the localized string 437 * @param requestedLanguageId the ID of the language 438 * @param defaultLanguageId the ID of the default language 439 * @param cdata whether to store localized strings as CDATA in the XML 440 * @return the updated localizations XML 441 */ 442 public String updateLocalization( 443 String xml, String key, String value, String requestedLanguageId, 444 String defaultLanguageId, boolean cdata); 445 446 /** 447 * Updates the localized string for the language in the localizations XML 448 * and changes the default language, optionally storing the localized 449 * strings as CDATA in the XML. 450 * 451 * @param xml the localizations XML 452 * @param key the name of the localized string, such as "Title" 453 * @param value the localized string 454 * @param requestedLanguageId the ID of the language 455 * @param defaultLanguageId the ID of the default language 456 * @param cdata whether to store localized strings as CDATA in the XML 457 * @param localized whether there is a localized field 458 * @return the updated localizations XML 459 */ 460 public String updateLocalization( 461 String xml, String key, String value, String requestedLanguageId, 462 String defaultLanguageId, boolean cdata, boolean localized); 463 464 }