001    /**
002     * Copyright (c) 2000-2012 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 the default locale from the localizations XML.
066             *
067             * @param  xml the localizations XML
068             * @return the language ID of the default locale, or the system default
069             *         locale if the default locale cannot be retrieved from the XML
070             */
071            public String getDefaultLocale(String xml);
072    
073            /**
074             * Returns the localized string from the localizations XML in the language.
075             * Uses the default language if no localization exists for the requested
076             * language.
077             *
078             * @param  xml the localizations XML
079             * @param  requestedLanguageId the ID of the language
080             * @return the localized string
081             */
082            public String getLocalization(String xml, String requestedLanguageId);
083    
084            /**
085             * Returns the localized string from the localizations XML in the language,
086             * optionally using the default language if the no localization exists for
087             * the requested language.
088             *
089             * @param  xml the localizations XML
090             * @param  requestedLanguageId the ID of the language
091             * @param  useDefault whether to use the default language if no localization
092             *         exists for the requested language
093             * @return the localized string. If <code>useDefault</code> is
094             *         <code>false</code> and no localization exists for the requested
095             *         language, an empty string will be returned.
096             */
097            public String getLocalization(
098                    String xml, String requestedLanguageId, boolean useDefault);
099    
100            /**
101             * Returns a map of locales and localized strings for the parameter in the
102             * preferences container.
103             *
104             * @param  preferences the preferences container
105             * @param  parameter the prefix of the parameters containing the localized
106             *         strings. Each localization will be loaded from a parameter with
107             *         this prefix, followed by an underscore, and the language ID.
108             * @return the locales and localized strings
109             */
110            public Map<Locale, String> getLocalizationMap(
111                    PortletPreferences preferences, String parameter);
112    
113            /**
114             * Returns a map of locales and localized strings for the parameter in the
115             * portlet request.
116             *
117             * @param  portletRequest the portlet request
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                    PortletRequest portletRequest, String parameter);
125    
126            /**
127             * Returns a map of locales and localized strings from the localizations
128             * XML.
129             *
130             * @param  xml the localizations XML
131             * @return the locales and localized strings
132             */
133            public Map<Locale, String> getLocalizationMap(String xml);
134    
135            /**
136             * Returns a map of locales and localized strings for the given languageIds
137             * and values.
138             *
139             * @param  languageIds the languageIds of the localized Strings
140             * @param  values the localized strings for the different languageId
141             * @return the map of locales and values for the given parameters
142             */
143            public Map<Locale, String> getLocalizationMap(
144                    String[] languageIds, String[] values);
145    
146            /**
147             * Returns the localizations XML for the parameter in the portlet request,
148             * attempting to get data from the preferences container when it is not
149             * available in the portlet request.
150             *
151             * @param  preferences the preferences container
152             * @param  portletRequest the portlet request
153             * @param  parameter the prefix of the parameters containing the localized
154             *         strings. Each localization will be loaded from a parameter with
155             *         this prefix, followed by an underscore, and the language ID.
156             * @return the locales and localized strings
157             */
158            public String getLocalizationXmlFromPreferences(
159                    PortletPreferences preferences, PortletRequest portletRequest,
160                    String parameter);
161    
162            /**
163             * @deprecated Use {@link #getLocalizationMap(PortletRequest, String)}
164             *             instead.
165             */
166            public Map<Locale, String> getLocalizedParameter(
167                    PortletRequest portletRequest, String parameter);
168    
169            /**
170             * Returns the localized preferences key in the language. Generally this is
171             * just the preferences key, followed by an underscore, and the language ID.
172             *
173             * @param  key the preferences key
174             * @param  languageId the ID of the language
175             * @return the localized preferences key
176             */
177            public String getPreferencesKey(String key, String languageId);
178    
179            /**
180             * Returns the localized preferences value for the key in the language. Uses
181             * the default language if no localization exists for the requested
182             * language.
183             *
184             * @param  preferences the preferences container
185             * @param  key the preferences key
186             * @param  languageId the ID of the language
187             * @return the localized preferences value
188             */
189            public String getPreferencesValue(
190                    PortletPreferences preferences, String key, String languageId);
191    
192            /**
193             * Returns the localized preferences value for the key in the language,
194             * optionally using the default language if the no localization exists for
195             * the requested language.
196             *
197             * @param  preferences the preferences container
198             * @param  key the preferences key
199             * @param  languageId the ID of the language
200             * @param  useDefault whether to use the default language if no localization
201             *         exists for the requested language
202             * @return the localized preferences value. If <code>useDefault</code> is
203             *         <code>false</code> and no localization exists for the requested
204             *         language, an empty string will be returned.
205             */
206            public String getPreferencesValue(
207                    PortletPreferences preferences, String key, String languageId,
208                    boolean useDefault);
209    
210            /**
211             * Returns the localized preferences values for the key in the language.
212             * Uses the default language if no localization exists for the requested
213             * language.
214             *
215             * @param  preferences the preferences container
216             * @param  key the preferences key
217             * @param  languageId the ID of the language
218             * @return the localized preferences values
219             */
220            public String[] getPreferencesValues(
221                    PortletPreferences preferences, String key, String languageId);
222    
223            /**
224             * Returns the localized preferences values for the key in the language,
225             * optionally using the default language if the no localization exists for
226             * the requested language.
227             *
228             * @param  preferences the preferences container
229             * @param  key the preferences key
230             * @param  languageId the ID of the language
231             * @param  useDefault whether to use the default language if no localization
232             *         exists for the requested language
233             * @return the localized preferences values. If <code>useDefault</code> is
234             *         <code>false</code> and no localization exists for the requested
235             *         language, an empty array will be returned.
236             */
237            public String[] getPreferencesValues(
238                    PortletPreferences preferences, String key, String languageId,
239                    boolean useDefault);
240    
241            /**
242             * Removes the localization for the language from the localizations XML.
243             * Stores the localized strings as characters in the XML.
244             *
245             * @param  xml the localizations XML
246             * @param  key the name of the localized string, such as &quot;Title&quot;
247             * @param  requestedLanguageId the ID of the language
248             * @return the localizations XML with the language removed
249             */
250            public String removeLocalization(
251                    String xml, String key, String requestedLanguageId);
252    
253            /**
254             * Removes the localization for the language from the localizations XML,
255             * optionally storing the localized strings as CDATA in the XML.
256             *
257             * @param  xml the localizations XML
258             * @param  key the name of the localized string, such as &quot;Title&quot;
259             * @param  requestedLanguageId the ID of the language
260             * @param  cdata whether to store localized strings as CDATA in the XML
261             * @return the localizations XML with the language removed
262             */
263            public String removeLocalization(
264                    String xml, String key, String requestedLanguageId, boolean cdata);
265    
266            /**
267             * Removes the localization for the language from the localizations XML,
268             * optionally storing the localized strings as CDATA in the XML.
269             *
270             * @param  xml the localizations XML
271             * @param  key the name of the localized string, such as &quot;Title&quot;
272             * @param  requestedLanguageId the ID of the language
273             * @param  cdata whether to store localized strings as CDATA in the XML
274             * @param  localized whether there is a localized field
275             * @return the localizations XML with the language removed
276             */
277            public String removeLocalization(
278                    String xml, String key, String requestedLanguageId, boolean cdata,
279                    boolean localized);
280    
281            /**
282             * Sets the localized preferences values for the parameter in the portlet
283             * request.
284             *
285             * @param  portletRequest the portlet request
286             * @param  preferences the preferences container
287             * @param  parameter the prefix of the parameters containing the localized
288             *         strings. Each localization will be loaded from a parameter with
289             *         this prefix, followed by an underscore, and the language ID.
290             * @throws Exception if an exception occurred
291             */
292            public void setLocalizedPreferencesValues(
293                            PortletRequest portletRequest, PortletPreferences preferences,
294                            String parameter)
295                    throws Exception;
296    
297            /**
298             * Sets the localized preferences value for the key in the language.
299             *
300             * @param  preferences the preferences container
301             * @param  key the preferences key
302             * @param  languageId the ID of the language
303             * @param  value the localized value
304             * @throws Exception if an exception occurred
305             */
306            public void setPreferencesValue(
307                            PortletPreferences preferences, String key, String languageId,
308                            String value)
309                    throws Exception;
310    
311            /**
312             * Sets the localized preferences values for the key in the language.
313             *
314             * @param  preferences the preferences container
315             * @param  key the preferences key
316             * @param  languageId the ID of the language
317             * @param  values the localized values
318             * @throws Exception if an exception occurred
319             */
320            public void setPreferencesValues(
321                            PortletPreferences preferences, String key, String languageId,
322                            String[] values)
323                    throws Exception;
324    
325            /**
326             * Updates the localized string for the system default language in the
327             * localizations XML. Stores the localized strings as characters in the XML.
328             *
329             * @param  xml the localizations XML
330             * @param  key the name of the localized string, such as &quot;Title&quot;
331             * @param  value the localized string
332             * @return the updated localizations XML
333             */
334            public String updateLocalization(String xml, String key, String value);
335    
336            /**
337             * Updates the localized string for the language in the localizations XML.
338             * Stores the localized strings as characters in the XML.
339             *
340             * @param  xml the localizations XML
341             * @param  key the name of the localized string, such as &quot;Title&quot;
342             * @param  value the localized string
343             * @param  requestedLanguageId the ID of the language
344             * @return the updated localizations XML
345             */
346            public String updateLocalization(
347                    String xml, String key, String value, String requestedLanguageId);
348    
349            /**
350             * Updates the localized string for the language in the localizations XML
351             * and changes the default language. Stores the localized strings as
352             * characters in the XML.
353             *
354             * @param  xml the localizations XML
355             * @param  key the name of the localized string, such as &quot;Title&quot;
356             * @param  value the localized string
357             * @param  requestedLanguageId the ID of the language
358             * @param  defaultLanguageId the ID of the default language
359             * @return the updated localizations XML
360             */
361            public String updateLocalization(
362                    String xml, String key, String value, String requestedLanguageId,
363                    String defaultLanguageId);
364    
365            /**
366             * Updates the localized string for the language in the localizations XML
367             * and changes the default language, optionally storing the localized
368             * strings as CDATA in the XML.
369             *
370             * @param  xml the localizations XML
371             * @param  key the name of the localized string, such as &quot;Title&quot;
372             * @param  value the localized string
373             * @param  requestedLanguageId the ID of the language
374             * @param  defaultLanguageId the ID of the default language
375             * @param  cdata whether to store localized strings as CDATA in the XML
376             * @return the updated localizations XML
377             */
378            public String updateLocalization(
379                    String xml, String key, String value, String requestedLanguageId,
380                    String defaultLanguageId, boolean cdata);
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             * @param  localized whether there is a localized field
394             * @return the updated localizations XML
395             */
396            public String updateLocalization(
397                    String xml, String key, String value, String requestedLanguageId,
398                    String defaultLanguageId, boolean cdata, boolean localized);
399    
400    }