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