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 /** 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 a valid default locale for importing a localized entity. 066 * 067 * @param className the class name of the entity 068 * @param classPK the primary keys of the entity 069 * @param contentDefaultLocale the default Locale of the entity 070 * @param contentAvailableLocales the available locales of the entity 071 * @return the valid locale 072 */ 073 public Locale getDefaultImportLocale( 074 String className, long classPK, Locale contentDefaultLocale, 075 Locale[] contentAvailableLocales); 076 077 /** 078 * Returns the default locale from the localizations XML. 079 * 080 * @param xml the localizations XML 081 * @return the language ID of the default locale, or the system default 082 * locale if the default locale cannot be retrieved from the XML 083 */ 084 public String getDefaultLocale(String xml); 085 086 /** 087 * Returns the localized string from the localizations XML in the language. 088 * Uses the default language if no localization exists for the requested 089 * language. 090 * 091 * @param xml the localizations XML 092 * @param requestedLanguageId the ID of the language 093 * @return the localized string 094 */ 095 public String getLocalization(String xml, String requestedLanguageId); 096 097 /** 098 * Returns the localized string from the localizations XML in the language, 099 * optionally using the default language if the no localization exists for 100 * the requested language. 101 * 102 * @param xml the localizations XML 103 * @param requestedLanguageId the ID of the language 104 * @param useDefault whether to use the default language if no localization 105 * exists for the requested language 106 * @return the localized string. If <code>useDefault</code> is 107 * <code>false</code> and no localization exists for the requested 108 * language, an empty string will be returned. 109 */ 110 public String getLocalization( 111 String xml, String requestedLanguageId, boolean useDefault); 112 113 /** 114 * Returns a map of locales and localized strings for the parameter in the 115 * preferences container. 116 * 117 * @param preferences the preferences container 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 PortletPreferences preferences, String parameter); 125 126 /** 127 * Returns a map of locales and localized strings for the parameter in the 128 * portlet request. 129 * 130 * @param portletRequest the portlet request 131 * @param parameter the prefix of the parameters containing the localized 132 * strings. Each localization will be loaded from a parameter with 133 * this prefix, followed by an underscore, and the language ID. 134 * @return the locales and localized strings 135 */ 136 public Map<Locale, String> getLocalizationMap( 137 PortletRequest portletRequest, String parameter); 138 139 /** 140 * Returns a map of locales and localized strings from the localizations 141 * XML. 142 * 143 * @param xml the localizations XML 144 * @return the locales and localized strings 145 */ 146 public Map<Locale, String> getLocalizationMap(String xml); 147 148 public Map<Locale, String> getLocalizationMap( 149 String bundleName, ClassLoader classLoader, String key, 150 boolean includeBetaLocales); 151 152 /** 153 * Returns a map of locales and localized strings for the given languageIds 154 * and values. 155 * 156 * @param languageIds the languageIds of the localized Strings 157 * @param values the localized strings for the different languageId 158 * @return the map of locales and values for the given parameters 159 */ 160 public Map<Locale, String> getLocalizationMap( 161 String[] languageIds, String[] values); 162 163 /** 164 * Returns the localizations XML for the parameter in the portlet request, 165 * attempting to get data from the preferences container when it is not 166 * available in the portlet request. 167 * 168 * @param preferences the preferences container 169 * @param portletRequest the portlet request 170 * @param parameter the prefix of the parameters containing the localized 171 * strings. Each localization will be loaded from a parameter with 172 * this prefix, followed by an underscore, and the language ID. 173 * @return the locales and localized strings 174 */ 175 public String getLocalizationXmlFromPreferences( 176 PortletPreferences preferences, PortletRequest portletRequest, 177 String parameter); 178 179 /** 180 * @deprecated Use {@link #getLocalizationMap(PortletRequest, String)} 181 * instead. 182 */ 183 public Map<Locale, String> getLocalizedParameter( 184 PortletRequest portletRequest, String parameter); 185 186 /** 187 * Returns the localized preferences key in the language. Generally this is 188 * just the preferences key, followed by an underscore, and the language ID. 189 * 190 * @param key the preferences key 191 * @param languageId the ID of the language 192 * @return the localized preferences key 193 */ 194 public String getPreferencesKey(String key, String languageId); 195 196 /** 197 * Returns the localized preferences value for the key in the language. Uses 198 * the default language if no localization exists for the requested 199 * language. 200 * 201 * @param preferences the preferences container 202 * @param key the preferences key 203 * @param languageId the ID of the language 204 * @return the localized preferences value 205 */ 206 public String getPreferencesValue( 207 PortletPreferences preferences, String key, String languageId); 208 209 /** 210 * Returns the localized preferences value for the key in the language, 211 * optionally using the default language if the no localization exists for 212 * the requested language. 213 * 214 * @param preferences the preferences container 215 * @param key the preferences key 216 * @param languageId the ID of the language 217 * @param useDefault whether to use the default language if no localization 218 * exists for the requested language 219 * @return the localized preferences value. If <code>useDefault</code> is 220 * <code>false</code> and no localization exists for the requested 221 * language, an empty string will be returned. 222 */ 223 public String getPreferencesValue( 224 PortletPreferences preferences, String key, String languageId, 225 boolean useDefault); 226 227 /** 228 * Returns the localized preferences values for the key in the language. 229 * Uses 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 values 236 */ 237 public String[] getPreferencesValues( 238 PortletPreferences preferences, String key, String languageId); 239 240 /** 241 * Returns the localized preferences values 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 values. If <code>useDefault</code> is 251 * <code>false</code> and no localization exists for the requested 252 * language, an empty array will be returned. 253 */ 254 public String[] getPreferencesValues( 255 PortletPreferences preferences, String key, String languageId, 256 boolean useDefault); 257 258 /** 259 * Removes the localization for the language from the localizations XML. 260 * Stores the localized strings as characters in the XML. 261 * 262 * @param xml the localizations XML 263 * @param key the name of the localized string, such as "Title" 264 * @param requestedLanguageId the ID of the language 265 * @return the localizations XML with the language removed 266 */ 267 public String removeLocalization( 268 String xml, String key, String requestedLanguageId); 269 270 /** 271 * Removes the localization for the language from the localizations XML, 272 * optionally storing the localized strings as CDATA in the XML. 273 * 274 * @param xml the localizations XML 275 * @param key the name of the localized string, such as "Title" 276 * @param requestedLanguageId the ID of the language 277 * @param cdata whether to store localized strings as CDATA in the XML 278 * @return the localizations XML with the language removed 279 */ 280 public String removeLocalization( 281 String xml, String key, String requestedLanguageId, boolean cdata); 282 283 /** 284 * Removes the localization for the language from the localizations XML, 285 * optionally storing the localized strings as CDATA in the XML. 286 * 287 * @param xml the localizations XML 288 * @param key the name of the localized string, such as "Title" 289 * @param requestedLanguageId the ID of the language 290 * @param cdata whether to store localized strings as CDATA in the XML 291 * @param localized whether there is a localized field 292 * @return the localizations XML with the language removed 293 */ 294 public String removeLocalization( 295 String xml, String key, String requestedLanguageId, boolean cdata, 296 boolean localized); 297 298 /** 299 * Sets the localized preferences values for the parameter in the portlet 300 * request. 301 * 302 * @param portletRequest the portlet request 303 * @param preferences the preferences container 304 * @param parameter the prefix of the parameters containing the localized 305 * strings. Each localization will be loaded from a parameter with 306 * this prefix, followed by an underscore, and the language ID. 307 * @throws Exception if an exception occurred 308 */ 309 public void setLocalizedPreferencesValues( 310 PortletRequest portletRequest, PortletPreferences preferences, 311 String parameter) 312 throws Exception; 313 314 /** 315 * Sets the localized preferences value for the key in the language. 316 * 317 * @param preferences the preferences container 318 * @param key the preferences key 319 * @param languageId the ID of the language 320 * @param value the localized value 321 * @throws Exception if an exception occurred 322 */ 323 public void setPreferencesValue( 324 PortletPreferences preferences, String key, String languageId, 325 String value) 326 throws Exception; 327 328 /** 329 * Sets the localized preferences values for the key in the language. 330 * 331 * @param preferences the preferences container 332 * @param key the preferences key 333 * @param languageId the ID of the language 334 * @param values the localized values 335 * @throws Exception if an exception occurred 336 */ 337 public void setPreferencesValues( 338 PortletPreferences preferences, String key, String languageId, 339 String[] values) 340 throws Exception; 341 342 /** 343 * Updates the localized string for the system default language in the 344 * localizations XML. Stores the localized strings as characters in the XML. 345 * 346 * @param xml the localizations XML 347 * @param key the name of the localized string, such as "Title" 348 * @param value the localized string 349 * @return the updated localizations XML 350 */ 351 public String updateLocalization(String xml, String key, String value); 352 353 /** 354 * Updates the localized string for the language in the localizations XML. 355 * Stores the localized strings as characters in the XML. 356 * 357 * @param xml the localizations XML 358 * @param key the name of the localized string, such as "Title" 359 * @param value the localized string 360 * @param requestedLanguageId the ID of the language 361 * @return the updated localizations XML 362 */ 363 public String updateLocalization( 364 String xml, String key, String value, String requestedLanguageId); 365 366 /** 367 * Updates the localized string for the language in the localizations XML 368 * and changes the default language. Stores the localized strings as 369 * characters in the XML. 370 * 371 * @param xml the localizations XML 372 * @param key the name of the localized string, such as "Title" 373 * @param value the localized string 374 * @param requestedLanguageId the ID of the language 375 * @param defaultLanguageId the ID of the default language 376 * @return the updated localizations XML 377 */ 378 public String updateLocalization( 379 String xml, String key, String value, String requestedLanguageId, 380 String defaultLanguageId); 381 382 /** 383 * Updates the localized string for the language in the localizations XML 384 * and changes the default language, optionally storing the localized 385 * strings as CDATA in the XML. 386 * 387 * @param xml the localizations XML 388 * @param key the name of the localized string, such as "Title" 389 * @param value the localized string 390 * @param requestedLanguageId the ID of the language 391 * @param defaultLanguageId the ID of the default language 392 * @param cdata whether to store localized strings as CDATA in the XML 393 * @return the updated localizations XML 394 */ 395 public String updateLocalization( 396 String xml, String key, String value, String requestedLanguageId, 397 String defaultLanguageId, boolean cdata); 398 399 /** 400 * Updates the localized string for the language in the localizations XML 401 * and changes the default language, optionally storing the localized 402 * strings as CDATA 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 * @param defaultLanguageId the ID of the default language 409 * @param cdata whether to store localized strings as CDATA in the XML 410 * @param localized whether there is a localized field 411 * @return the updated localizations XML 412 */ 413 public String updateLocalization( 414 String xml, String key, String value, String requestedLanguageId, 415 String defaultLanguageId, boolean cdata, boolean localized); 416 417 }