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