001    /**
002     * Copyright (c) 2000-present 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    import com.liferay.portal.kernel.settings.Settings;
019    import com.liferay.portal.kernel.xml.Document;
020    
021    import java.util.Locale;
022    import java.util.Map;
023    
024    import javax.portlet.PortletPreferences;
025    import javax.portlet.PortletRequest;
026    
027    import javax.servlet.http.HttpServletRequest;
028    
029    /**
030     * Stores and retrieves localized strings from XML, and provides utility methods
031     * for updating localizations from JSON, portlet requests, and maps. Used for
032     * adding localization to strings, most often for model properties.
033     *
034     * <p>
035     * Localized values are cached in this class rather than in the value object
036     * since value objects get flushed from cache fairly quickly. Though lookups
037     * performed on a key based on an XML file are slower than lookups done at the
038     * value object level in general, the value object will get flushed at a rate
039     * which works against the performance gain. The cache is a soft hash map which
040     * prevents memory leaks within the system while enabling the cache to live
041     * longer than in a weak hash map.
042     * </p>
043     *
044     * @author Alexander Chow
045     * @author Jorge Ferrer
046     * @author Mauro Mariuzzo
047     * @author Julio Camarero
048     * @author Brian Wing Shun Chan
049     */
050    public interface Localization {
051    
052            /**
053             * Deserializes the JSON object into a map of locales and localized strings.
054             *
055             * @param  jsonObject the JSON object
056             * @return the locales and localized strings
057             */
058            public Object deserialize(JSONObject jsonObject);
059    
060            public String[] getAvailableLanguageIds(Document document);
061    
062            /**
063             * Returns the available locales from the localizations XML.
064             *
065             * @param  xml the localizations XML
066             * @return the language IDs of the available locales
067             */
068            public String[] getAvailableLanguageIds(String xml);
069    
070            /**
071             * Returns a valid default locale for importing a localized entity.
072             *
073             * @param  className the class name of the entity
074             * @param  classPK the primary keys of the entity
075             * @param  contentDefaultLocale the default Locale of the entity
076             * @param  contentAvailableLocales the available locales of the entity
077             * @return the valid locale
078             */
079            public Locale getDefaultImportLocale(
080                    String className, long classPK, Locale contentDefaultLocale,
081                    Locale[] contentAvailableLocales);
082    
083            public String getDefaultLanguageId(Document document);
084    
085            public String getDefaultLanguageId(Document document, Locale defaultLocale);
086    
087            /**
088             * Returns the default locale from the localizations XML.
089             *
090             * @param  xml the localizations XML
091             * @return the language ID of the default locale, or the system default
092             *         locale if the default locale cannot be retrieved from the XML
093             */
094            public String getDefaultLanguageId(String xml);
095    
096            public String getDefaultLanguageId(String xml, Locale defaultLocale);
097    
098            /**
099             * Returns the localized string from the localizations XML in the language.
100             * The default language is used if no localization exists for the requested
101             * language.
102             *
103             * @param  xml the localizations XML
104             * @param  requestedLanguageId the ID of the language
105             * @return the localized string
106             */
107            public String getLocalization(String xml, String requestedLanguageId);
108    
109            /**
110             * Returns the localized string from the localizations XML in the language,
111             * optionally using the default language if no localization exists for the
112             * requested language.
113             *
114             * @param  xml the localizations XML
115             * @param  requestedLanguageId the ID of the language
116             * @param  useDefault whether to use the default language if no localization
117             *         exists for the requested language
118             * @return the localized string, or an empty string if
119             *         <code>useDefault</code> is <code>false</code> and no localization
120             *         exists for the requested language
121             */
122            public String getLocalization(
123                    String xml, String requestedLanguageId, boolean useDefault);
124    
125            /**
126             * Returns the localized string from the localizations XML in the language,
127             * optionally using the default language if no localization exists for the
128             * requested language. If no localization exists, the default value is
129             * returned.
130             *
131             * @param  xml the localizations XML
132             * @param  requestedLanguageId the ID of the language
133             * @param  useDefault whether to use the default language if no localization
134             *         exists for the requested language
135             * @param  defaultValue the value returned if no localization exists
136             * @return the localized string, or the <code>defaultValue</code> if
137             *         <code>useDefault</code> is <code>false</code> and no localization
138             *         exists for the requested language
139             */
140            public String getLocalization(
141                    String xml, String requestedLanguageId, boolean useDefault,
142                    String defaultValue);
143    
144            /**
145             * Returns a map of locales and localized strings for the parameter in the
146             * request.
147             *
148             * @param  request the request
149             * @param  parameter the prefix of the parameters containing the localized
150             *         strings. Each localization is loaded from a parameter with this
151             *         prefix, followed by an underscore, and the language ID.
152             * @return the locales and localized strings
153             */
154            public Map<Locale, String> getLocalizationMap(
155                    HttpServletRequest request, String parameter);
156    
157            /**
158             * Returns a map of locales and localized strings for the preference in the
159             * preferences container.
160             *
161             * @param  preferences the preferences container
162             * @param  preferenceName the prefix of the preference containing the
163             *         localized strings. Each localization is loaded from a preference
164             *         with this prefix, followed by an underscore, and the language ID.
165             * @return the locales and localized strings
166             */
167            public Map<Locale, String> getLocalizationMap(
168                    PortletPreferences preferences, String preferenceName);
169    
170            /**
171             * Returns a map of locales and localized strings for the preference in the
172             * preferences container. If no localization exists for the preference in
173             * the default locale, the value of the property is used as the localization
174             * for it.
175             *
176             * @param  preferences the preferences container
177             * @param  preferenceName the prefix of the preference containing the
178             *         localized strings. Each localization is loaded from a preference
179             *         with this prefix, followed by an underscore, and the language ID.
180             * @param  propertyName the name of the property whose value is used as the
181             *         localization for the default locale, if no localization exists
182             *         for it
183             * @return the locales and localized strings
184             */
185            public Map<Locale, String> getLocalizationMap(
186                    PortletPreferences preferences, String preferenceName,
187                    String propertyName);
188    
189            /**
190             * Returns a map of locales and localized strings for the parameter in the
191             * portlet request.
192             *
193             * @param  portletRequest the portlet request
194             * @param  parameter the prefix of the parameters containing the localized
195             *         strings. Each localization is loaded from a parameter with this
196             *         prefix, followed by an underscore, and the language ID.
197             * @return the locales and localized strings
198             */
199            public Map<Locale, String> getLocalizationMap(
200                    PortletRequest portletRequest, String parameter);
201    
202            /**
203             * Returns a map of locales and localized strings from the localizations
204             * XML.
205             *
206             * @param  xml the localizations XML
207             * @return the locales and localized strings
208             */
209            public Map<Locale, String> getLocalizationMap(String xml);
210    
211            public Map<Locale, String> getLocalizationMap(
212                    String xml, boolean useDefault);
213    
214            public Map<Locale, String> getLocalizationMap(
215                    String bundleName, ClassLoader classLoader, String key,
216                    boolean includeBetaLocales);
217    
218            /**
219             * Returns a map of locales and localized strings for the given languageIds
220             * and values.
221             *
222             * @param  languageIds the languageIds of the localized Strings
223             * @param  values the localized strings for the different languageId
224             * @return the map of locales and values for the given parameters
225             */
226            public Map<Locale, String> getLocalizationMap(
227                    String[] languageIds, String[] values);
228    
229            /**
230             * Returns the localizations XML for the parameter from the portlet request,
231             * attempting to get data from the preferences container if it is not
232             * available in the portlet request.
233             *
234             * @param  preferences the preferences container
235             * @param  portletRequest the portlet request
236             * @param  parameter the prefix of the parameters containing the localized
237             *         strings. Each localization is loaded from a parameter with this
238             *         prefix, followed by an underscore, and the language ID.
239             * @return the locales and localized strings
240             */
241            public String getLocalizationXmlFromPreferences(
242                    PortletPreferences preferences, PortletRequest portletRequest,
243                    String parameter);
244    
245            /**
246             * Returns the localizations XML for the parameter from the portlet request,
247             * attempting to get data from the preferences container if it is not
248             * available in the portlet request. If no localization exists in the
249             * default locale, the default value is used as the localization for it.
250             *
251             * @param  preferences the preferences container
252             * @param  portletRequest the portlet request
253             * @param  parameter the prefix of the parameters containing the localized
254             *         strings. Each localization is loaded from a parameter with this
255             *         prefix, followed by an underscore, and the language ID.
256             * @param  defaultValue the value used as the localization for the default
257             *         locale, if no localization exists for it
258             * @return the locales and localized strings
259             */
260            public String getLocalizationXmlFromPreferences(
261                    PortletPreferences preferences, PortletRequest portletRequest,
262                    String parameter, String defaultValue);
263    
264            /**
265             * Returns the localizations XML for the prefixed parameter from the portlet
266             * request, attempting to get data from the preferences container if it is
267             * not available in the portlet request. If no localization exists for the
268             * the default locale, the default value is used as the localization for it.
269             *
270             * @param  preferences the preferences container
271             * @param  portletRequest the portlet request
272             * @param  parameter the prefix of the parameters containing the localized
273             *         strings. Each localization is loaded from a parameter with this
274             *         prefix, followed by an underscore, and the language ID.
275             * @param  prefix the value used in the request to prefix the parameter name
276             * @param  defaultValue the value used as the localization for the default
277             *         locale, if no localization exists for it
278             * @return the locales and localized strings, or the
279             *         <code>defaultValue</code> if no localization exists
280             */
281            public String getLocalizationXmlFromPreferences(
282                    PortletPreferences preferences, PortletRequest portletRequest,
283                    String parameter, String prefix, String defaultValue);
284    
285            /**
286             * Returns the localized name in the language. The localized name is the
287             * name, followed by an underscore, and the language ID.
288             *
289             * @param  name the name to be localized
290             * @param  languageId the ID of the language
291             * @return the localized name for the language
292             */
293            public String getLocalizedName(String name, String languageId);
294    
295            /**
296             * @deprecated As of 6.2.0, replaced by {@link
297             *             #getLocalizationMap(PortletRequest, String)}
298             */
299            @Deprecated
300            public Map<Locale, String> getLocalizedParameter(
301                    PortletRequest portletRequest, String parameter);
302    
303            /**
304             * Returns the localized preferences key in the language. Generally this is
305             * just the preferences key, followed by an underscore, and the language ID.
306             *
307             * @param  key the preferences key
308             * @param  languageId the ID of the language
309             * @return the localized preferences key
310             */
311            public String getPreferencesKey(String key, String languageId);
312    
313            /**
314             * Returns the localized preferences value for the key in the language. The
315             * default language is used if no localization exists for the requested
316             * language.
317             *
318             * @param  preferences the preferences container
319             * @param  key the preferences key
320             * @param  languageId the ID of the language
321             * @return the localized preferences value
322             */
323            public String getPreferencesValue(
324                    PortletPreferences preferences, String key, String languageId);
325    
326            /**
327             * Returns the localized preferences value for the key in the language,
328             * optionally using the default language if no localization exists for the
329             * requested language.
330             *
331             * @param  preferences the preferences container
332             * @param  key the preferences key
333             * @param  languageId the ID of the language
334             * @param  useDefault whether to use the default language if no localization
335             *         exists for the requested language
336             * @return the localized preferences value, or an empty string if
337             *         <code>useDefault</code> is <code>false</code> and no localization
338             *         exists for the requested language
339             */
340            public String getPreferencesValue(
341                    PortletPreferences preferences, String key, String languageId,
342                    boolean useDefault);
343    
344            /**
345             * Returns the localized preferences values for the key in the language. The
346             * default language is used if no localization exists for the requested
347             * language.
348             *
349             * @param  preferences the preferences container
350             * @param  key the preferences key
351             * @param  languageId the ID of the language
352             * @return the localized preferences values
353             */
354            public String[] getPreferencesValues(
355                    PortletPreferences preferences, String key, String languageId);
356    
357            /**
358             * Returns the localized preferences values for the key in the language,
359             * optionally using the default language if no localization exists for the
360             * requested language.
361             *
362             * @param  preferences the preferences container
363             * @param  key the preferences key
364             * @param  languageId the ID of the language
365             * @param  useDefault whether to use the default language if no localization
366             *         exists for the requested language
367             * @return the localized preferences values, or an empty string if
368             *         <code>useDefault</code> is <code>false</code> and no localization
369             *         exists for the requested language
370             */
371            public String[] getPreferencesValues(
372                    PortletPreferences preferences, String key, String languageId,
373                    boolean useDefault);
374    
375            /**
376             * Returns the localized settings value for the key in the language. The
377             * default language is used if no localization exists for the requested
378             * language.
379             *
380             * @param  settings the settings
381             * @param  key the settings key
382             * @param  languageId the ID of the language
383             * @return the localized settings value
384             */
385            public String getSettingsValue(
386                    Settings settings, String key, String languageId);
387    
388            /**
389             * Returns the localized settings value for the key in the language,
390             * optionally using the default language if no localization exists for the
391             * requested language.
392             *
393             * @param  settings the settings
394             * @param  key the settings key
395             * @param  languageId the ID of the language
396             * @param  useDefault whether to use the default language if no localization
397             *         exists for the requested language
398             * @return the localized settings value. If <code>useDefault</code> is
399             *         <code>false</code> and no localization exists for the requested
400             *         language, an empty string is returned.
401             */
402            public String getSettingsValue(
403                    Settings settings, String key, String languageId, boolean useDefault);
404    
405            /**
406             * Returns the localized settings values for the key in the language. The
407             * default language is used if no localization exists for the requested
408             * language.
409             *
410             * @param  settings the settings
411             * @param  key the settings key
412             * @param  languageId the ID of the language
413             * @return the localized settings values
414             */
415            public String[] getSettingsValues(
416                    Settings settings, String key, String languageId);
417    
418            /**
419             * Returns the localized settings values for the key in the language,
420             * optionally using the default language if no localization exists for the
421             * requested language.
422             *
423             * @param  settings the settings
424             * @param  key the settings key
425             * @param  languageId the ID of the language
426             * @param  useDefault whether to use the default language if no localization
427             *         exists for the requested language
428             * @return the localized settings values. If <code>useDefault</code> is
429             *         <code>false</code> and no localization exists for the requested
430             *         language, an empty array is returned.
431             */
432            public String[] getSettingsValues(
433                    Settings settings, String key, String languageId, boolean useDefault);
434    
435            /**
436             * Removes the localization for the language from the localizations XML. The
437             * localized strings are stored as characters in the XML.
438             *
439             * @param  xml the localizations XML
440             * @param  key the name of the localized string, such as &quot;Title&quot;
441             * @param  requestedLanguageId the ID of the language
442             * @return the localizations XML with the language removed
443             */
444            public String removeLocalization(
445                    String xml, String key, String requestedLanguageId);
446    
447            /**
448             * Removes the localization for the language from the localizations XML,
449             * optionally storing the localized strings as CDATA in the XML.
450             *
451             * @param  xml the localizations XML
452             * @param  key the name of the localized string, such as &quot;Title&quot;
453             * @param  requestedLanguageId the ID of the language
454             * @param  cdata whether to store localized strings as CDATA in the XML
455             * @return the localizations XML with the language removed
456             */
457            public String removeLocalization(
458                    String xml, String key, String requestedLanguageId, boolean cdata);
459    
460            /**
461             * Removes the localization for the language from the localizations XML,
462             * optionally storing the localized strings as CDATA in the XML.
463             *
464             * @param  xml the localizations XML
465             * @param  key the name of the localized string, such as &quot;Title&quot;
466             * @param  requestedLanguageId the ID of the language
467             * @param  cdata whether to store localized strings as CDATA in the XML
468             * @param  localized whether there is a localized field
469             * @return the localizations XML with the language removed
470             */
471            public String removeLocalization(
472                    String xml, String key, String requestedLanguageId, boolean cdata,
473                    boolean localized);
474    
475            /**
476             * Sets the localized preferences values for the parameter in the portlet
477             * request.
478             *
479             * @param  portletRequest the portlet request
480             * @param  preferences the preferences container
481             * @param  parameter the prefix of the parameters containing the localized
482             *         strings. Each localization is loaded from a parameter with this
483             *         prefix, followed by an underscore, and the language ID.
484             * @throws Exception if an exception occurred
485             */
486            public void setLocalizedPreferencesValues(
487                            PortletRequest portletRequest, PortletPreferences preferences,
488                            String parameter)
489                    throws Exception;
490    
491            /**
492             * Sets the localized preferences value for the key in the language.
493             *
494             * @param  preferences the preferences container
495             * @param  key the preferences key
496             * @param  languageId the ID of the language
497             * @param  value the localized value
498             * @throws Exception if an exception occurred
499             */
500            public void setPreferencesValue(
501                            PortletPreferences preferences, String key, String languageId,
502                            String value)
503                    throws Exception;
504    
505            /**
506             * Sets the localized preferences values for the key in the language.
507             *
508             * @param  preferences the preferences container
509             * @param  key the preferences key
510             * @param  languageId the ID of the language
511             * @param  values the localized values
512             * @throws Exception if an exception occurred
513             */
514            public void setPreferencesValues(
515                            PortletPreferences preferences, String key, String languageId,
516                            String[] values)
517                    throws Exception;
518    
519            /**
520             * Updates the localized string for all the available languages in the
521             * localizations XML for the map of locales and localized strings and
522             * changes the default language. The localized strings are stored as
523             * characters in the XML.
524             *
525             * @param  localizationMap the locales and localized strings
526             * @param  xml the localizations XML
527             * @param  key the name of the localized string, such as &quot;Title&quot;
528             * @param  defaultLanguageId the ID of the default language
529             * @return the updated localizations XML
530             */
531            public String updateLocalization(
532                    Map<Locale, String> localizationMap, String xml, String key,
533                    String defaultLanguageId);
534    
535            /**
536             * Updates the localized string for the system default language in the
537             * localizations XML. The localized strings are stored as characters in the
538             * XML.
539             *
540             * @param  xml the localizations XML
541             * @param  key the name of the localized string, such as &quot;Title&quot;
542             * @param  value the localized string
543             * @return the updated localizations XML
544             */
545            public String updateLocalization(String xml, String key, String value);
546    
547            /**
548             * Updates the localized string for the language in the localizations XML.
549             * The localized strings are stored as characters in the XML.
550             *
551             * @param  xml the localizations XML
552             * @param  key the name of the localized string, such as &quot;Title&quot;
553             * @param  value the localized string
554             * @param  requestedLanguageId the ID of the language
555             * @return the updated localizations XML
556             */
557            public String updateLocalization(
558                    String xml, String key, String value, String requestedLanguageId);
559    
560            /**
561             * Updates the localized string for the language in the localizations XML
562             * and changes the default language. The localized strings are stored as
563             * characters in the XML.
564             *
565             * @param  xml the localizations XML
566             * @param  key the name of the localized string, such as &quot;Title&quot;
567             * @param  value the localized string
568             * @param  requestedLanguageId the ID of the language
569             * @param  defaultLanguageId the ID of the default language
570             * @return the updated localizations XML
571             */
572            public String updateLocalization(
573                    String xml, String key, String value, String requestedLanguageId,
574                    String defaultLanguageId);
575    
576            /**
577             * Updates the localized string for the language in the localizations XML
578             * and changes the default language, optionally storing the localized
579             * strings as CDATA in the XML.
580             *
581             * @param  xml the localizations XML
582             * @param  key the name of the localized string, such as &quot;Title&quot;
583             * @param  value the localized string
584             * @param  requestedLanguageId the ID of the language
585             * @param  defaultLanguageId the ID of the default language
586             * @param  cdata whether to store localized strings as CDATA in the XML
587             * @return the updated localizations XML
588             */
589            public String updateLocalization(
590                    String xml, String key, String value, String requestedLanguageId,
591                    String defaultLanguageId, boolean cdata);
592    
593            /**
594             * Updates the localized string for the language in the localizations XML
595             * and changes the default language, optionally storing the localized
596             * strings as CDATA in the XML.
597             *
598             * @param  xml the localizations XML
599             * @param  key the name of the localized string, such as &quot;Title&quot;
600             * @param  value the localized string
601             * @param  requestedLanguageId the ID of the language
602             * @param  defaultLanguageId the ID of the default language
603             * @param  cdata whether to store localized strings as CDATA in the XML
604             * @param  localized whether there is a localized field
605             * @return the updated localizations XML
606             */
607            public String updateLocalization(
608                    String xml, String key, String value, String requestedLanguageId,
609                    String defaultLanguageId, boolean cdata, boolean localized);
610    
611    }