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