001 /** 002 * Copyright (c) 2000-2011 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 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 * Caching of the localized values is done in this class rather than in the 032 * value object since value objects get flushed from cache fairly quickly. 033 * Though lookups performed on a key based on an XML file is slower than lookups 034 * done at the value object level in general, the value object will get flushed 035 * at a rate which works against the performance gain. The cache is a soft hash 036 * map which prevents memory leaks within the system while enabling the cache to 037 * live 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 to deserialize 052 * @return the locales and localized strings 053 */ 054 public Object deserialize(JSONObject jsonObject); 055 056 /** 057 * Gets the available locales from the localizations XML 058 * 059 * @param xml the localizations XML to get the available locales from 060 * @return the language IDs of the available locales 061 */ 062 public String[] getAvailableLocales(String xml); 063 064 /** 065 * Gets the default locale from the localizations XML. 066 * 067 * @param xml the localizations XML to get the default locale from 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 * Gets the localized string from the localizations XML. Uses the default 075 * language if no localization exists for the requested language. 076 * 077 * @param xml the localizations XML to get the localized string from 078 * @param requestedLanguageId the ID of the language to get the 079 * localization for 080 * @return the localized string 081 */ 082 public String getLocalization(String xml, String requestedLanguageId); 083 084 /** 085 * Gets the localized string from the localizations XML, optionally using 086 * the default language if the no localization exists for the requested 087 * language. 088 * 089 * @param xml the localizations XML to get the localized string from 090 * @param requestedLanguageId the ID of the language to get the 091 * localization for 092 * @param useDefault whether to use the default language if no localization 093 * exists for the requested language 094 * @return the localized string. If <code>useDefault</code> is 095 * <code>false</code> and no localization exists for the requested 096 * language, an empty string will be returned. 097 */ 098 public String getLocalization( 099 String xml, String requestedLanguageId, boolean useDefault); 100 101 /** 102 * Gets a map of locales and localized strings for the parameter in the 103 * portlet request. 104 * 105 * @param preferences the preferences container to get the locales and 106 * localized strings from 107 * @param parameter the prefix of the parameters containing the localized 108 * strings. Each localization will be loaded from a parameter with 109 * this prefix, followed by an underscore, and the language ID. 110 * @return the locales and localized strings 111 */ 112 public Map<Locale, String> getLocalizationMap( 113 PortletPreferences preferences, String parameter); 114 115 /** 116 * Gets a map of locales and localized strings for the parameter in the 117 * portlet request. 118 * 119 * @param portletRequest the portlet request to get the locales and 120 * localized strings from 121 * @param parameter the prefix of the parameters containing the localized 122 * strings. Each localization will be loaded from a parameter with 123 * this prefix, followed by an underscore, and the language ID. 124 * @return the locales and localized strings 125 */ 126 public Map<Locale, String> getLocalizationMap( 127 PortletRequest portletRequest, String parameter); 128 129 /** 130 * Gets a map of locales and localized strings from the localizations XML. 131 * 132 * @param xml the localizations XML to get the locales and localized 133 * strings from 134 * @return the locales and localized strings 135 */ 136 public Map<Locale, String> getLocalizationMap(String xml); 137 138 /** 139 * Gets an xml of locales and localized strings for the parameter in the 140 * portlet request. 141 * 142 * @param preferences the preferences container to get the localized value 143 * from 144 * @param portletRequest the portlet request to get the locales and 145 * localized strings from 146 * @param parameter the prefix of the parameters containing the localized 147 * strings. Each localization will be loaded from a parameter with 148 * this prefix, followed by an underscore, and the language ID. 149 * @return the locales and localized strings 150 */ 151 public String getLocalizationXmlFromPreferences( 152 PortletPreferences preferences, PortletRequest portletRequest, 153 String parameter); 154 155 /** 156 * @deprecated use {@link #getLocalizationMap(PortletRequest, String)} 157 * instead. 158 */ 159 public Map<Locale, String> getLocalizedParameter( 160 PortletRequest portletRequest, String parameter); 161 162 /** 163 * Gets the localized name of the key. Uses the default language if no 164 * localization exists for the requested language. 165 * 166 * @param key the preferences key to get the localized name for 167 * @param languageId the ID of the language to get the localization for 168 * @return the localized preferences key 169 */ 170 public String getPreferencesKey(String key, String languageId); 171 172 /** 173 * Gets the localized preferences value for the key. Uses the default 174 * language if no localization exists for the requested language. 175 * 176 * @param preferences the preferences container to get the localized value 177 * from 178 * @param key the preferences key to get the localized value for 179 * @param languageId the ID of the language to get the localization for 180 * @return the localized preferences value 181 */ 182 public String getPreferencesValue( 183 PortletPreferences preferences, String key, String languageId); 184 185 /** 186 * Gets the localized preferences value for the key, optionally using the 187 * default language if the no localization exists for the requested 188 * language. 189 * 190 * @param preferences the preferences container to get the localized value 191 * from 192 * @param key the preferences key to get the localized value for 193 * @param languageId the ID of the language to get the localization for 194 * @param useDefault whether to use the default language if no localization 195 * exists for the requested language 196 * @return the localized preferences value. If <code>useDefault</code> is 197 * <code>false</code> and no localization exists for the requested 198 * language, an empty string will be returned. 199 */ 200 public String getPreferencesValue( 201 PortletPreferences preferences, String key, String languageId, 202 boolean useDefault); 203 204 /** 205 * Gets the localized preferences values for the key. Uses the default 206 * language if no localization exists for the requested language. 207 * 208 * @param preferences the preferences container to get the localized values 209 * from 210 * @param key the preferences key to get localized values for 211 * @param languageId the ID of the language to get the localizations for 212 * @return the localized preferences values 213 */ 214 public String[] getPreferencesValues( 215 PortletPreferences preferences, String key, String languageId); 216 217 /** 218 * Gets the localized preferences values for the key, optionally using the 219 * default language if the no localization exists for the requested 220 * language. 221 * 222 * @param preferences the preferences container to get the localized values 223 * from 224 * @param key the preferences key to get localized values for 225 * @param languageId the ID of the language to get the localizations for 226 * @param useDefault whether to use the default language if no localization 227 * exists for the requested language 228 * @return the localized preferences values. If <code>useDefault</code> is 229 * <code>false</code> and no localization exists for the requested 230 * language, an empty array will be returned. 231 */ 232 public String[] getPreferencesValues( 233 PortletPreferences preferences, String key, String languageId, 234 boolean useDefault); 235 236 /** 237 * Removes the localization for the language from the localizations XML. 238 * Stores the localized strings as characters in the XML. 239 * 240 * @param xml the localizations XML to remove the localization for the 241 * language from 242 * @param key the name of the localized string, such as "Title" 243 * @param requestedLanguageId the ID of the language to remove from the 244 * localizations XML 245 * @return the localizations XML with the language removed 246 */ 247 public String removeLocalization( 248 String xml, String key, String requestedLanguageId); 249 250 /** 251 * Removes the localization for the language from the localizations XML, 252 * optionally storing the localized strings as CDATA in the XML. 253 * 254 * @param xml the localizations XML to remove the localization for the 255 * language from 256 * @param key the name of the localized string, such as "Title" 257 * @param requestedLanguageId the ID of the language to remove from the 258 * localizations XML 259 * @param cdata whether to store localized strings as CDATA in the XML 260 * @return the localizations XML with the language removed 261 */ 262 public String removeLocalization( 263 String xml, String key, String requestedLanguageId, boolean cdata); 264 265 /** 266 * Removes the localization for the language from the localizations XML, 267 * optionally storing the localized strings as CDATA in the XML. 268 * 269 * @param xml the localizations XML to remove the localization for the 270 * language from 271 * @param key the name of the localized string, such as "Title" 272 * @param requestedLanguageId the ID of the language to remove from the 273 * localizations XML 274 * @param cdata whether to store localized strings as CDATA in the XML 275 * @param localized whether there is a localized field 276 * @return the localizations XML with the language removed 277 */ 278 public String removeLocalization( 279 String xml, String key, String requestedLanguageId, boolean cdata, 280 boolean localized); 281 282 /** 283 * Sets the localized preferences values for the parameter in the portlet 284 * request. 285 * 286 * @param portletRequest the portlet request to get the localized values 287 * from 288 * @param preferences the preferences container to set the localized values 289 * in 290 * @param parameter the prefix of the parameters containing the localized 291 * strings. Each localization will be loaded from a parameter with 292 * this prefix, followed by an underscore, and the language ID. 293 * @throws Exception if an exception occurred 294 */ 295 public void setLocalizedPreferencesValues ( 296 PortletRequest portletRequest, PortletPreferences preferences, 297 String parameter) 298 throws Exception; 299 300 /** 301 * Sets the localized preferences value for the key. 302 * 303 * @param preferences the preferences container to store the localized 304 * value in 305 * @param key the preferences key to set the localized value for 306 * @param languageId the ID of the language to set the localization for 307 * @param value the localized value 308 * @throws Exception if an exception occurred 309 */ 310 public void setPreferencesValue( 311 PortletPreferences preferences, String key, String languageId, 312 String value) 313 throws Exception; 314 315 /** 316 * Sets the localized preferences values for the key. 317 * 318 * @param preferences the preferences container to store the localized 319 * values in 320 * @param key the preferences key to set the localized values for 321 * @param languageId the ID of the language to set the localizations for 322 * @param values the localized values 323 * @throws Exception if an exception occurred 324 */ 325 public void setPreferencesValues( 326 PortletPreferences preferences, String key, String languageId, 327 String[] values) 328 throws Exception; 329 330 /** 331 * Updates the localized string for the system default language in the 332 * localizations XML. Stores the localized strings as characters in the XML. 333 * 334 * @param xml the localizations XML to update the localized string in 335 * @param key the name of the localized string, such as "Title" 336 * @param value the localized string 337 * @return the updated localizations XML 338 */ 339 public String updateLocalization(String xml, String key, String value); 340 341 /** 342 * Updates the localized string for the language in the localizations XML. 343 * Stores the localized strings as characters in the XML. 344 * 345 * @param xml the localizations XML to update the localized string in 346 * @param key the name of the localized string, such as "Title" 347 * @param value the localized string 348 * @param requestedLanguageId the ID of the language to update the 349 * localization for 350 * @return the updated localizations XML 351 */ 352 public String updateLocalization( 353 String xml, String key, String value, String requestedLanguageId); 354 355 /** 356 * Updates the localized string for the language in the localizations XML 357 * and changes the default language. Stores the localized strings as 358 * characters in the XML. 359 * 360 * @param xml the localizations XML to update the localized string in 361 * @param key the name of the localized string, such as "Title" 362 * @param value the localized string 363 * @param requestedLanguageId the ID of the language to update the 364 * localization for 365 * @param defaultLanguageId the ID of the default language 366 * @return the updated localizations XML 367 */ 368 public String updateLocalization( 369 String xml, String key, String value, String requestedLanguageId, 370 String defaultLanguageId); 371 372 /** 373 * Updates the localized string for the language in the localizations XML 374 * and changes the default language, optionally storing the localized 375 * strings as CDATA in the XML. 376 * 377 * @param xml the localizations XML to update the localized string in 378 * @param key the name of the localized string, such as "Title" 379 * @param value the localized string 380 * @param requestedLanguageId the ID of the language to update the 381 * localization for 382 * @param defaultLanguageId the ID of the default language 383 * @param cdata whether to store localized strings as CDATA in the XML 384 * @return the updated localizations XML 385 */ 386 public String updateLocalization( 387 String xml, String key, String value, String requestedLanguageId, 388 String defaultLanguageId, boolean cdata); 389 390 /** 391 * Updates the localized string for the language in the localizations XML 392 * and changes the default language, optionally storing the localized 393 * strings as CDATA in the XML. 394 * 395 * @param xml the localizations XML to update the localized string in 396 * @param key the name of the localized string, such as "Title" 397 * @param value the localized string 398 * @param requestedLanguageId the ID of the language to update the 399 * localization for 400 * @param defaultLanguageId the ID of the default language 401 * @param cdata whether to store localized strings as CDATA in the XML 402 * @param localized whether there is a localized field 403 * @return the updated localizations XML 404 */ 405 public String updateLocalization( 406 String xml, String key, String value, String requestedLanguageId, 407 String defaultLanguageId, boolean cdata, boolean localized); 408 409 }