001    /**
002     * Copyright (c) 2000-2013 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.xml.Document;
019    
020    import java.util.Locale;
021    import java.util.Map;
022    
023    import javax.portlet.PortletPreferences;
024    import javax.portlet.PortletRequest;
025    
026    import javax.servlet.http.HttpServletRequest;
027    
028    /**
029     * Stores and retrieves localized strings from XML, and provides utility methods
030     * for updating localizations from JSON, portlet requests, and maps. Used for
031     * adding localization to strings, most often for model properties.
032     *
033     * <p>
034     * Localized values are cached in this class rather than in the value object
035     * since value objects get flushed from cache fairly quickly. Though lookups
036     * performed on a key based on an XML file are slower than lookups done at the
037     * value object level in general, the value object will get flushed at a rate
038     * which works against the performance gain. The cache is a soft hash map which
039     * prevents memory leaks within the system while enabling the cache to live
040     * longer than in a weak hash map.
041     * </p>
042     *
043     * @author Alexander Chow
044     * @author Jorge Ferrer
045     * @author Mauro Mariuzzo
046     * @author Julio Camarero
047     * @author Brian Wing Shun Chan
048     */
049    public interface Localization {
050    
051            /**
052             * Deserializes the JSON object into a map of locales and localized strings.
053             *
054             * @param  jsonObject the JSON object
055             * @return the locales and localized strings
056             */
057            public Object deserialize(JSONObject jsonObject);
058    
059            public String[] getAvailableLanguageIds(Document document);
060    
061            /**
062             * Returns the available locales from the localizations XML.
063             *
064             * @param  xml the localizations XML
065             * @return the language IDs of the available locales
066             */
067            public String[] getAvailableLanguageIds(String xml);
068    
069            /**
070             * Returns a valid default locale for importing a localized entity.
071             *
072             * @param  className the class name of the entity
073             * @param  classPK the primary keys of the entity
074             * @param  contentDefaultLocale the default Locale of the entity
075             * @param  contentAvailableLocales the available locales of the entity
076             * @return the valid locale
077             */
078            public Locale getDefaultImportLocale(
079                    String className, long classPK, Locale contentDefaultLocale,
080                    Locale[] contentAvailableLocales);
081    
082            public String getDefaultLanguageId(Document document);
083    
084            public String getDefaultLanguageId(Document document, Locale defaultLocale);
085    
086            /**
087             * Returns the default locale from the localizations XML.
088             *
089             * @param  xml the localizations XML
090             * @return the language ID of the default locale, or the system default
091             *         locale if the default locale cannot be retrieved from the XML
092             */
093            public String getDefaultLanguageId(String xml);
094    
095            public String getDefaultLanguageId(String xml, Locale defaultLocale);
096    
097            /**
098             * Returns the localized string from the localizations XML in the language.
099             * Uses the default language if no localization exists for the requested
100             * language.
101             *
102             * @param  xml the localizations XML
103             * @param  requestedLanguageId the ID of the language
104             * @return the localized string
105             */
106            public String getLocalization(String xml, String requestedLanguageId);
107    
108            /**
109             * Returns the localized string from the localizations XML in the language,
110             * optionally using the default language if the no localization exists for
111             * the requested language.
112             *
113             * @param  xml the localizations XML
114             * @param  requestedLanguageId the ID of the language
115             * @param  useDefault whether to use the default language if no localization
116             *         exists for the requested language
117             * @return the localized string. If <code>useDefault</code> is
118             *         <code>false</code> and no localization exists for the requested
119             *         language, an empty string will be returned.
120             */
121            public String getLocalization(
122                    String xml, String requestedLanguageId, boolean useDefault);
123    
124            /**
125             * Returns a map of locales and localized strings for the parameter in the
126             * request.
127             *
128             * @param  request the request
129             * @param  parameter the prefix of the parameters containing the localized
130             *         strings. Each localization will be loaded from a parameter with
131             *         this prefix, followed by an underscore, and the language ID.
132             * @return the locales and localized strings
133             */
134            public Map<Locale, String> getLocalizationMap(
135                    HttpServletRequest request, String parameter);
136    
137            /**
138             * Returns a map of locales and localized strings for the parameter in the
139             * preferences container.
140             *
141             * @param  preferences the preferences container
142             * @param  parameter the prefix of the parameters containing the localized
143             *         strings. Each localization will be loaded from a parameter with
144             *         this prefix, followed by an underscore, and the language ID.
145             * @return the locales and localized strings
146             */
147            public Map<Locale, String> getLocalizationMap(
148                    PortletPreferences preferences, String parameter);
149    
150            /**
151             * Returns a map of locales and localized strings for the parameter in the
152             * portlet request.
153             *
154             * @param  portletRequest the portlet request
155             * @param  parameter the prefix of the parameters containing the localized
156             *         strings. Each localization will be loaded from a parameter with
157             *         this prefix, followed by an underscore, and the language ID.
158             * @return the locales and localized strings
159             */
160            public Map<Locale, String> getLocalizationMap(
161                    PortletRequest portletRequest, String parameter);
162    
163            /**
164             * Returns a map of locales and localized strings from the localizations
165             * XML.
166             *
167             * @param  xml the localizations XML
168             * @return the locales and localized strings
169             */
170            public Map<Locale, String> getLocalizationMap(String xml);
171    
172            public Map<Locale, String> getLocalizationMap(
173                    String xml, boolean useDefault);
174    
175            public Map<Locale, String> getLocalizationMap(
176                    String bundleName, ClassLoader classLoader, String key,
177                    boolean includeBetaLocales);
178    
179            /**
180             * Returns a map of locales and localized strings for the given languageIds
181             * and values.
182             *
183             * @param  languageIds the languageIds of the localized Strings
184             * @param  values the localized strings for the different languageId
185             * @return the map of locales and values for the given parameters
186             */
187            public Map<Locale, String> getLocalizationMap(
188                    String[] languageIds, String[] values);
189    
190            /**
191             * Returns the localizations XML for the parameter in the portlet request,
192             * attempting to get data from the preferences container when it is not
193             * available in the portlet request.
194             *
195             * @param  preferences the preferences container
196             * @param  portletRequest the portlet request
197             * @param  parameter the prefix of the parameters containing the localized
198             *         strings. Each localization will be loaded from a parameter with
199             *         this prefix, followed by an underscore, and the language ID.
200             * @return the locales and localized strings
201             */
202            public String getLocalizationXmlFromPreferences(
203                    PortletPreferences preferences, PortletRequest portletRequest,
204                    String parameter);
205    
206            /**
207             * @deprecated As of 6.2.0, replaced by {@link
208             *             #getLocalizationMap(PortletRequest, String)}
209             */
210            public Map<Locale, String> getLocalizedParameter(
211                    PortletRequest portletRequest, String parameter);
212    
213            /**
214             * Returns the localized preferences key in the language. Generally this is
215             * just the preferences key, followed by an underscore, and the language ID.
216             *
217             * @param  key the preferences key
218             * @param  languageId the ID of the language
219             * @return the localized preferences key
220             */
221            public String getPreferencesKey(String key, String languageId);
222    
223            /**
224             * Returns the localized preferences value for the key in the language. Uses
225             * the default language if no localization exists for the requested
226             * language.
227             *
228             * @param  preferences the preferences container
229             * @param  key the preferences key
230             * @param  languageId the ID of the language
231             * @return the localized preferences value
232             */
233            public String getPreferencesValue(
234                    PortletPreferences preferences, String key, String languageId);
235    
236            /**
237             * Returns the localized preferences value for the key in the language,
238             * optionally using the default language if the no localization exists for
239             * the requested language.
240             *
241             * @param  preferences the preferences container
242             * @param  key the preferences key
243             * @param  languageId the ID of the language
244             * @param  useDefault whether to use the default language if no localization
245             *         exists for the requested language
246             * @return the localized preferences value. If <code>useDefault</code> is
247             *         <code>false</code> and no localization exists for the requested
248             *         language, an empty string will be returned.
249             */
250            public String getPreferencesValue(
251                    PortletPreferences preferences, String key, String languageId,
252                    boolean useDefault);
253    
254            /**
255             * Returns the localized preferences values for the key in the language.
256             * Uses the default language if no localization exists for the requested
257             * language.
258             *
259             * @param  preferences the preferences container
260             * @param  key the preferences key
261             * @param  languageId the ID of the language
262             * @return the localized preferences values
263             */
264            public String[] getPreferencesValues(
265                    PortletPreferences preferences, String key, String languageId);
266    
267            /**
268             * Returns the localized preferences values for the key in the language,
269             * optionally using the default language if the no localization exists for
270             * the requested language.
271             *
272             * @param  preferences the preferences container
273             * @param  key the preferences key
274             * @param  languageId the ID of the language
275             * @param  useDefault whether to use the default language if no localization
276             *         exists for the requested language
277             * @return the localized preferences values. If <code>useDefault</code> is
278             *         <code>false</code> and no localization exists for the requested
279             *         language, an empty array will be returned.
280             */
281            public String[] getPreferencesValues(
282                    PortletPreferences preferences, String key, String languageId,
283                    boolean useDefault);
284    
285            /**
286             * Removes the localization for the language from the localizations XML.
287             * Stores the localized strings as characters in the XML.
288             *
289             * @param  xml the localizations XML
290             * @param  key the name of the localized string, such as &quot;Title&quot;
291             * @param  requestedLanguageId the ID of the language
292             * @return the localizations XML with the language removed
293             */
294            public String removeLocalization(
295                    String xml, String key, String requestedLanguageId);
296    
297            /**
298             * Removes the localization for the language from the localizations XML,
299             * optionally storing the localized strings as CDATA in the XML.
300             *
301             * @param  xml the localizations XML
302             * @param  key the name of the localized string, such as &quot;Title&quot;
303             * @param  requestedLanguageId the ID of the language
304             * @param  cdata whether to store localized strings as CDATA in the XML
305             * @return the localizations XML with the language removed
306             */
307            public String removeLocalization(
308                    String xml, String key, String requestedLanguageId, boolean cdata);
309    
310            /**
311             * Removes the localization for the language from the localizations XML,
312             * optionally storing the localized strings as CDATA in the XML.
313             *
314             * @param  xml the localizations XML
315             * @param  key the name of the localized string, such as &quot;Title&quot;
316             * @param  requestedLanguageId the ID of the language
317             * @param  cdata whether to store localized strings as CDATA in the XML
318             * @param  localized whether there is a localized field
319             * @return the localizations XML with the language removed
320             */
321            public String removeLocalization(
322                    String xml, String key, String requestedLanguageId, boolean cdata,
323                    boolean localized);
324    
325            /**
326             * Sets the localized preferences values for the parameter in the portlet
327             * request.
328             *
329             * @param  portletRequest the portlet request
330             * @param  preferences the preferences container
331             * @param  parameter the prefix of the parameters containing the localized
332             *         strings. Each localization will be loaded from a parameter with
333             *         this prefix, followed by an underscore, and the language ID.
334             * @throws Exception if an exception occurred
335             */
336            public void setLocalizedPreferencesValues(
337                            PortletRequest portletRequest, PortletPreferences preferences,
338                            String parameter)
339                    throws Exception;
340    
341            /**
342             * Sets the localized preferences value for the key in the language.
343             *
344             * @param  preferences the preferences container
345             * @param  key the preferences key
346             * @param  languageId the ID of the language
347             * @param  value the localized value
348             * @throws Exception if an exception occurred
349             */
350            public void setPreferencesValue(
351                            PortletPreferences preferences, String key, String languageId,
352                            String value)
353                    throws Exception;
354    
355            /**
356             * Sets the localized preferences values for the key in the language.
357             *
358             * @param  preferences the preferences container
359             * @param  key the preferences key
360             * @param  languageId the ID of the language
361             * @param  values the localized values
362             * @throws Exception if an exception occurred
363             */
364            public void setPreferencesValues(
365                            PortletPreferences preferences, String key, String languageId,
366                            String[] values)
367                    throws Exception;
368    
369            /**
370             * Updates the localized string for all the available languages in the
371             * localizations XML for the map of locales and localized strings and
372             * changes the default language. Stores the localized strings as characters
373             * in the XML.
374             *
375             * @param  localizationMap the locales and localized strings
376             * @param  xml the localizations XML
377             * @param  key the name of the localized string, such as &quot;Title&quot;
378             * @param  defaultLanguageId the ID of the default language
379             * @return the updated localizations XML
380             */
381            public String updateLocalization(
382                    Map<Locale, String> localizationMap, String xml, String key,
383                    String defaultLanguageId);
384    
385            /**
386             * Updates the localized string for the system default language in the
387             * localizations XML. Stores the localized strings as characters in the XML.
388             *
389             * @param  xml the localizations XML
390             * @param  key the name of the localized string, such as &quot;Title&quot;
391             * @param  value the localized string
392             * @return the updated localizations XML
393             */
394            public String updateLocalization(String xml, String key, String value);
395    
396            /**
397             * Updates the localized string for the language in the localizations XML.
398             * Stores the localized strings as characters in the XML.
399             *
400             * @param  xml the localizations XML
401             * @param  key the name of the localized string, such as &quot;Title&quot;
402             * @param  value the localized string
403             * @param  requestedLanguageId the ID of the language
404             * @return the updated localizations XML
405             */
406            public String updateLocalization(
407                    String xml, String key, String value, String requestedLanguageId);
408    
409            /**
410             * Updates the localized string for the language in the localizations XML
411             * and changes the default language. Stores the localized strings as
412             * characters in the XML.
413             *
414             * @param  xml the localizations XML
415             * @param  key the name of the localized string, such as &quot;Title&quot;
416             * @param  value the localized string
417             * @param  requestedLanguageId the ID of the language
418             * @param  defaultLanguageId the ID of the default language
419             * @return the updated localizations XML
420             */
421            public String updateLocalization(
422                    String xml, String key, String value, String requestedLanguageId,
423                    String defaultLanguageId);
424    
425            /**
426             * Updates the localized string for the language in the localizations XML
427             * and changes the default language, optionally storing the localized
428             * strings as CDATA in the XML.
429             *
430             * @param  xml the localizations XML
431             * @param  key the name of the localized string, such as &quot;Title&quot;
432             * @param  value the localized string
433             * @param  requestedLanguageId the ID of the language
434             * @param  defaultLanguageId the ID of the default language
435             * @param  cdata whether to store localized strings as CDATA in the XML
436             * @return the updated localizations XML
437             */
438            public String updateLocalization(
439                    String xml, String key, String value, String requestedLanguageId,
440                    String defaultLanguageId, boolean cdata);
441    
442            /**
443             * Updates the localized string for the language in the localizations XML
444             * and changes the default language, optionally storing the localized
445             * strings as CDATA in the XML.
446             *
447             * @param  xml the localizations XML
448             * @param  key the name of the localized string, such as &quot;Title&quot;
449             * @param  value the localized string
450             * @param  requestedLanguageId the ID of the language
451             * @param  defaultLanguageId the ID of the default language
452             * @param  cdata whether to store localized strings as CDATA in the XML
453             * @param  localized whether there is a localized field
454             * @return the updated localizations XML
455             */
456            public String updateLocalization(
457                    String xml, String key, String value, String requestedLanguageId,
458                    String defaultLanguageId, boolean cdata, boolean localized);
459    
460    }