001 /** 002 * Copyright (c) 2000-2010 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 * 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 portletRequest the portlet request 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 PortletRequest portletRequest, String parameter); 114 115 /** 116 * Gets a map of locales and localized strings from the localizations XML. 117 * 118 * @param xml the localizations XML to get the locales and localized 119 * strings from 120 * @return the locales and localized strings 121 */ 122 public Map<Locale, String> getLocalizationMap(String xml); 123 124 /** 125 * Gets an xml of locales and localized strings for the parameter in the 126 * portlet request. 127 * 128 * @param preferences the preferences container to get the localized value 129 * from 130 * @param portletRequest the portlet request to get the locales and 131 * localized strings from 132 * @param parameter the prefix of the parameters containing the localized 133 * strings. Each localization will be loaded from a parameter with 134 * this prefix, followed by an underscore, and the language id. 135 * @return the locales and localized strings 136 */ 137 public String getLocalizationXmlFromPreferences( 138 PortletPreferences preferences, PortletRequest portletRequest, 139 String parameter); 140 141 /** 142 * @deprecated use {@link #getLocalizationMap(PortletRequest, String)} 143 * instead. 144 */ 145 public Map<Locale, String> getLocalizedParameter( 146 PortletRequest portletRequest, String parameter); 147 148 /** 149 * Gets the localized preferences value for the key. Uses the default 150 * language if no localization exists for the requested language. 151 * 152 * @param preferences the preferences container to get the localized value 153 * from 154 * @param key the preferences key to get the localized value for 155 * @param languageId the id of the language to get the localization for 156 * @return the localized preferences value 157 */ 158 public String getPreferencesValue( 159 PortletPreferences preferences, String key, String languageId); 160 161 /** 162 * Gets the localized preferences value for the key, optionally using the 163 * default language if the no localization exists for the requested 164 * language. 165 * 166 * @param preferences the preferences container to get the localized value 167 * from 168 * @param key the preferences key to get the localized value for 169 * @param languageId the id of the language to get the localization for 170 * @param useDefault whether to use the default language if no localization 171 * exists for the requested language 172 * @return the localized preferences value. If <code>useDefault</code> is 173 * <code>false</code> and no localization exists for the requested 174 * language, an empty string will be returned. 175 */ 176 public String getPreferencesValue( 177 PortletPreferences preferences, String key, String languageId, 178 boolean useDefault); 179 180 /** 181 * Gets the localized preferences values for the key. Uses the default 182 * language if no localization exists for the requested language. 183 * 184 * @param preferences the preferences container to get the localized values 185 * from 186 * @param key the preferences key to get localized values for 187 * @param languageId the id of the language to get the localizations for 188 * @return the localized preferences values 189 */ 190 public String[] getPreferencesValues( 191 PortletPreferences preferences, String key, String languageId); 192 193 /** 194 * Gets the localized preferences values for the key, optionally using the 195 * default language if the no localization exists for the requested 196 * language. 197 * 198 * @param preferences the preferences container to get the localized values 199 * from 200 * @param key the preferences key to get localized values for 201 * @param languageId the id of the language to get the localizations for 202 * @param useDefault whether to use the default language if no localization 203 * exists for the requested language 204 * @return the localized preferences values. If <code>useDefault</code> is 205 * <code>false</code> and no localization exists for the requested 206 * language, an empty array will be returned. 207 */ 208 public String[] getPreferencesValues( 209 PortletPreferences preferences, String key, String languageId, 210 boolean useDefault); 211 212 /** 213 * Removes the localization for the language from the localizations XML. 214 * Stores the localized strings as characters in the XML. 215 * 216 * @param xml the localizations XML to remove the localization for the 217 * language from 218 * @param key the name of the localized string, such as "Title" 219 * @param requestedLanguageId the id of the language to remove from the 220 * localizations XML 221 * @return the localizations XML with the language removed 222 */ 223 public String removeLocalization( 224 String xml, String key, String requestedLanguageId); 225 226 /** 227 * Removes the localization for the language from the localizations XML, 228 * optionally storing the localized strings as CDATA in the XML. 229 * 230 * @param xml the localizations XML to remove the localization for the 231 * language from 232 * @param key the name of the localized string, such as "Title" 233 * @param requestedLanguageId the id of the language to remove from the 234 * localizations XML 235 * @param cdata whether to store localized strings as CDATA in the XML 236 * @return the localizations XML with the language removed 237 */ 238 public String removeLocalization( 239 String xml, String key, String requestedLanguageId, boolean cdata); 240 241 /** 242 * Sets the localized preferences values for the parameter in the portlet 243 * request. 244 * 245 * @param portletRequest the portlet request to get the localized values 246 * from 247 * @param preferences the preferences container to set the localized values 248 * in 249 * @param parameter the prefix of the parameters containing the localized 250 * strings. Each localization will be loaded from a parameter with 251 * this prefix, followed by an underscore, and the language id. 252 * @throws Exception if an exception occurred 253 */ 254 public void setLocalizedPreferencesValues ( 255 PortletRequest portletRequest, PortletPreferences preferences, 256 String parameter) 257 throws Exception; 258 259 /** 260 * Sets the localized preferences value for the key. 261 * 262 * @param preferences the preferences container to store the localized 263 * value in 264 * @param key the preferences key to set the localized value for 265 * @param languageId the id of the language to set the localization for 266 * @param value the localized value 267 * @throws Exception if an exception occurred 268 */ 269 public void setPreferencesValue( 270 PortletPreferences preferences, String key, String languageId, 271 String value) 272 throws Exception; 273 274 /** 275 * Sets the localized preferences values for the key. 276 * 277 * @param preferences the preferences container to store the localized 278 * values in 279 * @param key the preferences key to set the localized values for 280 * @param languageId the id of the language to set the localizations for 281 * @param values the localized values 282 * @throws Exception if an exception occurred 283 */ 284 public void setPreferencesValues( 285 PortletPreferences preferences, String key, String languageId, 286 String[] values) 287 throws Exception; 288 289 /** 290 * Updates the localized string for the system default language in the 291 * localizations XML. Stores the localized strings as characters in the XML. 292 * 293 * @param xml the localizations XML to update the localized string in 294 * @param key the name of the localized string, such as "Title" 295 * @param value the localized string 296 * @return the updated localizations XML 297 */ 298 public String updateLocalization(String xml, String key, String value); 299 300 /** 301 * Updates the localized string for the language in the localizations XML. 302 * Stores the localized strings as characters in the XML. 303 * 304 * @param xml the localizations XML to update the localized string in 305 * @param key the name of the localized string, such as "Title" 306 * @param value the localized string 307 * @param requestedLanguageId the id of the language to update the 308 * localization for 309 * @return the updated localizations XML 310 */ 311 public String updateLocalization( 312 String xml, String key, String value, String requestedLanguageId); 313 314 /** 315 * Updates the localized string for the language in the localizations XML 316 * and changes the default language. Stores the localized strings as 317 * characters in the XML. 318 * 319 * @param xml the localizations XML to update the localized string in 320 * @param key the name of the localized string, such as "Title" 321 * @param value the localized string 322 * @param requestedLanguageId the id of the language to update the 323 * localization for 324 * @param defaultLanguageId the id of the default language 325 * @return the updated localizations XML 326 */ 327 public String updateLocalization( 328 String xml, String key, String value, String requestedLanguageId, 329 String defaultLanguageId); 330 331 /** 332 * Updates the localized string for the language in the localizations XML 333 * and changes the default language, optionally storing the localized 334 * strings as CDATA in the XML. 335 * 336 * @param xml the localizations XML to update the localized string in 337 * @param key the name of the localized string, such as "Title" 338 * @param value the localized string 339 * @param requestedLanguageId the id of the language to update the 340 * localization for 341 * @param defaultLanguageId the id of the default language 342 * @param cdata whether to store localized strings as CDATA in the XML 343 * @return the updated localizations XML 344 */ 345 public String updateLocalization( 346 String xml, String key, String value, String requestedLanguageId, 347 String defaultLanguageId, boolean cdata); 348 349 }