001    /**
002     * Copyright (c) 2000-2011 Liferay, Inc. All rights reserved.
003     *
004     * The contents of this file are subject to the terms of the Liferay Enterprise
005     * Subscription License ("License"). You may not use this file except in
006     * compliance with the License. You can obtain a copy of the License by
007     * contacting Liferay, Inc. See the License for the specific language governing
008     * permissions and limitations under the License, including but not limited to
009     * distribution rights of the Software.
010     *
011     *
012     *
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  preferences the preferences container 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                    PortletPreferences preferences, String parameter);
114    
115            /**
116             * Gets a map of locales and localized strings for the parameter in the
117             * portlet request.
118             *
119             * @param  portletRequest the portlet request to get the locales and
120             *         localized strings from
121             * @param  parameter the prefix of the parameters containing the localized
122             *         strings. Each localization will be loaded from a parameter with
123             *         this prefix, followed by an underscore, and the language ID.
124             * @return the locales and localized strings
125             */
126            public Map<Locale, String> getLocalizationMap(
127                    PortletRequest portletRequest, String parameter);
128    
129            /**
130             * Gets a map of locales and localized strings from the localizations XML.
131             *
132             * @param  xml the localizations XML to get the locales and localized
133             *         strings from
134             * @return the locales and localized strings
135             */
136            public Map<Locale, String> getLocalizationMap(String xml);
137    
138            /**
139             * Gets an xml of locales and localized strings for the parameter in the
140             * portlet request.
141             *
142             * @param  preferences the preferences container to get the localized value
143             *         from
144             * @param  portletRequest the portlet request to get the locales and
145             *         localized strings from
146             * @param  parameter the prefix of the parameters containing the localized
147             *         strings. Each localization will be loaded from a parameter with
148             *         this prefix, followed by an underscore, and the language ID.
149             * @return the locales and localized strings
150             */
151            public String getLocalizationXmlFromPreferences(
152                    PortletPreferences preferences, PortletRequest portletRequest,
153                    String parameter);
154    
155            /**
156             * @deprecated use {@link #getLocalizationMap(PortletRequest, String)}
157             *             instead.
158             */
159            public Map<Locale, String> getLocalizedParameter(
160                    PortletRequest portletRequest, String parameter);
161    
162            /**
163             * Gets the localized name of the key. Uses the default language if no
164             * localization exists for the requested language.
165             *
166             * @param  key the preferences key to get the localized name for
167             * @param  languageId the ID of the language to get the localization for
168             * @return the localized preferences key
169             */
170            public String getPreferencesKey(String key, String languageId);
171    
172            /**
173             * Gets the localized preferences value for the key. Uses the default
174             * language if no localization exists for the requested language.
175             *
176             * @param  preferences the preferences container to get the localized value
177             *         from
178             * @param  key the preferences key to get the localized value for
179             * @param  languageId the ID of the language to get the localization for
180             * @return the localized preferences value
181             */
182            public String getPreferencesValue(
183                    PortletPreferences preferences, String key, String languageId);
184    
185            /**
186             * Gets the localized preferences value for the key, optionally using the
187             * default language if the no localization exists for the requested
188             * language.
189             *
190             * @param  preferences the preferences container to get the localized value
191             *         from
192             * @param  key the preferences key to get the localized value for
193             * @param  languageId the ID of the language to get the localization for
194             * @param  useDefault whether to use the default language if no localization
195             *         exists for the requested language
196             * @return the localized preferences value. If <code>useDefault</code> is
197             *         <code>false</code> and no localization exists for the requested
198             *         language, an empty string will be returned.
199             */
200            public String getPreferencesValue(
201                    PortletPreferences preferences, String key, String languageId,
202                    boolean useDefault);
203    
204            /**
205             * Gets the localized preferences values for the key. Uses the default
206             * language if no localization exists for the requested language.
207             *
208             * @param  preferences the preferences container to get the localized values
209             *         from
210             * @param  key the preferences key to get localized values for
211             * @param  languageId the ID of the language to get the localizations for
212             * @return the localized preferences values
213             */
214            public String[] getPreferencesValues(
215                    PortletPreferences preferences, String key, String languageId);
216    
217            /**
218             * Gets the localized preferences values for the key, optionally using the
219             * default language if the no localization exists for the requested
220             * language.
221             *
222             * @param  preferences the preferences container to get the localized values
223             *         from
224             * @param  key the preferences key to get localized values for
225             * @param  languageId the ID of the language to get the localizations for
226             * @param  useDefault whether to use the default language if no localization
227             *         exists for the requested language
228             * @return the localized preferences values. If <code>useDefault</code> is
229             *         <code>false</code> and no localization exists for the requested
230             *         language, an empty array will be returned.
231             */
232            public String[] getPreferencesValues(
233                    PortletPreferences preferences, String key, String languageId,
234                    boolean useDefault);
235    
236            /**
237             * Removes the localization for the language from the localizations XML.
238             * Stores the localized strings as characters in the XML.
239             *
240             * @param  xml the localizations XML to remove the localization for the
241             *         language from
242             * @param  key the name of the localized string, such as &quot;Title&quot;
243             * @param  requestedLanguageId the ID of the language to remove from the
244             *         localizations XML
245             * @return the localizations XML with the language removed
246             */
247            public String removeLocalization(
248                    String xml, String key, String requestedLanguageId);
249    
250            /**
251             * Removes the localization for the language from the localizations XML,
252             * optionally storing the localized strings as CDATA in the XML.
253             *
254             * @param  xml the localizations XML to remove the localization for the
255             *         language from
256             * @param  key the name of the localized string, such as &quot;Title&quot;
257             * @param  requestedLanguageId the ID of the language to remove from the
258             *         localizations XML
259             * @param  cdata whether to store localized strings as CDATA in the XML
260             * @return the localizations XML with the language removed
261             */
262            public String removeLocalization(
263                    String xml, String key, String requestedLanguageId, boolean cdata);
264    
265            /**
266             * Removes the localization for the language from the localizations XML,
267             * optionally storing the localized strings as CDATA in the XML.
268             *
269             * @param  xml the localizations XML to remove the localization for the
270             *         language from
271             * @param  key the name of the localized string, such as &quot;Title&quot;
272             * @param  requestedLanguageId the ID of the language to remove from the
273             *         localizations XML
274             * @param  cdata whether to store localized strings as CDATA in the XML
275             * @param  localized whether there is a localized field
276             * @return the localizations XML with the language removed
277             */
278            public String removeLocalization(
279                    String xml, String key, String requestedLanguageId, boolean cdata,
280                    boolean localized);
281    
282            /**
283             * Sets the localized preferences values for the parameter in the portlet
284             * request.
285             *
286             * @param  portletRequest the portlet request to get the localized values
287             *         from
288             * @param  preferences the preferences container to set the localized values
289             *         in
290             * @param  parameter the prefix of the parameters containing the localized
291             *         strings. Each localization will be loaded from a parameter with
292             *         this prefix, followed by an underscore, and the language ID.
293             * @throws Exception if an exception occurred
294             */
295            public void setLocalizedPreferencesValues (
296                            PortletRequest portletRequest, PortletPreferences preferences,
297                            String parameter)
298                    throws Exception;
299    
300            /**
301             * Sets the localized preferences value for the key.
302             *
303             * @param  preferences the preferences container to store the localized
304             *         value in
305             * @param  key the preferences key to set the localized value for
306             * @param  languageId the ID of the language to set the localization for
307             * @param  value the localized value
308             * @throws Exception if an exception occurred
309             */
310            public void setPreferencesValue(
311                            PortletPreferences preferences, String key, String languageId,
312                            String value)
313                    throws Exception;
314    
315            /**
316             * Sets the localized preferences values for the key.
317             *
318             * @param  preferences the preferences container to store the localized
319             *         values in
320             * @param  key the preferences key to set the localized values for
321             * @param  languageId the ID of the language to set the localizations for
322             * @param  values the localized values
323             * @throws Exception if an exception occurred
324             */
325            public void setPreferencesValues(
326                            PortletPreferences preferences, String key, String languageId,
327                            String[] values)
328                    throws Exception;
329    
330            /**
331             * Updates the localized string for the system default language in the
332             * localizations XML. Stores the localized strings as characters in the XML.
333             *
334             * @param  xml the localizations XML to update the localized string in
335             * @param  key the name of the localized string, such as &quot;Title&quot;
336             * @param  value the localized string
337             * @return the updated localizations XML
338             */
339            public String updateLocalization(String xml, String key, String value);
340    
341            /**
342             * Updates the localized string for the language in the localizations XML.
343             * Stores the localized strings as characters in the XML.
344             *
345             * @param  xml the localizations XML to update the localized string in
346             * @param  key the name of the localized string, such as &quot;Title&quot;
347             * @param  value the localized string
348             * @param  requestedLanguageId the ID of the language to update the
349             *         localization for
350             * @return the updated localizations XML
351             */
352            public String updateLocalization(
353                    String xml, String key, String value, String requestedLanguageId);
354    
355            /**
356             * Updates the localized string for the language in the localizations XML
357             * and changes the default language. Stores the localized strings as
358             * characters in the XML.
359             *
360             * @param  xml the localizations XML to update the localized string in
361             * @param  key the name of the localized string, such as &quot;Title&quot;
362             * @param  value the localized string
363             * @param  requestedLanguageId the ID of the language to update the
364             *         localization for
365             * @param  defaultLanguageId the ID of the default language
366             * @return the updated localizations XML
367             */
368            public String updateLocalization(
369                    String xml, String key, String value, String requestedLanguageId,
370                    String defaultLanguageId);
371    
372            /**
373             * Updates the localized string for the language in the localizations XML
374             * and changes the default language, optionally storing the localized
375             * strings as CDATA in the XML.
376             *
377             * @param  xml the localizations XML to update the localized string in
378             * @param  key the name of the localized string, such as &quot;Title&quot;
379             * @param  value the localized string
380             * @param  requestedLanguageId the ID of the language to update the
381             *         localization for
382             * @param  defaultLanguageId the ID of the default language
383             * @param  cdata whether to store localized strings as CDATA in the XML
384             * @return the updated localizations XML
385             */
386            public String updateLocalization(
387                    String xml, String key, String value, String requestedLanguageId,
388                    String defaultLanguageId, boolean cdata);
389    
390            /**
391             * Updates the localized string for the language in the localizations XML
392             * and changes the default language, optionally storing the localized
393             * strings as CDATA in the XML.
394             *
395             * @param  xml the localizations XML to update the localized string in
396             * @param  key the name of the localized string, such as &quot;Title&quot;
397             * @param  value the localized string
398             * @param  requestedLanguageId the ID of the language to update the
399             *         localization for
400             * @param  defaultLanguageId the ID of the default language
401             * @param  cdata whether to store localized strings as CDATA in the XML
402             * @param  localized whether there is a localized field
403             * @return the updated localizations XML
404             */
405            public String updateLocalization(
406                    String xml, String key, String value, String requestedLanguageId,
407                    String defaultLanguageId, boolean cdata, boolean localized);
408    
409    }