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