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            /**
085             * Returns the default locale from the localizations XML.
086             *
087             * @param  xml the localizations XML
088             * @return the language ID of the default locale, or the system default
089             *         locale if the default locale cannot be retrieved from the XML
090             */
091            public String getDefaultLanguageId(String xml);
092    
093            /**
094             * Returns the localized string from the localizations XML in the language.
095             * Uses the default language if no localization exists for the requested
096             * language.
097             *
098             * @param  xml the localizations XML
099             * @param  requestedLanguageId the ID of the language
100             * @return the localized string
101             */
102            public String getLocalization(String xml, String requestedLanguageId);
103    
104            /**
105             * Returns the localized string from the localizations XML in the language,
106             * optionally using the default language if the no localization exists for
107             * the requested language.
108             *
109             * @param  xml the localizations XML
110             * @param  requestedLanguageId the ID of the language
111             * @param  useDefault whether to use the default language if no localization
112             *         exists for the requested language
113             * @return the localized string. If <code>useDefault</code> is
114             *         <code>false</code> and no localization exists for the requested
115             *         language, an empty string will be returned.
116             */
117            public String getLocalization(
118                    String xml, String requestedLanguageId, boolean useDefault);
119    
120            /**
121             * Returns a map of locales and localized strings for the parameter in the
122             * request.
123             *
124             * @param  request the request
125             * @param  parameter the prefix of the parameters containing the localized
126             *         strings. Each localization will be loaded from a parameter with
127             *         this prefix, followed by an underscore, and the language ID.
128             * @return the locales and localized strings
129             */
130            public Map<Locale, String> getLocalizationMap(
131                    HttpServletRequest request, String parameter);
132    
133            /**
134             * Returns a map of locales and localized strings for the parameter in the
135             * preferences container.
136             *
137             * @param  preferences the preferences container
138             * @param  parameter the prefix of the parameters containing the localized
139             *         strings. Each localization will be loaded from a parameter with
140             *         this prefix, followed by an underscore, and the language ID.
141             * @return the locales and localized strings
142             */
143            public Map<Locale, String> getLocalizationMap(
144                    PortletPreferences preferences, String parameter);
145    
146            /**
147             * Returns a map of locales and localized strings for the parameter in the
148             * portlet request.
149             *
150             * @param  portletRequest the portlet request
151             * @param  parameter the prefix of the parameters containing the localized
152             *         strings. Each localization will be loaded from a parameter with
153             *         this prefix, followed by an underscore, and the language ID.
154             * @return the locales and localized strings
155             */
156            public Map<Locale, String> getLocalizationMap(
157                    PortletRequest portletRequest, String parameter);
158    
159            /**
160             * Returns a map of locales and localized strings from the localizations
161             * XML.
162             *
163             * @param  xml the localizations XML
164             * @return the locales and localized strings
165             */
166            public Map<Locale, String> getLocalizationMap(String xml);
167    
168            public Map<Locale, String> getLocalizationMap(
169                    String xml, boolean useDefault);
170    
171            public Map<Locale, String> getLocalizationMap(
172                    String bundleName, ClassLoader classLoader, String key,
173                    boolean includeBetaLocales);
174    
175            /**
176             * Returns a map of locales and localized strings for the given languageIds
177             * and values.
178             *
179             * @param  languageIds the languageIds of the localized Strings
180             * @param  values the localized strings for the different languageId
181             * @return the map of locales and values for the given parameters
182             */
183            public Map<Locale, String> getLocalizationMap(
184                    String[] languageIds, String[] values);
185    
186            /**
187             * Returns the localizations XML for the parameter in the portlet request,
188             * attempting to get data from the preferences container when it is not
189             * available in the portlet request.
190             *
191             * @param  preferences the preferences container
192             * @param  portletRequest the portlet request
193             * @param  parameter the prefix of the parameters containing the localized
194             *         strings. Each localization will be loaded from a parameter with
195             *         this prefix, followed by an underscore, and the language ID.
196             * @return the locales and localized strings
197             */
198            public String getLocalizationXmlFromPreferences(
199                    PortletPreferences preferences, PortletRequest portletRequest,
200                    String parameter);
201    
202            /**
203             * @deprecated As of 6.2.0, replaced by {@link
204             *             #getLocalizationMap(PortletRequest, String)}
205             */
206            public Map<Locale, String> getLocalizedParameter(
207                    PortletRequest portletRequest, String parameter);
208    
209            /**
210             * Returns the localized preferences key in the language. Generally this is
211             * just the preferences key, followed by an underscore, and the language ID.
212             *
213             * @param  key the preferences key
214             * @param  languageId the ID of the language
215             * @return the localized preferences key
216             */
217            public String getPreferencesKey(String key, String languageId);
218    
219            /**
220             * Returns the localized preferences value for the key in the language. Uses
221             * the default language if no localization exists for the requested
222             * language.
223             *
224             * @param  preferences the preferences container
225             * @param  key the preferences key
226             * @param  languageId the ID of the language
227             * @return the localized preferences value
228             */
229            public String getPreferencesValue(
230                    PortletPreferences preferences, String key, String languageId);
231    
232            /**
233             * Returns the localized preferences value for the key in the language,
234             * optionally using the default language if the no localization exists for
235             * the requested language.
236             *
237             * @param  preferences the preferences container
238             * @param  key the preferences key
239             * @param  languageId the ID of the language
240             * @param  useDefault whether to use the default language if no localization
241             *         exists for the requested language
242             * @return the localized preferences value. If <code>useDefault</code> is
243             *         <code>false</code> and no localization exists for the requested
244             *         language, an empty string will be returned.
245             */
246            public String getPreferencesValue(
247                    PortletPreferences preferences, String key, String languageId,
248                    boolean useDefault);
249    
250            /**
251             * Returns the localized preferences values for the key in the language.
252             * Uses the default language if no localization exists for the requested
253             * language.
254             *
255             * @param  preferences the preferences container
256             * @param  key the preferences key
257             * @param  languageId the ID of the language
258             * @return the localized preferences values
259             */
260            public String[] getPreferencesValues(
261                    PortletPreferences preferences, String key, String languageId);
262    
263            /**
264             * Returns the localized preferences values for the key in the language,
265             * optionally using the default language if the no localization exists for
266             * the requested language.
267             *
268             * @param  preferences the preferences container
269             * @param  key the preferences key
270             * @param  languageId the ID of the language
271             * @param  useDefault whether to use the default language if no localization
272             *         exists for the requested language
273             * @return the localized preferences values. If <code>useDefault</code> is
274             *         <code>false</code> and no localization exists for the requested
275             *         language, an empty array will be returned.
276             */
277            public String[] getPreferencesValues(
278                    PortletPreferences preferences, String key, String languageId,
279                    boolean useDefault);
280    
281            /**
282             * Removes the localization for the language from the localizations XML.
283             * Stores the localized strings as characters in the XML.
284             *
285             * @param  xml the localizations XML
286             * @param  key the name of the localized string, such as &quot;Title&quot;
287             * @param  requestedLanguageId the ID of the language
288             * @return the localizations XML with the language removed
289             */
290            public String removeLocalization(
291                    String xml, String key, String requestedLanguageId);
292    
293            /**
294             * Removes the localization for the language from the localizations XML,
295             * optionally storing the localized strings as CDATA in the XML.
296             *
297             * @param  xml the localizations XML
298             * @param  key the name of the localized string, such as &quot;Title&quot;
299             * @param  requestedLanguageId the ID of the language
300             * @param  cdata whether to store localized strings as CDATA in the XML
301             * @return the localizations XML with the language removed
302             */
303            public String removeLocalization(
304                    String xml, String key, String requestedLanguageId, boolean cdata);
305    
306            /**
307             * Removes the localization for the language from the localizations XML,
308             * optionally storing the localized strings as CDATA in the XML.
309             *
310             * @param  xml the localizations XML
311             * @param  key the name of the localized string, such as &quot;Title&quot;
312             * @param  requestedLanguageId the ID of the language
313             * @param  cdata whether to store localized strings as CDATA in the XML
314             * @param  localized whether there is a localized field
315             * @return the localizations XML with the language removed
316             */
317            public String removeLocalization(
318                    String xml, String key, String requestedLanguageId, boolean cdata,
319                    boolean localized);
320    
321            /**
322             * Sets the localized preferences values for the parameter in the portlet
323             * request.
324             *
325             * @param  portletRequest the portlet request
326             * @param  preferences the preferences container
327             * @param  parameter the prefix of the parameters containing the localized
328             *         strings. Each localization will be loaded from a parameter with
329             *         this prefix, followed by an underscore, and the language ID.
330             * @throws Exception if an exception occurred
331             */
332            public void setLocalizedPreferencesValues(
333                            PortletRequest portletRequest, PortletPreferences preferences,
334                            String parameter)
335                    throws Exception;
336    
337            /**
338             * Sets the localized preferences value for the key in the language.
339             *
340             * @param  preferences the preferences container
341             * @param  key the preferences key
342             * @param  languageId the ID of the language
343             * @param  value the localized value
344             * @throws Exception if an exception occurred
345             */
346            public void setPreferencesValue(
347                            PortletPreferences preferences, String key, String languageId,
348                            String value)
349                    throws Exception;
350    
351            /**
352             * Sets the localized preferences values for the key in the language.
353             *
354             * @param  preferences the preferences container
355             * @param  key the preferences key
356             * @param  languageId the ID of the language
357             * @param  values the localized values
358             * @throws Exception if an exception occurred
359             */
360            public void setPreferencesValues(
361                            PortletPreferences preferences, String key, String languageId,
362                            String[] values)
363                    throws Exception;
364    
365            /**
366             * Updates the localized string for all the available languages in the
367             * localizations XML for the map of locales and localized strings and
368             * changes the default language. Stores the localized strings as characters
369             * in the XML.
370             *
371             * @param  localizationMap the locales and localized strings
372             * @param  xml the localizations XML
373             * @param  key the name of the localized string, such as &quot;Title&quot;
374             * @param  defaultLanguageId the ID of the default language
375             * @return the updated localizations XML
376             */
377            public String updateLocalization(
378                    Map<Locale, String> localizationMap, String xml, String key,
379                    String defaultLanguageId);
380    
381            /**
382             * Updates the localized string for the system default language in the
383             * localizations XML. Stores the localized strings as characters in the XML.
384             *
385             * @param  xml the localizations XML
386             * @param  key the name of the localized string, such as &quot;Title&quot;
387             * @param  value the localized string
388             * @return the updated localizations XML
389             */
390            public String updateLocalization(String xml, String key, String value);
391    
392            /**
393             * Updates the localized string for the language in the localizations XML.
394             * Stores the localized strings as characters in the XML.
395             *
396             * @param  xml the localizations XML
397             * @param  key the name of the localized string, such as &quot;Title&quot;
398             * @param  value the localized string
399             * @param  requestedLanguageId the ID of the language
400             * @return the updated localizations XML
401             */
402            public String updateLocalization(
403                    String xml, String key, String value, String requestedLanguageId);
404    
405            /**
406             * Updates the localized string for the language in the localizations XML
407             * and changes the default language. Stores the localized strings as
408             * characters in the XML.
409             *
410             * @param  xml the localizations XML
411             * @param  key the name of the localized string, such as &quot;Title&quot;
412             * @param  value the localized string
413             * @param  requestedLanguageId the ID of the language
414             * @param  defaultLanguageId the ID of the default language
415             * @return the updated localizations XML
416             */
417            public String updateLocalization(
418                    String xml, String key, String value, String requestedLanguageId,
419                    String defaultLanguageId);
420    
421            /**
422             * Updates the localized string for the language in the localizations XML
423             * and changes the default language, optionally storing the localized
424             * strings as CDATA in the XML.
425             *
426             * @param  xml the localizations XML
427             * @param  key the name of the localized string, such as &quot;Title&quot;
428             * @param  value the localized string
429             * @param  requestedLanguageId the ID of the language
430             * @param  defaultLanguageId the ID of the default language
431             * @param  cdata whether to store localized strings as CDATA in the XML
432             * @return the updated localizations XML
433             */
434            public String updateLocalization(
435                    String xml, String key, String value, String requestedLanguageId,
436                    String defaultLanguageId, boolean cdata);
437    
438            /**
439             * Updates the localized string for the language in the localizations XML
440             * and changes the default language, optionally storing the localized
441             * strings as CDATA in the XML.
442             *
443             * @param  xml the localizations XML
444             * @param  key the name of the localized string, such as &quot;Title&quot;
445             * @param  value the localized string
446             * @param  requestedLanguageId the ID of the language
447             * @param  defaultLanguageId the ID of the default language
448             * @param  cdata whether to store localized strings as CDATA in the XML
449             * @param  localized whether there is a localized field
450             * @return the updated localizations XML
451             */
452            public String updateLocalization(
453                    String xml, String key, String value, String requestedLanguageId,
454                    String defaultLanguageId, boolean cdata, boolean localized);
455    
456    }