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    import javax.servlet.http.HttpServletRequest;
026    
027    /**
028     * Stores and retrieves localized strings from XML, and provides utility methods
029     * for updating localizations from JSON, portlet requests, and maps. Used for
030     * adding localization to strings, most often for model properties.
031     *
032     * <p>
033     * Localized values are cached in this class rather than in the value object
034     * since value objects get flushed from cache fairly quickly. Though lookups
035     * performed on a key based on an XML file are slower than lookups done at the
036     * value object level in general, the value object will get flushed at a rate
037     * which works against the performance gain. The cache is a soft hash map which
038     * prevents memory leaks within the system while enabling the cache to live
039     * longer than in a weak hash map.
040     * </p>
041     *
042     * @author Alexander Chow
043     * @author Jorge Ferrer
044     * @author Mauro Mariuzzo
045     * @author Julio Camarero
046     * @author Brian Wing Shun Chan
047     */
048    public interface Localization {
049    
050            /**
051             * Deserializes the JSON object into a map of locales and localized strings.
052             *
053             * @param  jsonObject the JSON object
054             * @return the locales and localized strings
055             */
056            public Object deserialize(JSONObject jsonObject);
057    
058            /**
059             * Returns the available locales from the localizations XML.
060             *
061             * @param  xml the localizations XML
062             * @return the language IDs of the available locales
063             */
064            public String[] getAvailableLocales(String xml);
065    
066            /**
067             * Returns a valid default locale for importing a localized entity.
068             *
069             * @param  className the class name of the entity
070             * @param  classPK the primary keys of the entity
071             * @param  contentDefaultLocale the default Locale of the entity
072             * @param  contentAvailableLocales the available locales of the entity
073             * @return the valid locale
074             */
075            public Locale getDefaultImportLocale(
076                    String className, long classPK, Locale contentDefaultLocale,
077                    Locale[] contentAvailableLocales);
078    
079            /**
080             * Returns the default locale from the localizations XML.
081             *
082             * @param  xml the localizations XML
083             * @return the language ID of the default locale, or the system default
084             *         locale if the default locale cannot be retrieved from the XML
085             */
086            public String getDefaultLocale(String xml);
087    
088            /**
089             * Returns the localized string from the localizations XML in the language.
090             * Uses the default language if no localization exists for the requested
091             * language.
092             *
093             * @param  xml the localizations XML
094             * @param  requestedLanguageId the ID of the language
095             * @return the localized string
096             */
097            public String getLocalization(String xml, String requestedLanguageId);
098    
099            /**
100             * Returns the localized string from the localizations XML in the language,
101             * optionally using the default language if the no localization exists for
102             * the requested language.
103             *
104             * @param  xml the localizations XML
105             * @param  requestedLanguageId the ID of the language
106             * @param  useDefault whether to use the default language if no localization
107             *         exists for the requested language
108             * @return the localized string. If <code>useDefault</code> is
109             *         <code>false</code> and no localization exists for the requested
110             *         language, an empty string will be returned.
111             */
112            public String getLocalization(
113                    String xml, String requestedLanguageId, boolean useDefault);
114    
115            /**
116             * Returns a map of locales and localized strings for the parameter in the
117             * request.
118             *
119             * @param  request the request
120             * @param  parameter the prefix of the parameters containing the localized
121             *         strings. Each localization will be loaded from a parameter with
122             *         this prefix, followed by an underscore, and the language ID.
123             * @return the locales and localized strings
124             */
125            public Map<Locale, String> getLocalizationMap(
126                    HttpServletRequest request, String parameter);
127    
128            /**
129             * Returns a map of locales and localized strings for the parameter in the
130             * preferences container.
131             *
132             * @param  preferences the preferences container
133             * @param  parameter the prefix of the parameters containing the localized
134             *         strings. Each localization will be loaded from a parameter with
135             *         this prefix, followed by an underscore, and the language ID.
136             * @return the locales and localized strings
137             */
138            public Map<Locale, String> getLocalizationMap(
139                    PortletPreferences preferences, String parameter);
140    
141            /**
142             * Returns a map of locales and localized strings for the parameter in the
143             * portlet request.
144             *
145             * @param  portletRequest the portlet request
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 Map<Locale, String> getLocalizationMap(
152                    PortletRequest portletRequest, String parameter);
153    
154            /**
155             * Returns a map of locales and localized strings from the localizations
156             * XML.
157             *
158             * @param  xml the localizations XML
159             * @return the locales and localized strings
160             */
161            public Map<Locale, String> getLocalizationMap(String xml);
162    
163            public Map<Locale, String> getLocalizationMap(
164                    String xml, boolean useDefault);
165    
166            public Map<Locale, String> getLocalizationMap(
167                    String bundleName, ClassLoader classLoader, String key,
168                    boolean includeBetaLocales);
169    
170            /**
171             * Returns a map of locales and localized strings for the given languageIds
172             * and values.
173             *
174             * @param  languageIds the languageIds of the localized Strings
175             * @param  values the localized strings for the different languageId
176             * @return the map of locales and values for the given parameters
177             */
178            public Map<Locale, String> getLocalizationMap(
179                    String[] languageIds, String[] values);
180    
181            /**
182             * Returns the localizations XML for the parameter in the portlet request,
183             * attempting to get data from the preferences container when it is not
184             * available in the portlet request.
185             *
186             * @param  preferences the preferences container
187             * @param  portletRequest the portlet request
188             * @param  parameter the prefix of the parameters containing the localized
189             *         strings. Each localization will be loaded from a parameter with
190             *         this prefix, followed by an underscore, and the language ID.
191             * @return the locales and localized strings
192             */
193            public String getLocalizationXmlFromPreferences(
194                    PortletPreferences preferences, PortletRequest portletRequest,
195                    String parameter);
196    
197            /**
198             * @deprecated As of 6.2.0, replaced by {@link
199             *             #getLocalizationMap(PortletRequest, String)}
200             */
201            public Map<Locale, String> getLocalizedParameter(
202                    PortletRequest portletRequest, String parameter);
203    
204            /**
205             * Returns the localized preferences key in the language. Generally this is
206             * just the preferences key, followed by an underscore, and the language ID.
207             *
208             * @param  key the preferences key
209             * @param  languageId the ID of the language
210             * @return the localized preferences key
211             */
212            public String getPreferencesKey(String key, String languageId);
213    
214            /**
215             * Returns the localized preferences value for the key in the language. Uses
216             * the default language if no localization exists for the requested
217             * language.
218             *
219             * @param  preferences the preferences container
220             * @param  key the preferences key
221             * @param  languageId the ID of the language
222             * @return the localized preferences value
223             */
224            public String getPreferencesValue(
225                    PortletPreferences preferences, String key, String languageId);
226    
227            /**
228             * Returns the localized preferences value for the key in the language,
229             * optionally using the default language if the no localization exists for
230             * the requested language.
231             *
232             * @param  preferences the preferences container
233             * @param  key the preferences key
234             * @param  languageId the ID of the language
235             * @param  useDefault whether to use the default language if no localization
236             *         exists for the requested language
237             * @return the localized preferences value. If <code>useDefault</code> is
238             *         <code>false</code> and no localization exists for the requested
239             *         language, an empty string will be returned.
240             */
241            public String getPreferencesValue(
242                    PortletPreferences preferences, String key, String languageId,
243                    boolean useDefault);
244    
245            /**
246             * Returns the localized preferences values for the key in the language.
247             * Uses the default language if no localization exists for the requested
248             * language.
249             *
250             * @param  preferences the preferences container
251             * @param  key the preferences key
252             * @param  languageId the ID of the language
253             * @return the localized preferences values
254             */
255            public String[] getPreferencesValues(
256                    PortletPreferences preferences, String key, String languageId);
257    
258            /**
259             * Returns the localized preferences values for the key in the language,
260             * optionally using the default language if the no localization exists for
261             * the requested language.
262             *
263             * @param  preferences the preferences container
264             * @param  key the preferences key
265             * @param  languageId the ID of the language
266             * @param  useDefault whether to use the default language if no localization
267             *         exists for the requested language
268             * @return the localized preferences values. If <code>useDefault</code> is
269             *         <code>false</code> and no localization exists for the requested
270             *         language, an empty array will be returned.
271             */
272            public String[] getPreferencesValues(
273                    PortletPreferences preferences, String key, String languageId,
274                    boolean useDefault);
275    
276            /**
277             * Removes the localization for the language from the localizations XML.
278             * Stores the localized strings as characters in the XML.
279             *
280             * @param  xml the localizations XML
281             * @param  key the name of the localized string, such as &quot;Title&quot;
282             * @param  requestedLanguageId the ID of the language
283             * @return the localizations XML with the language removed
284             */
285            public String removeLocalization(
286                    String xml, String key, String requestedLanguageId);
287    
288            /**
289             * Removes the localization for the language from the localizations XML,
290             * optionally storing the localized strings as CDATA in the XML.
291             *
292             * @param  xml the localizations XML
293             * @param  key the name of the localized string, such as &quot;Title&quot;
294             * @param  requestedLanguageId the ID of the language
295             * @param  cdata whether to store localized strings as CDATA in the XML
296             * @return the localizations XML with the language removed
297             */
298            public String removeLocalization(
299                    String xml, String key, String requestedLanguageId, boolean cdata);
300    
301            /**
302             * Removes the localization for the language from the localizations XML,
303             * optionally storing the localized strings as CDATA in the XML.
304             *
305             * @param  xml the localizations XML
306             * @param  key the name of the localized string, such as &quot;Title&quot;
307             * @param  requestedLanguageId the ID of the language
308             * @param  cdata whether to store localized strings as CDATA in the XML
309             * @param  localized whether there is a localized field
310             * @return the localizations XML with the language removed
311             */
312            public String removeLocalization(
313                    String xml, String key, String requestedLanguageId, boolean cdata,
314                    boolean localized);
315    
316            /**
317             * Sets the localized preferences values for the parameter in the portlet
318             * request.
319             *
320             * @param  portletRequest the portlet request
321             * @param  preferences the preferences container
322             * @param  parameter the prefix of the parameters containing the localized
323             *         strings. Each localization will be loaded from a parameter with
324             *         this prefix, followed by an underscore, and the language ID.
325             * @throws Exception if an exception occurred
326             */
327            public void setLocalizedPreferencesValues(
328                            PortletRequest portletRequest, PortletPreferences preferences,
329                            String parameter)
330                    throws Exception;
331    
332            /**
333             * Sets the localized preferences value for the key in the language.
334             *
335             * @param  preferences the preferences container
336             * @param  key the preferences key
337             * @param  languageId the ID of the language
338             * @param  value the localized value
339             * @throws Exception if an exception occurred
340             */
341            public void setPreferencesValue(
342                            PortletPreferences preferences, String key, String languageId,
343                            String value)
344                    throws Exception;
345    
346            /**
347             * Sets the localized preferences values for the key in the language.
348             *
349             * @param  preferences the preferences container
350             * @param  key the preferences key
351             * @param  languageId the ID of the language
352             * @param  values the localized values
353             * @throws Exception if an exception occurred
354             */
355            public void setPreferencesValues(
356                            PortletPreferences preferences, String key, String languageId,
357                            String[] values)
358                    throws Exception;
359    
360            /**
361             * Updates the localized string for all the available languages in the
362             * localizations XML for the map of locales and localized strings and
363             * changes the default language. Stores the localized strings as characters
364             * in the XML.
365             *
366             * @param  localizationMap the locales and localized strings
367             * @param  xml the localizations XML
368             * @param  key the name of the localized string, such as &quot;Title&quot;
369             * @param  defaultLanguageId the ID of the default language
370             * @return the updated localizations XML
371             */
372            public String updateLocalization(
373                    Map<Locale, String> localizationMap, String xml, String key,
374                    String defaultLanguageId);
375    
376            /**
377             * Updates the localized string for the system default language in the
378             * localizations XML. Stores the localized strings as characters in the XML.
379             *
380             * @param  xml the localizations XML
381             * @param  key the name of the localized string, such as &quot;Title&quot;
382             * @param  value the localized string
383             * @return the updated localizations XML
384             */
385            public String updateLocalization(String xml, String key, String value);
386    
387            /**
388             * Updates the localized string for the language in the localizations XML.
389             * Stores the localized strings as characters in the XML.
390             *
391             * @param  xml the localizations XML
392             * @param  key the name of the localized string, such as &quot;Title&quot;
393             * @param  value the localized string
394             * @param  requestedLanguageId the ID of the language
395             * @return the updated localizations XML
396             */
397            public String updateLocalization(
398                    String xml, String key, String value, String requestedLanguageId);
399    
400            /**
401             * Updates the localized string for the language in the localizations XML
402             * and changes the default language. Stores the localized strings as
403             * characters in the XML.
404             *
405             * @param  xml the localizations XML
406             * @param  key the name of the localized string, such as &quot;Title&quot;
407             * @param  value the localized string
408             * @param  requestedLanguageId the ID of the language
409             * @param  defaultLanguageId the ID of the default language
410             * @return the updated localizations XML
411             */
412            public String updateLocalization(
413                    String xml, String key, String value, String requestedLanguageId,
414                    String defaultLanguageId);
415    
416            /**
417             * Updates the localized string for the language in the localizations XML
418             * and changes the default language, optionally storing the localized
419             * strings as CDATA in the XML.
420             *
421             * @param  xml the localizations XML
422             * @param  key the name of the localized string, such as &quot;Title&quot;
423             * @param  value the localized string
424             * @param  requestedLanguageId the ID of the language
425             * @param  defaultLanguageId the ID of the default language
426             * @param  cdata whether to store localized strings as CDATA in the XML
427             * @return the updated localizations XML
428             */
429            public String updateLocalization(
430                    String xml, String key, String value, String requestedLanguageId,
431                    String defaultLanguageId, boolean cdata);
432    
433            /**
434             * Updates the localized string for the language in the localizations XML
435             * and changes the default language, optionally storing the localized
436             * strings as CDATA in the XML.
437             *
438             * @param  xml the localizations XML
439             * @param  key the name of the localized string, such as &quot;Title&quot;
440             * @param  value the localized string
441             * @param  requestedLanguageId the ID of the language
442             * @param  defaultLanguageId the ID of the default language
443             * @param  cdata whether to store localized strings as CDATA in the XML
444             * @param  localized whether there is a localized field
445             * @return the updated localizations XML
446             */
447            public String updateLocalization(
448                    String xml, String key, String value, String requestedLanguageId,
449                    String defaultLanguageId, boolean cdata, boolean localized);
450    
451    }