001    /**
002     * Copyright (c) 2000-2011 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 the localizations XML for the parameter in the portlet request,
137             * attempting to get data from the preferences container when it is not
138             * available in the portlet request.
139             *
140             * @param  preferences the preferences container
141             * @param  portletRequest the portlet request
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 String getLocalizationXmlFromPreferences(
148                    PortletPreferences preferences, PortletRequest portletRequest,
149                    String parameter);
150    
151            /**
152             * @deprecated Use {@link #getLocalizationMap(PortletRequest, String)}
153             *             instead.
154             */
155            public Map<Locale, String> getLocalizedParameter(
156                    PortletRequest portletRequest, String parameter);
157    
158            /**
159             * Returns the localized preferences key in the language. Generally this is
160             * just the preferences key, followed by an underscore, and the language ID.
161             *
162             * @param  key the preferences key
163             * @param  languageId the ID of the language
164             * @return the localized preferences key
165             */
166            public String getPreferencesKey(String key, String languageId);
167    
168            /**
169             * Returns the localized preferences value for the key in the language. Uses
170             * the default language if no localization exists for the requested
171             * language.
172             *
173             * @param  preferences the preferences container
174             * @param  key the preferences key
175             * @param  languageId the ID of the language
176             * @return the localized preferences value
177             */
178            public String getPreferencesValue(
179                    PortletPreferences preferences, String key, String languageId);
180    
181            /**
182             * Returns the localized preferences value for the key in the language,
183             * optionally using the default language if the no localization exists for
184             * the requested language.
185             *
186             * @param  preferences the preferences container
187             * @param  key the preferences key
188             * @param  languageId the ID of the language
189             * @param  useDefault whether to use the default language if no localization
190             *         exists for the requested language
191             * @return the localized preferences value. If <code>useDefault</code> is
192             *         <code>false</code> and no localization exists for the requested
193             *         language, an empty string will be returned.
194             */
195            public String getPreferencesValue(
196                    PortletPreferences preferences, String key, String languageId,
197                    boolean useDefault);
198    
199            /**
200             * Returns the localized preferences values for the key in the language.
201             * Uses the default language if no localization exists for the requested
202             * language.
203             *
204             * @param  preferences the preferences container
205             * @param  key the preferences key
206             * @param  languageId the ID of the language
207             * @return the localized preferences values
208             */
209            public String[] getPreferencesValues(
210                    PortletPreferences preferences, String key, String languageId);
211    
212            /**
213             * Returns the localized preferences values for the key in the language,
214             * optionally using the default language if the no localization exists for
215             * the requested language.
216             *
217             * @param  preferences the preferences container
218             * @param  key the preferences key
219             * @param  languageId the ID of the language
220             * @param  useDefault whether to use the default language if no localization
221             *         exists for the requested language
222             * @return the localized preferences values. If <code>useDefault</code> is
223             *         <code>false</code> and no localization exists for the requested
224             *         language, an empty array will be returned.
225             */
226            public String[] getPreferencesValues(
227                    PortletPreferences preferences, String key, String languageId,
228                    boolean useDefault);
229    
230            /**
231             * Removes the localization for the language from the localizations XML.
232             * Stores the localized strings as characters in the XML.
233             *
234             * @param  xml the localizations XML
235             * @param  key the name of the localized string, such as &quot;Title&quot;
236             * @param  requestedLanguageId the ID of the language
237             * @return the localizations XML with the language removed
238             */
239            public String removeLocalization(
240                    String xml, String key, String requestedLanguageId);
241    
242            /**
243             * Removes the localization for the language from the localizations XML,
244             * optionally storing the localized strings as CDATA in the XML.
245             *
246             * @param  xml the localizations XML
247             * @param  key the name of the localized string, such as &quot;Title&quot;
248             * @param  requestedLanguageId the ID of the language
249             * @param  cdata whether to store localized strings as CDATA in the XML
250             * @return the localizations XML with the language removed
251             */
252            public String removeLocalization(
253                    String xml, String key, String requestedLanguageId, boolean cdata);
254    
255            /**
256             * Removes the localization for the language from the localizations XML,
257             * optionally storing the localized strings as CDATA in the XML.
258             *
259             * @param  xml the localizations XML
260             * @param  key the name of the localized string, such as &quot;Title&quot;
261             * @param  requestedLanguageId the ID of the language
262             * @param  cdata whether to store localized strings as CDATA in the XML
263             * @param  localized whether there is a localized field
264             * @return the localizations XML with the language removed
265             */
266            public String removeLocalization(
267                    String xml, String key, String requestedLanguageId, boolean cdata,
268                    boolean localized);
269    
270            /**
271             * Sets the localized preferences values for the parameter in the portlet
272             * request.
273             *
274             * @param  portletRequest the portlet request
275             * @param  preferences the preferences container
276             * @param  parameter the prefix of the parameters containing the localized
277             *         strings. Each localization will be loaded from a parameter with
278             *         this prefix, followed by an underscore, and the language ID.
279             * @throws Exception if an exception occurred
280             */
281            public void setLocalizedPreferencesValues (
282                            PortletRequest portletRequest, PortletPreferences preferences,
283                            String parameter)
284                    throws Exception;
285    
286            /**
287             * Sets the localized preferences value for the key in the language.
288             *
289             * @param  preferences the preferences container
290             * @param  key the preferences key
291             * @param  languageId the ID of the language
292             * @param  value the localized value
293             * @throws Exception if an exception occurred
294             */
295            public void setPreferencesValue(
296                            PortletPreferences preferences, String key, String languageId,
297                            String value)
298                    throws Exception;
299    
300            /**
301             * Sets the localized preferences values for the key in the language.
302             *
303             * @param  preferences the preferences container
304             * @param  key the preferences key
305             * @param  languageId the ID of the language
306             * @param  values the localized values
307             * @throws Exception if an exception occurred
308             */
309            public void setPreferencesValues(
310                            PortletPreferences preferences, String key, String languageId,
311                            String[] values)
312                    throws Exception;
313    
314            /**
315             * Updates the localized string for the system default language in the
316             * localizations XML. Stores the localized strings as characters in the XML.
317             *
318             * @param  xml the localizations XML
319             * @param  key the name of the localized string, such as &quot;Title&quot;
320             * @param  value the localized string
321             * @return the updated localizations XML
322             */
323            public String updateLocalization(String xml, String key, String value);
324    
325            /**
326             * Updates the localized string for the language in the localizations XML.
327             * 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             * @param  requestedLanguageId the ID of the language
333             * @return the updated localizations XML
334             */
335            public String updateLocalization(
336                    String xml, String key, String value, String requestedLanguageId);
337    
338            /**
339             * Updates the localized string for the language in the localizations XML
340             * and changes the default language. Stores the localized strings as
341             * characters in the XML.
342             *
343             * @param  xml the localizations XML
344             * @param  key the name of the localized string, such as &quot;Title&quot;
345             * @param  value the localized string
346             * @param  requestedLanguageId the ID of the language
347             * @param  defaultLanguageId the ID of the default language
348             * @return the updated localizations XML
349             */
350            public String updateLocalization(
351                    String xml, String key, String value, String requestedLanguageId,
352                    String defaultLanguageId);
353    
354            /**
355             * Updates the localized string for the language in the localizations XML
356             * and changes the default language, optionally storing the localized
357             * strings as CDATA in the XML.
358             *
359             * @param  xml the localizations XML
360             * @param  key the name of the localized string, such as &quot;Title&quot;
361             * @param  value the localized string
362             * @param  requestedLanguageId the ID of the language
363             * @param  defaultLanguageId the ID of the default language
364             * @param  cdata whether to store localized strings as CDATA in the XML
365             * @return the updated localizations XML
366             */
367            public String updateLocalization(
368                    String xml, String key, String value, String requestedLanguageId,
369                    String defaultLanguageId, boolean cdata);
370    
371            /**
372             * Updates the localized string for the language in the localizations XML
373             * and changes the default language, optionally storing the localized
374             * strings as CDATA in the XML.
375             *
376             * @param  xml the localizations XML
377             * @param  key the name of the localized string, such as &quot;Title&quot;
378             * @param  value the localized string
379             * @param  requestedLanguageId the ID of the language
380             * @param  defaultLanguageId the ID of the default language
381             * @param  cdata whether to store localized strings as CDATA in the XML
382             * @param  localized whether there is a localized field
383             * @return the updated localizations XML
384             */
385            public String updateLocalization(
386                    String xml, String key, String value, String requestedLanguageId,
387                    String defaultLanguageId, boolean cdata, boolean localized);
388    
389    }