Package org.opencms.i18n

Class CmsLocaleManager

  • All Implemented Interfaces:
    I_CmsEventListener
    public class CmsLocaleManager
extends java.lang.Object
implements I_CmsEventListener
    Manages the locales configured for this OpenCms installation.

    Locale configuration is done in the configuration file opencms-system.xml in the opencms/system/internationalization node and it's sub-nodes.

    Since:
    6.0.0

    • Constructor Detail

      • CmsLocaleManager

        public CmsLocaleManager()
        Initializes a new CmsLocaleManager, called from the configuration.

      • CmsLocaleManager

        public CmsLocaleManager​(java.util.Locale defaultLocale)
        Initializes a new CmsLocaleManager, used for OpenCms runlevel 1 (unit tests) only.

        Parameters:
        defaultLocale - the default locale to use

    • Method Detail

      • getDefaultLocale

        public static java.util.Locale getDefaultLocale()
        Returns the default locale configured in opencms-system.xml, that is the first locale from the list provided in the opencms/system/internationalization/localesdefault node.

        Returns:
        the default locale configured in opencms-system.xml

      • getLocale

        public static java.util.Locale getLocale​(java.lang.String localeName)
        Returns a locale created from the given full name.

        The full name must consist of language code, country code(optional), variant(optional) separated by "_".

        This method will always return a valid Locale! If the provided locale name is not valid (i.e. leads to an Exception when trying to create the Locale, then the configured default Locale is returned.

        Parameters:
        localeName - the full locale name
        Returns:
        the locale or null if not available

      • getLocaleNames

        public static java.lang.String getLocaleNames​(java.util.List<java.util.Locale> locales)
        Returns the locale names from the given List of locales as a comma separated String.

        For example, if the input List contains Locale.ENGLISH and Locale.GERMANY, the result will be "en, de_DE".

        An empty String is returned if the input is null, or contains no elements.

        Parameters:
        locales - the locales to generate a String from
        Returns:
        the locale names from the given List of locales as a comma separated String

      • getLocales

        public static java.util.List<java.util.Locale> getLocales​(java.util.List<java.lang.String> localeNames)
        Returns a List of locales from an array of locale names.

        Parameters:
        localeNames - array of locale names
        Returns:
        a List of locales derived from the given locale names

      • getLocales

        public static java.util.List<java.util.Locale> getLocales​(java.lang.String localeNames)
        Returns a List of locales from a comma-separated string of locale names.

        Parameters:
        localeNames - a comma-separated string of locale names
        Returns:
        a List of locales derived from the given locale names

      • getLocaleVariants

        public static java.util.List<java.lang.String> getLocaleVariants​(java.lang.String basename,
                                                                 java.util.Locale locale,
                                                                 boolean wantBase,
                                                                 boolean defaultAsBase)

        Extends a base name with locale suffixes and yields the list of extended names in the order they typically should be used according to the given locale.

        Example: If you have base name base and the locale with String representation de_DE, the result will be (assuming en is the default locale):

        • for wantBase == false and defaultAsBase == false: [base_de_DE, base_de]
        • for wantBase == true and defaultAsBase == false: [base_de_DE, base_de, base]
        • for wantBase == false and defaultAsBase == true: [base_de_DE, base_de, base_en]
        • for wantBase == true and defaultAsBase == true: [base_de_DE, base_de, base, base_en]
        If the requested locale is a variant of the default locale, the list will never contain the default locale as last element because it appears already earlier.
        Parameters:
        basename - the base name that should be extended by locale post-fixes
        locale - the locale for which the list of extensions should be generated.
        wantBase - flag, indicating if the base name without locale post-fix should be yielded as well.
        defaultAsBase - flag, indicating, if the variant with the default locale should be used as base.
        Returns:
        the list of locale variants of the base name in the order they should be used.

      • getMainLocale

        public static java.util.Locale getMainLocale​(CmsObject cms,
                                             CmsResource res)
        Utility method to get the primary locale for a given resource.

        Parameters:
        cms - the current CMS context
        res - the resource for which the locale should be retrieved
        Returns:
        the primary locale

      • getResourceEncoding

        public static final java.lang.String getResourceEncoding​(CmsObject cms,
                                                         CmsResource res)
        Returns the content encoding set for the given resource.

        The content encoding is controlled by the property CmsPropertyDefinition.PROPERTY_CONTENT_ENCODING, which can be set on the resource or on a parent folder for all resources in this folder.

        In case no encoding has been set, the default encoding from CmsSystemInfo.getDefaultEncoding() is returned.

        Parameters:
        cms - the current OpenCms user context
        res - the resource to read the encoding for
        Returns:
        the content encoding set for the given resource

      • addAvailableLocale

        public void addAvailableLocale​(java.lang.String localeName)
        Adds a locale to the list of available locales.

        Parameters:
        localeName - the locale to add

      • addDefaultLocale

        public void addDefaultLocale​(java.lang.String localeName)
        Adds a locale to the list of default locales.

        Parameters:
        localeName - the locale to add

      • cmsEvent

        public void cmsEvent​(CmsEvent event)
        Implements the CmsEvent interface, the locale manager the events to clear the list of cached keys .

        Specified by:
        cmsEvent in interface I_CmsEventListener
        Parameters:
        event - CmsEvent that has occurred

      • getAvailableLocales

        public java.util.List<java.util.Locale> getAvailableLocales()
        Returns the list of available Locales configured in opencms-system.xml, in the opencms/system/internationalization/localesconfigured node.

        The list of configured available locales contains all locales that are allowed to be used in the VFS, for example as languages in XML content files.

        The available locales are a superset of the default locales, see getDefaultLocales().

        It's possible to reduce the system default by setting the propery CmsPropertyDefinition.PROPERTY_AVAILABLE_LOCALES to a comma separated list of locale names. However, you can not add new available locales, only remove from the configured list.

        Note that if the localesconfigured node contains a locale variant for a specific country (e.g. de_DE), then both that locale and the locale without the country suffix will be in the returned list.

        Returns:
        the list of available locale names, e.g. en, de
        See Also:
        getDefaultLocales()

      • getAvailableLocales

        public java.util.List<java.util.Locale> getAvailableLocales​(CmsObject cms,
                                                            CmsResource resource)
        Returns an array of available locale names for the given resource.

        Parameters:
        cms - the current cms permission object
        resource - the resource
        Returns:
        an array of available locale names
        See Also:
        getAvailableLocales()

      • getAvailableLocales

        public java.util.List<java.util.Locale> getAvailableLocales​(CmsObject cms,
                                                            java.lang.String resourceName)
        Returns an array of available locale names for the given resource.

        Parameters:
        cms - the current cms permission object
        resourceName - the name of the resource
        Returns:
        an array of available locale names
        See Also:
        getAvailableLocales()

      • getAvailableLocales

        public java.util.List<java.util.Locale> getAvailableLocales​(java.lang.String names)
        Returns a List of available locales from a comma separated string of locale names.

        All names are filtered against the allowed available locales configured in opencms-system.xml.

        Parameters:
        names - a comma-separated String of locale names
        Returns:
        List of locales created from the given locale names
        See Also:
        getAvailableLocales()

      • getBestAvailableLocaleForXmlContent

        public java.util.Locale getBestAvailableLocaleForXmlContent​(CmsObject cms,
                                                            CmsResource resource,
                                                            I_CmsXmlDocument content)
        Returns the best available locale present in the given XML content, or the default locale.

        Parameters:
        cms - the current OpenCms user context
        resource - the resource
        content - the XML content
        Returns:
        the locale

      • getBestMatchingLocale

        public java.util.Locale getBestMatchingLocale​(java.util.Locale requestedLocale,
                                              java.util.List<java.util.Locale> defaults,
                                              java.util.List<java.util.Locale> available)
        Tries to find the given requested locale (eventually simplified) in the collection of available locales, if the requested locale is not found it will return the first match from the given list of default locales.

        Parameters:
        requestedLocale - the requested locale, if this (or a simplified version of it) is available it will be returned
        defaults - a list of default locales to use in case the requested locale is not available
        available - the available locales to find a match in
        Returns:
        the best matching locale name or null if no name matches

      • getDefaultLocales

        public java.util.List<java.util.Locale> getDefaultLocales()
        Returns the list of default Locales configured in opencms-system.xml, in the opencms/system/internationalization/localesdefault node.

        Since the default locale is always available, the result list will always contain at least one Locale.

        It's possible to override the system default by setting the property CmsPropertyDefinition.PROPERTY_LOCALE to a comma separated list of locale names. This property is inherited from the parent folders.

        The default locales must be a subset of the configured available locales, see getAvailableLocales(). In case an invalid locale has been set with the property, this locale is ignored.

        The default locale names are used as a fallback mechanism in case a locale is requested that can not be found, for example when delivering content form an XML content.

        There is a list of default locales (instead of just one default locale) since there are scenarios when one default is not enough. Consider the following example: The main default locale is set to "en". An example XML content file contains just one language, in this case "de" and not "en". Now a request is made to the file for the locale "fr". If there would be only one default locale ("en"), we would have to give up. But since we allow more then one default, we can deliver the "de" content instead of a blank page.

        Returns:
        the list of default locale names, e.g. en, de
        See Also:
        getAvailableLocales()

      • getFirstMatchingLocale

        public java.util.Locale getFirstMatchingLocale​(java.util.List<java.util.Locale> locales,
                                               java.util.List<java.util.Locale> available)
        Returns the first matching locale (eventually simplified) from the available locales.

        In case no match is found, code null is returned.

        Parameters:
        locales - must be an ascending sorted list of locales in order of preference
        available - the available locales to find a match in
        Returns:
        the first precise or simplified match, or null in case no match is found

      • getI18nInfo

        public CmsI18nInfo getI18nInfo​(javax.servlet.http.HttpServletRequest req,
                               CmsUser user,
                               CmsProject project,
                               java.lang.String resource)
        Returns the the appropriate locale/encoding for a request, using the "right" locale handler for the given resource.

        Certain system folders (like the Workplace) require a special locale handler different from the configured handler. Use this method if you want to resolve locales exactly like the system does for a request.

        Parameters:
        req - the current http request
        user - the current user
        project - the current project
        resource - the URI of the requested resource (with full site root added)
        Returns:
        the i18n information to use for the given request context

      • getLocaleHandler

        public I_CmsLocaleHandler getLocaleHandler()
        Returns the configured locale handler.

        This handler is used to derive the appropriate locale/encoding for a request.

        Returns:
        the locale handler

      • getReuseElementsStr

        public java.lang.String getReuseElementsStr()
        Gets the string value of the 'reuse-elements' option.

        Returns:
        the string value of the 'reuse-elements' option

      • getTimeZone

        public java.util.TimeZone getTimeZone()
        Returns the OpenCms default the time zone.

        Returns:
        the OpenCms default the time zone

      • initialize

        public void initialize​(CmsObject cms)
        Initializes this locale manager with the OpenCms system configuration.

        Parameters:
        cms - an OpenCms context object that must have been initialized with "Admin" permissions

      • isInitialized

        public boolean isInitialized()
        Returns true if this locale manager is fully initialized.

        This is required to prevent errors during unit tests, simple unit tests will usually not have a fully initialized locale manager available.

        Returns:
        true if the locale manager is fully initialized

      • setLocaleHandler

        public void setLocaleHandler​(I_CmsLocaleHandler localeHandler)
        Sets the configured locale handler.

        Parameters:
        localeHandler - the locale handler to set

      • setReuseElements

        public void setReuseElements​(java.lang.String reuseElements)
        Sets the 'reuse-elemnts option value.

        Parameters:
        reuseElements - the option value

      • setTimeZone

        public void setTimeZone​(java.lang.String timeZoneName)
        Sets OpenCms default the time zone.

        If the name can not be resolved as time zone ID, then "GMT" is used.

        Parameters:
        timeZoneName - the name of the time zone to set, for example "GMT"

      • shouldReuseElements

        public boolean shouldReuseElements()
        Returns true if the 'copy page' dialog should reuse elements in auto mode when copying to a different locale.

        Returns:
        true if auto mode of the 'copy page' dialog should reuse elements