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            public Map<Locale, String> getMap(LocalizedValuesMap localizedValuesMap);
320    
321            /**
322             * Returns the localized preferences key in the language. Generally this is
323             * just the preferences key, followed by an underscore, and the language ID.
324             *
325             * @param      key the preferences key
326             * @param      languageId the ID of the language
327             * @return     the localized preferences key
328             * @deprecated As of 7.0.0, replaced by {@link #getLocalizedName(String,
329             *             String)}
330             */
331            @Deprecated
332            public String getPreferencesKey(String key, String languageId);
333    
334            /**
335             * Returns the localized preferences value for the key in the language. The
336             * default language is used if no localization exists for the requested
337             * language.
338             *
339             * @param  preferences the preferences container
340             * @param  key the preferences key
341             * @param  languageId the ID of the language
342             * @return the localized preferences value
343             */
344            public String getPreferencesValue(
345                    PortletPreferences preferences, String key, String languageId);
346    
347            /**
348             * Returns the localized preferences value for the key in the language,
349             * optionally using the default language if no localization exists for the
350             * requested language.
351             *
352             * @param  preferences the preferences container
353             * @param  key the preferences key
354             * @param  languageId the ID of the language
355             * @param  useDefault whether to use the default language if no localization
356             *         exists for the requested language
357             * @return the localized preferences value, or an empty string if
358             *         <code>useDefault</code> is <code>false</code> and no localization
359             *         exists for the requested language
360             */
361            public String getPreferencesValue(
362                    PortletPreferences preferences, String key, String languageId,
363                    boolean useDefault);
364    
365            /**
366             * Returns the localized preferences values for the key in the language. The
367             * default language is used if no localization exists for the requested
368             * language.
369             *
370             * @param  preferences the preferences container
371             * @param  key the preferences key
372             * @param  languageId the ID of the language
373             * @return the localized preferences values
374             */
375            public String[] getPreferencesValues(
376                    PortletPreferences preferences, String key, String languageId);
377    
378            /**
379             * Returns the localized preferences values for the key in the language,
380             * optionally using the default language if no localization exists for the
381             * requested language.
382             *
383             * @param  preferences the preferences container
384             * @param  key the preferences key
385             * @param  languageId the ID of the language
386             * @param  useDefault whether to use the default language if no localization
387             *         exists for the requested language
388             * @return the localized preferences values, or an empty string if
389             *         <code>useDefault</code> is <code>false</code> and no localization
390             *         exists for the requested language
391             */
392            public String[] getPreferencesValues(
393                    PortletPreferences preferences, String key, String languageId,
394                    boolean useDefault);
395    
396            /**
397             * Returns the localized settings value for the key in the language. The
398             * default language is used if no localization exists for the requested
399             * language.
400             *
401             * @param  settings the settings
402             * @param  key the settings key
403             * @param  languageId the ID of the language
404             * @return the localized settings value
405             */
406            public String getSettingsValue(
407                    Settings settings, String key, String languageId);
408    
409            /**
410             * Returns the localized settings value for the key in the language,
411             * optionally using the default language if no localization exists for the
412             * requested language.
413             *
414             * @param  settings the settings
415             * @param  key the settings key
416             * @param  languageId the ID of the language
417             * @param  useDefault whether to use the default language if no localization
418             *         exists for the requested language
419             * @return the localized settings value. If <code>useDefault</code> is
420             *         <code>false</code> and no localization exists for the requested
421             *         language, an empty string is returned.
422             */
423            public String getSettingsValue(
424                    Settings settings, String key, String languageId, boolean useDefault);
425    
426            /**
427             * Returns the localized settings values for the key in the language. The
428             * default language is used if no localization exists for the requested
429             * language.
430             *
431             * @param  settings the settings
432             * @param  key the settings key
433             * @param  languageId the ID of the language
434             * @return the localized settings values
435             */
436            public String[] getSettingsValues(
437                    Settings settings, String key, String languageId);
438    
439            /**
440             * Returns the localized settings values for the key in the language,
441             * optionally using the default language if no localization exists for the
442             * requested language.
443             *
444             * @param  settings the settings
445             * @param  key the settings key
446             * @param  languageId the ID of the language
447             * @param  useDefault whether to use the default language if no localization
448             *         exists for the requested language
449             * @return the localized settings values. If <code>useDefault</code> is
450             *         <code>false</code> and no localization exists for the requested
451             *         language, an empty array is returned.
452             */
453            public String[] getSettingsValues(
454                    Settings settings, String key, String languageId, boolean useDefault);
455    
456            public String getXml(LocalizedValuesMap localizedValuesMap, String key);
457    
458            /**
459             * Removes the localization for the language from the localizations XML. The
460             * localized strings are stored as characters in the XML.
461             *
462             * @param  xml the localizations XML
463             * @param  key the name of the localized string, such as &quot;Title&quot;
464             * @param  requestedLanguageId the ID of the language
465             * @return the localizations XML with the language removed
466             */
467            public String removeLocalization(
468                    String xml, String key, String requestedLanguageId);
469    
470            /**
471             * Removes the localization for the language from the localizations XML,
472             * optionally storing the localized strings as CDATA in the XML.
473             *
474             * @param  xml the localizations XML
475             * @param  key the name of the localized string, such as &quot;Title&quot;
476             * @param  requestedLanguageId the ID of the language
477             * @param  cdata whether to store localized strings as CDATA in the XML
478             * @return the localizations XML with the language removed
479             */
480            public String removeLocalization(
481                    String xml, String key, String requestedLanguageId, boolean cdata);
482    
483            /**
484             * Removes the localization for the language from the localizations XML,
485             * optionally storing the localized strings as CDATA in the XML.
486             *
487             * @param  xml the localizations XML
488             * @param  key the name of the localized string, such as &quot;Title&quot;
489             * @param  requestedLanguageId the ID of the language
490             * @param  cdata whether to store localized strings as CDATA in the XML
491             * @param  localized whether there is a localized field
492             * @return the localizations XML with the language removed
493             */
494            public String removeLocalization(
495                    String xml, String key, String requestedLanguageId, boolean cdata,
496                    boolean localized);
497    
498            /**
499             * Sets the localized preferences values for the parameter in the portlet
500             * request.
501             *
502             * @param  portletRequest the portlet request
503             * @param  preferences the preferences container
504             * @param  parameter the prefix of the parameters containing the localized
505             *         strings. Each localization is loaded from a parameter with this
506             *         prefix, followed by an underscore, and the language ID.
507             * @throws Exception if an exception occurred
508             */
509            public void setLocalizedPreferencesValues(
510                            PortletRequest portletRequest, PortletPreferences preferences,
511                            String parameter)
512                    throws Exception;
513    
514            /**
515             * Sets the localized preferences value for the key in the language.
516             *
517             * @param  preferences the preferences container
518             * @param  key the preferences key
519             * @param  languageId the ID of the language
520             * @param  value the localized value
521             * @throws Exception if an exception occurred
522             */
523            public void setPreferencesValue(
524                            PortletPreferences preferences, String key, String languageId,
525                            String value)
526                    throws Exception;
527    
528            /**
529             * Sets the localized preferences values for the key in the language.
530             *
531             * @param  preferences the preferences container
532             * @param  key the preferences key
533             * @param  languageId the ID of the language
534             * @param  values the localized values
535             * @throws Exception if an exception occurred
536             */
537            public void setPreferencesValues(
538                            PortletPreferences preferences, String key, String languageId,
539                            String[] values)
540                    throws Exception;
541    
542            /**
543             * Updates the localized string for all the available languages in the
544             * localizations XML for the map of locales and localized strings and
545             * changes the default language. The localized strings are stored as
546             * characters in the XML.
547             *
548             * @param  localizationMap the locales and localized strings
549             * @param  xml the localizations XML
550             * @param  key the name of the localized string, such as &quot;Title&quot;
551             * @param  defaultLanguageId the ID of the default language
552             * @return the updated localizations XML
553             */
554            public String updateLocalization(
555                    Map<Locale, String> localizationMap, String xml, String key,
556                    String defaultLanguageId);
557    
558            /**
559             * Updates the localized string for the system default language in the
560             * localizations XML. The localized strings are stored as characters in the
561             * XML.
562             *
563             * @param  xml the localizations XML
564             * @param  key the name of the localized string, such as &quot;Title&quot;
565             * @param  value the localized string
566             * @return the updated localizations XML
567             */
568            public String updateLocalization(String xml, String key, String value);
569    
570            /**
571             * Updates the localized string for the language in the localizations XML.
572             * The localized strings are stored as characters in the XML.
573             *
574             * @param  xml the localizations XML
575             * @param  key the name of the localized string, such as &quot;Title&quot;
576             * @param  value the localized string
577             * @param  requestedLanguageId the ID of the language
578             * @return the updated localizations XML
579             */
580            public String updateLocalization(
581                    String xml, String key, String value, String requestedLanguageId);
582    
583            /**
584             * Updates the localized string for the language in the localizations XML
585             * and changes the default language. The localized strings are stored as
586             * characters 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             * @return the updated localizations XML
594             */
595            public String updateLocalization(
596                    String xml, String key, String value, String requestedLanguageId,
597                    String defaultLanguageId);
598    
599            /**
600             * Updates the localized string for the language in the localizations XML
601             * and changes the default language, optionally storing the localized
602             * strings as CDATA in the XML.
603             *
604             * @param  xml the localizations XML
605             * @param  key the name of the localized string, such as &quot;Title&quot;
606             * @param  value the localized string
607             * @param  requestedLanguageId the ID of the language
608             * @param  defaultLanguageId the ID of the default language
609             * @param  cdata whether to store localized strings as CDATA in the XML
610             * @return the updated localizations XML
611             */
612            public String updateLocalization(
613                    String xml, String key, String value, String requestedLanguageId,
614                    String defaultLanguageId, boolean cdata);
615    
616            /**
617             * Updates the localized string for the language in the localizations XML
618             * and changes the default language, optionally storing the localized
619             * strings as CDATA in the XML.
620             *
621             * @param  xml the localizations XML
622             * @param  key the name of the localized string, such as &quot;Title&quot;
623             * @param  value the localized string
624             * @param  requestedLanguageId the ID of the language
625             * @param  defaultLanguageId the ID of the default language
626             * @param  cdata whether to store localized strings as CDATA in the XML
627             * @param  localized whether there is a localized field
628             * @return the updated localizations XML
629             */
630            public String updateLocalization(
631                    String xml, String key, String value, String requestedLanguageId,
632                    String defaultLanguageId, boolean cdata, boolean localized);
633    
634    }