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