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