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            public Map<Locale, String> getLocalizationMap(
191                    PortletPreferences preferences, String preferenceName,
192                    String propertyName, String defaultPropertyValue,
193                    ClassLoader classLoader);
194    
195            /**
196             * Returns a map of locales and localized strings for the parameter in the
197             * portlet request.
198             *
199             * @param  portletRequest the portlet request
200             * @param  parameter the prefix of the parameters containing the localized
201             *         strings. Each localization is loaded from a parameter with this
202             *         prefix, followed by an underscore, and the language ID.
203             * @return the locales and localized strings
204             */
205            public Map<Locale, String> getLocalizationMap(
206                    PortletRequest portletRequest, String parameter);
207    
208            public Map<Locale, String> getLocalizationMap(
209                    PortletRequest portletRequest, String parameter,
210                    Map<Locale, String> defaultValues);
211    
212            /**
213             * Returns a map of locales and localized strings from the localizations
214             * XML.
215             *
216             * @param  xml the localizations XML
217             * @return the locales and localized strings
218             */
219            public Map<Locale, String> getLocalizationMap(String xml);
220    
221            public Map<Locale, String> getLocalizationMap(
222                    String xml, boolean useDefault);
223    
224            public Map<Locale, String> getLocalizationMap(
225                    String bundleName, ClassLoader classLoader, String key,
226                    boolean includeBetaLocales);
227    
228            /**
229             * Returns a map of locales and localized strings for the given languageIds
230             * and values.
231             *
232             * @param  languageIds the languageIds of the localized Strings
233             * @param  values the localized strings for the different languageId
234             * @return the map of locales and values for the given parameters
235             */
236            public Map<Locale, String> getLocalizationMap(
237                    String[] languageIds, String[] values);
238    
239            /**
240             * Returns the localizations XML for the parameter from the portlet request,
241             * attempting to get data from the preferences container if it is not
242             * available in the portlet request.
243             *
244             * @param  preferences the preferences container
245             * @param  portletRequest the portlet request
246             * @param  parameter the prefix of the parameters containing the localized
247             *         strings. Each localization is loaded from a parameter with this
248             *         prefix, followed by an underscore, and the language ID.
249             * @return the locales and localized strings
250             */
251            public String getLocalizationXmlFromPreferences(
252                    PortletPreferences preferences, PortletRequest portletRequest,
253                    String parameter);
254    
255            /**
256             * Returns the localizations XML for the parameter from the portlet request,
257             * attempting to get data from the preferences container if it is not
258             * available in the portlet request. If no localization exists in the
259             * default locale, the default value is used as the localization for it.
260             *
261             * @param  preferences the preferences container
262             * @param  portletRequest the portlet request
263             * @param  parameter the prefix of the parameters containing the localized
264             *         strings. Each localization is loaded from a parameter with this
265             *         prefix, followed by an underscore, and the language ID.
266             * @param  defaultValue the value used as the localization for the default
267             *         locale, if no localization exists for it
268             * @return the locales and localized strings
269             */
270            public String getLocalizationXmlFromPreferences(
271                    PortletPreferences preferences, PortletRequest portletRequest,
272                    String parameter, String defaultValue);
273    
274            /**
275             * Returns the localizations XML for the prefixed parameter from the portlet
276             * request, attempting to get data from the preferences container if it is
277             * not available in the portlet request. If no localization exists for the
278             * the default locale, the default value is used as the localization for it.
279             *
280             * @param  preferences the preferences container
281             * @param  portletRequest the portlet request
282             * @param  parameter the prefix of the parameters containing the localized
283             *         strings. Each localization is loaded from a parameter with this
284             *         prefix, followed by an underscore, and the language ID.
285             * @param  prefix the value used in the request to prefix the parameter name
286             * @param  defaultValue the value used as the localization for the default
287             *         locale, if no localization exists for it
288             * @return the locales and localized strings, or the
289             *         <code>defaultValue</code> if no localization exists
290             */
291            public String getLocalizationXmlFromPreferences(
292                    PortletPreferences preferences, PortletRequest portletRequest,
293                    String parameter, String prefix, String defaultValue);
294    
295            /**
296             * Returns the localized name in the language. The localized name is the
297             * name, followed by an underscore, and the language ID.
298             *
299             * @param  name the name to be localized
300             * @param  languageId the ID of the language
301             * @return the localized name for the language
302             */
303            public String getLocalizedName(String name, String languageId);
304    
305            /**
306             * @deprecated As of 6.2.0, replaced by {@link
307             *             #getLocalizationMap(PortletRequest, String)}
308             */
309            @Deprecated
310            public Map<Locale, String> getLocalizedParameter(
311                    PortletRequest portletRequest, String parameter);
312    
313            public Map<Locale, String> getMap(LocalizedValuesMap localizedValuesMap);
314    
315            /**
316             * Returns the localized preferences key in the language. Generally this is
317             * just the preferences key, followed by an underscore, and the language ID.
318             *
319             * @param      key the preferences key
320             * @param      languageId the ID of the language
321             * @return     the localized preferences key
322             * @deprecated As of 7.0.0, replaced by {@link #getLocalizedName(String,
323             *             String)}
324             */
325            @Deprecated
326            public String getPreferencesKey(String key, String languageId);
327    
328            /**
329             * Returns the localized preferences value for the key in the language. The
330             * default language is used if no localization exists for the requested
331             * language.
332             *
333             * @param  preferences the preferences container
334             * @param  key the preferences key
335             * @param  languageId the ID of the language
336             * @return the localized preferences value
337             */
338            public String getPreferencesValue(
339                    PortletPreferences preferences, String key, String languageId);
340    
341            /**
342             * Returns the localized preferences value for the key in the language,
343             * optionally using the default language if no localization exists for the
344             * requested language.
345             *
346             * @param  preferences the preferences container
347             * @param  key the preferences key
348             * @param  languageId the ID of the language
349             * @param  useDefault whether to use the default language if no localization
350             *         exists for the requested language
351             * @return the localized preferences value, or an empty string if
352             *         <code>useDefault</code> is <code>false</code> and no localization
353             *         exists for the requested language
354             */
355            public String getPreferencesValue(
356                    PortletPreferences preferences, String key, String languageId,
357                    boolean useDefault);
358    
359            /**
360             * Returns the localized preferences values for the key in the language. The
361             * default language is used if no localization exists for the requested
362             * language.
363             *
364             * @param  preferences the preferences container
365             * @param  key the preferences key
366             * @param  languageId the ID of the language
367             * @return the localized preferences values
368             */
369            public String[] getPreferencesValues(
370                    PortletPreferences preferences, String key, String languageId);
371    
372            /**
373             * Returns the localized preferences values for the key in the language,
374             * optionally using the default language if no localization exists for the
375             * requested language.
376             *
377             * @param  preferences the preferences container
378             * @param  key the preferences key
379             * @param  languageId the ID of the language
380             * @param  useDefault whether to use the default language if no localization
381             *         exists for the requested language
382             * @return the localized preferences values, or an empty string if
383             *         <code>useDefault</code> is <code>false</code> and no localization
384             *         exists for the requested language
385             */
386            public String[] getPreferencesValues(
387                    PortletPreferences preferences, String key, String languageId,
388                    boolean useDefault);
389    
390            /**
391             * Returns the localized settings value for the key in the language. The
392             * default language is used if no localization exists for the requested
393             * language.
394             *
395             * @param  settings the settings
396             * @param  key the settings key
397             * @param  languageId the ID of the language
398             * @return the localized settings value
399             */
400            public String getSettingsValue(
401                    Settings settings, String key, String languageId);
402    
403            /**
404             * Returns the localized settings value for the key in the language,
405             * optionally using the default language if no localization exists for the
406             * requested language.
407             *
408             * @param  settings the settings
409             * @param  key the settings key
410             * @param  languageId the ID of the language
411             * @param  useDefault whether to use the default language if no localization
412             *         exists for the requested language
413             * @return the localized settings value. If <code>useDefault</code> is
414             *         <code>false</code> and no localization exists for the requested
415             *         language, an empty string is returned.
416             */
417            public String getSettingsValue(
418                    Settings settings, String key, String languageId, boolean useDefault);
419    
420            /**
421             * Returns the localized settings values for the key in the language. The
422             * default language is used if no localization exists for the requested
423             * language.
424             *
425             * @param  settings the settings
426             * @param  key the settings key
427             * @param  languageId the ID of the language
428             * @return the localized settings values
429             */
430            public String[] getSettingsValues(
431                    Settings settings, String key, String languageId);
432    
433            /**
434             * Returns the localized settings values for the key in the language,
435             * optionally using the default language if no localization exists for the
436             * requested language.
437             *
438             * @param  settings the settings
439             * @param  key the settings key
440             * @param  languageId the ID of the language
441             * @param  useDefault whether to use the default language if no localization
442             *         exists for the requested language
443             * @return the localized settings values. If <code>useDefault</code> is
444             *         <code>false</code> and no localization exists for the requested
445             *         language, an empty array is returned.
446             */
447            public String[] getSettingsValues(
448                    Settings settings, String key, String languageId, boolean useDefault);
449    
450            public String getXml(LocalizedValuesMap localizedValuesMap, String key);
451    
452            /**
453             * Removes the localization for the language from the localizations XML. The
454             * localized strings are stored as characters in the XML.
455             *
456             * @param  xml the localizations XML
457             * @param  key the name of the localized string, such as &quot;Title&quot;
458             * @param  requestedLanguageId the ID of the language
459             * @return the localizations XML with the language removed
460             */
461            public String removeLocalization(
462                    String xml, String key, String requestedLanguageId);
463    
464            /**
465             * Removes the localization for the language from the localizations XML,
466             * optionally storing the localized strings as CDATA in the XML.
467             *
468             * @param  xml the localizations XML
469             * @param  key the name of the localized string, such as &quot;Title&quot;
470             * @param  requestedLanguageId the ID of the language
471             * @param  cdata whether to store localized strings as CDATA in the XML
472             * @return the localizations XML with the language removed
473             */
474            public String removeLocalization(
475                    String xml, String key, String requestedLanguageId, boolean cdata);
476    
477            /**
478             * Removes the localization for the language from the localizations XML,
479             * optionally storing the localized strings as CDATA in the XML.
480             *
481             * @param  xml the localizations XML
482             * @param  key the name of the localized string, such as &quot;Title&quot;
483             * @param  requestedLanguageId the ID of the language
484             * @param  cdata whether to store localized strings as CDATA in the XML
485             * @param  localized whether there is a localized field
486             * @return the localizations XML with the language removed
487             */
488            public String removeLocalization(
489                    String xml, String key, String requestedLanguageId, boolean cdata,
490                    boolean localized);
491    
492            /**
493             * Sets the localized preferences values for the parameter in the portlet
494             * request.
495             *
496             * @param  portletRequest the portlet request
497             * @param  preferences the preferences container
498             * @param  parameter the prefix of the parameters containing the localized
499             *         strings. Each localization is loaded from a parameter with this
500             *         prefix, followed by an underscore, and the language ID.
501             * @throws Exception if an exception occurred
502             */
503            public void setLocalizedPreferencesValues(
504                            PortletRequest portletRequest, PortletPreferences preferences,
505                            String parameter)
506                    throws Exception;
507    
508            /**
509             * Sets the localized preferences value for the key in the language.
510             *
511             * @param  preferences the preferences container
512             * @param  key the preferences key
513             * @param  languageId the ID of the language
514             * @param  value the localized value
515             * @throws Exception if an exception occurred
516             */
517            public void setPreferencesValue(
518                            PortletPreferences preferences, String key, String languageId,
519                            String value)
520                    throws Exception;
521    
522            /**
523             * Sets the localized preferences values for the key in the language.
524             *
525             * @param  preferences the preferences container
526             * @param  key the preferences key
527             * @param  languageId the ID of the language
528             * @param  values the localized values
529             * @throws Exception if an exception occurred
530             */
531            public void setPreferencesValues(
532                            PortletPreferences preferences, String key, String languageId,
533                            String[] values)
534                    throws Exception;
535    
536            /**
537             * Updates the localized string for all the available languages in the
538             * localizations XML for the map of locales and localized strings and
539             * changes the default language. The localized strings are stored as
540             * characters in the XML.
541             *
542             * @param  localizationMap the locales and localized strings
543             * @param  xml the localizations XML
544             * @param  key the name of the localized string, such as &quot;Title&quot;
545             * @param  defaultLanguageId the ID of the default language
546             * @return the updated localizations XML
547             */
548            public String updateLocalization(
549                    Map<Locale, String> localizationMap, String xml, String key,
550                    String defaultLanguageId);
551    
552            /**
553             * Updates the localized string for the system default language in the
554             * localizations XML. The localized strings are stored as characters in the
555             * XML.
556             *
557             * @param  xml the localizations XML
558             * @param  key the name of the localized string, such as &quot;Title&quot;
559             * @param  value the localized string
560             * @return the updated localizations XML
561             */
562            public String updateLocalization(String xml, String key, String value);
563    
564            /**
565             * Updates the localized string for the language in the localizations XML.
566             * The localized strings are stored as characters in the XML.
567             *
568             * @param  xml the localizations XML
569             * @param  key the name of the localized string, such as &quot;Title&quot;
570             * @param  value the localized string
571             * @param  requestedLanguageId the ID of the language
572             * @return the updated localizations XML
573             */
574            public String updateLocalization(
575                    String xml, String key, String value, String requestedLanguageId);
576    
577            /**
578             * Updates the localized string for the language in the localizations XML
579             * and changes the default language. The localized strings are stored as
580             * characters in the XML.
581             *
582             * @param  xml the localizations XML
583             * @param  key the name of the localized string, such as &quot;Title&quot;
584             * @param  value the localized string
585             * @param  requestedLanguageId the ID of the language
586             * @param  defaultLanguageId the ID of the default language
587             * @return the updated localizations XML
588             */
589            public String updateLocalization(
590                    String xml, String key, String value, String requestedLanguageId,
591                    String defaultLanguageId);
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             * @return the updated localizations XML
605             */
606            public String updateLocalization(
607                    String xml, String key, String value, String requestedLanguageId,
608                    String defaultLanguageId, boolean cdata);
609    
610            /**
611             * Updates the localized string for the language in the localizations XML
612             * and changes the default language, optionally storing the localized
613             * strings as CDATA in the XML.
614             *
615             * @param  xml the localizations XML
616             * @param  key the name of the localized string, such as &quot;Title&quot;
617             * @param  value the localized string
618             * @param  requestedLanguageId the ID of the language
619             * @param  defaultLanguageId the ID of the default language
620             * @param  cdata whether to store localized strings as CDATA in the XML
621             * @param  localized whether there is a localized field
622             * @return the updated localizations XML
623             */
624            public String updateLocalization(
625                    String xml, String key, String value, String requestedLanguageId,
626                    String defaultLanguageId, boolean cdata, boolean localized);
627    
628    }