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