001    /**
002     * Copyright (c) 2000-2010 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     * Caching of the localized values is done in this class rather than in the
032     * value object since value objects get flushed from cache fairly quickly.
033     * Though lookups performed on a key based on an XML file is slower than lookups
034     * done at the value object level in general, the value object will get flushed
035     * at a rate which works against the performance gain. The cache is a soft hash
036     * map which prevents memory leaks within the system while enabling the cache to
037     * live 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 to deserialize
052             * @return the locales and localized strings
053             */
054            public Object deserialize(JSONObject jsonObject);
055    
056            /**
057             * Gets the available locales from the localizations XML
058             *
059             * @param  xml the localizations XML to get the available locales from
060             * @return the language ids of the available locales
061             */
062            public String[] getAvailableLocales(String xml);
063    
064            /**
065             * Gets the default locale from the localizations XML.
066             *
067             * @param  xml the localizations XML to get the default locale from
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             * Gets the localized string from the localizations XML. Uses the default
075             * language if no localization exists for the requested language.
076             *
077             * @param  xml the localizations XML to get the localized string from
078             * @param  requestedLanguageId the id of the language to get the
079             *                 localization for
080             * @return the localized string
081             */
082            public String getLocalization(String xml, String requestedLanguageId);
083    
084            /**
085             * Gets the localized string from the localizations XML, optionally using
086             * the default language if the no localization exists for the requested
087             * language.
088             *
089             * @param  xml the localizations XML to get the localized string from
090             * @param  requestedLanguageId the id of the language to get the
091             *                 localization for
092             * @param  useDefault whether to use the default language if no localization
093             *                 exists for the requested language
094             * @return the localized string. If <code>useDefault</code> is
095             *                 <code>false</code> and no localization exists for the requested
096             *                 language, an empty string will be returned.
097             */
098            public String getLocalization(
099                    String xml, String requestedLanguageId, boolean useDefault);
100    
101            /**
102             * Gets a map of locales and localized strings for the parameter in the
103             * portlet request.
104             *
105             * @param  portletRequest the portlet request to get the locales and
106             *                 localized strings from
107             * @param  parameter the prefix of the parameters containing the localized
108             *                 strings. Each localization will be loaded from a parameter with
109             *                 this prefix, followed by an underscore, and the language id.
110             * @return the locales and localized strings
111             */
112            public Map<Locale, String> getLocalizationMap(
113                    PortletRequest portletRequest, String parameter);
114    
115            /**
116             * Gets a map of locales and localized strings from the localizations XML.
117             *
118             * @param  xml the localizations XML to get the locales and localized
119             *                 strings from
120             * @return the locales and localized strings
121             */
122            public Map<Locale, String> getLocalizationMap(String xml);
123    
124            /**
125             * @deprecated use {@link #getLocalizationMap(PortletRequest, String)}
126             *                         instead.
127             */
128            public Map<Locale, String> getLocalizedParameter(
129                    PortletRequest portletRequest, String parameter);
130    
131            /**
132             * Gets the localized preferences value for the key. Uses the default
133             * language if no localization exists for the requested language.
134             *
135             * @param  preferences the preferences container to get the localized value
136             *                 from
137             * @param  key the preferences key to get the localized value for
138             * @param  languageId the id of the language to get the localization for
139             * @return the localized preferences value
140             */
141            public String getPreferencesValue(
142                    PortletPreferences preferences, String key, String languageId);
143    
144            /**
145             * Gets the localized preferences value for the key, optionally using the
146             * default language if the no localization exists for the requested
147             * language.
148             *
149             * @param  preferences the preferences container to get the localized value
150             *                 from
151             * @param  key the preferences key to get the localized value for
152             * @param  languageId the id of the language to get the localization for
153             * @param  useDefault whether to use the default language if no localization
154             *                 exists for the requested language
155             * @return the localized preferences value. If <code>useDefault</code> is
156             *                 <code>false</code> and no localization exists for the requested
157             *                 language, an empty string will be returned.
158             */
159            public String getPreferencesValue(
160                    PortletPreferences preferences, String key, String languageId,
161                    boolean useDefault);
162    
163            /**
164             * Gets the localized preferences values for the key. Uses the default
165             * language if no localization exists for the requested language.
166             *
167             * @param  preferences the preferences container to get the localized values
168             *                 from
169             * @param  key the preferences key to get localized values for
170             * @param  languageId the id of the language to get the localizations for
171             * @return the localized preferences values
172             */
173            public String[] getPreferencesValues(
174                    PortletPreferences preferences, String key, String languageId);
175    
176            /**
177             * Gets the localized preferences values for the key, optionally using the
178             * default language if the no localization exists for the requested
179             * language.
180             *
181             * @param  preferences the preferences container to get the localized values
182             *                 from
183             * @param  key the preferences key to get localized values for
184             * @param  languageId the id of the language to get the localizations for
185             * @param  useDefault whether to use the default language if no localization
186             *                 exists for the requested language
187             * @return the localized preferences values. If <code>useDefault</code> is
188             *                 <code>false</code> and no localization exists for the requested
189             *                 language, an empty array will be returned.
190             */
191            public String[] getPreferencesValues(
192                    PortletPreferences preferences, String key, String languageId,
193                    boolean useDefault);
194    
195            /**
196             * Removes the localization for the language from the localizations XML.
197             * Stores the localized strings as characters in the XML.
198             *
199             * @param  xml the localizations XML to remove the localization for the
200             *                 language from
201             * @param  key the name of the localized string, such as &quot;Title&quot;
202             * @param  requestedLanguageId the id of the language to remove from the
203             *                 localizations XML
204             * @return the localizations XML with the language removed
205             */
206            public String removeLocalization(
207                    String xml, String key, String requestedLanguageId);
208    
209            /**
210             * Removes the localization for the language from the localizations XML,
211             * optionally storing the localized strings as CDATA in the XML.
212             *
213             * @param  xml the localizations XML to remove the localization for the
214             *                 language from
215             * @param  key the name of the localized string, such as &quot;Title&quot;
216             * @param  requestedLanguageId the id of the language to remove from the
217             *                 localizations XML
218             * @param  cdata whether to store localized strings as CDATA in the XML
219             * @return the localizations XML with the language removed
220             */
221            public String removeLocalization(
222                    String xml, String key, String requestedLanguageId, boolean cdata);
223    
224            /**
225             * Sets the localized preferences values for the parameter in the portlet
226             * request.
227             *
228             * @param  portletRequest the portlet request to get the localized values
229             *                 from
230             * @param  preferences the preferences container to set the localized values
231             *                 in
232             * @param  parameter the prefix of the parameters containing the localized
233             *                 strings. Each localization will be loaded from a parameter with
234             *                 this prefix, followed by an underscore, and the language id.
235             * @throws Exception if an exception occurred
236             */
237            public void setLocalizedPreferencesValues (
238                            PortletRequest portletRequest, PortletPreferences preferences,
239                            String parameter)
240                    throws Exception;
241    
242            /**
243             * Sets the localized preferences value for the key.
244             *
245             * @param  preferences the preferences container to store the localized
246             *                 value in
247             * @param  key the preferences key to set the localized value for
248             * @param  languageId the id of the language to set the localization for
249             * @param  value the localized value
250             * @throws Exception if an exception occurred
251             */
252            public void setPreferencesValue(
253                            PortletPreferences preferences, String key, String languageId,
254                            String value)
255                    throws Exception;
256    
257            /**
258             * Sets the localized preferences values for the key.
259             *
260             * @param  preferences the preferences container to store the localized
261             *                 values in
262             * @param  key the preferences key to set the localized values for
263             * @param  languageId the id of the language to set the localizations for
264             * @param  values the localized values
265             * @throws Exception if an exception occurred
266             */
267            public void setPreferencesValues(
268                            PortletPreferences preferences, String key, String languageId,
269                            String[] values)
270                    throws Exception;
271    
272            /**
273             * Updates the localized string for the system default language in the
274             * localizations XML. Stores the localized strings as characters in the XML.
275             *
276             * @param  xml the localizations XML to update the localized string in
277             * @param  key the name of the localized string, such as &quot;Title&quot;
278             * @param  value the localized string
279             * @return the updated localizations XML
280             */
281            public String updateLocalization(String xml, String key, String value);
282    
283            /**
284             * Updates the localized string for the language in the localizations XML.
285             * Stores the localized strings as characters in the XML.
286             *
287             * @param  xml the localizations XML to update the localized string in
288             * @param  key the name of the localized string, such as &quot;Title&quot;
289             * @param  value the localized string
290             * @param  requestedLanguageId the id of the language to update the
291             *                 localization for
292             * @return the updated localizations XML
293             */
294            public String updateLocalization(
295                    String xml, String key, String value, String requestedLanguageId);
296    
297            /**
298             * Updates the localized string for the language in the localizations XML
299             * and changes the default language. Stores the localized strings as
300             * characters in the XML.
301             *
302             * @param  xml the localizations XML to update the localized string in
303             * @param  key the name of the localized string, such as &quot;Title&quot;
304             * @param  value the localized string
305             * @param  requestedLanguageId the id of the language to update the
306             *                 localization for
307             * @param  defaultLanguageId the id of the default language
308             * @return the updated localizations XML
309             */
310            public String updateLocalization(
311                    String xml, String key, String value, String requestedLanguageId,
312                    String defaultLanguageId);
313    
314            /**
315             * Updates the localized string for the language in the localizations XML
316             * and changes the default language, optionally storing the localized
317             * strings as CDATA in the XML.
318             *
319             * @param  xml the localizations XML to update the localized string in
320             * @param  key the name of the localized string, such as &quot;Title&quot;
321             * @param  value the localized string
322             * @param  requestedLanguageId the id of the language to update the
323             *                 localization for
324             * @param  defaultLanguageId the id of the default language
325             * @param  cdata whether to store localized strings as CDATA in the XML
326             * @return the updated localizations XML
327             */
328            public String updateLocalization(
329                    String xml, String key, String value, String requestedLanguageId,
330                    String defaultLanguageId, boolean cdata);
331    
332    }