Package org.opencms.util

Class CmsMacroResolver

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String KEY_ATTRIBUTE
      The prefix indicating that the key represents an OpenCms runtime attribute.
      static java.lang.String KEY_CONTEXT_PATH
      Key used to specify the context path as macro value.
      static java.lang.String KEY_CURRENT_ORGUNIT_DESCRIPTION
      Key used to specify the description of the current organizational unit as macro value.
      static java.lang.String KEY_CURRENT_ORGUNIT_FQN
      Key used to specify the full qualified name of the current organizational unit as macro value.
      static java.lang.String KEY_CURRENT_TIME
      Key used to specify the current time as macro value.
      static java.lang.String KEY_CURRENT_USER_CITY
      Key used to specify the city of the current user as macro value.
      static java.lang.String KEY_CURRENT_USER_COUNTRY
      Key used to specify the country of the current user as macro value.
      static java.lang.String KEY_CURRENT_USER_DISPLAYNAME
      Key used to specify the display name of the current user as macro value.
      static java.lang.String KEY_CURRENT_USER_EMAIL
      Key used to specify the email address of the current user as macro value.
      static java.lang.String KEY_CURRENT_USER_FIRSTNAME
      Key used to specify the first name of the current user as macro value.
      static java.lang.String KEY_CURRENT_USER_FULLNAME
      Key used to specify the full name of the current user as macro value.
      static java.lang.String KEY_CURRENT_USER_INSTITUTION
      Key used to specify the institution of the current user as macro value.
      static java.lang.String KEY_CURRENT_USER_LASTLOGIN
      Key used to specify the last login date of the current user as macro value.
      static java.lang.String KEY_CURRENT_USER_LASTNAME
      Key used to specify the last name of the current user as macro value.
      static java.lang.String KEY_CURRENT_USER_NAME
      Key used to specify the user name of the current user as macro value.
      static java.lang.String KEY_CURRENT_USER_STREET
      Key used to specify the street of the current user as macro value.
      static java.lang.String KEY_CURRENT_USER_ZIP
      Key used to specify the zip code of the current user as macro value.
      static java.lang.String KEY_LOCALIZED_PREFIX
      Key prefix used to specify the value of a localized key as macro value.
      static java.lang.String KEY_OPENCMS
      Identifier for "magic" parameter names.
      static java.lang.String KEY_PAGE_CONTEXT
      The prefix indicating that the key represents a page context object.
      static java.lang.String KEY_PARAM
      Prefix for getting parameters from the CmsParameterStore.
      static java.lang.String KEY_PROJECT_ID
      Key used to specify the project id as macro value.
      static java.lang.String KEY_PROPERTY
      The prefix indicating that the key represents a property to be read on the current request URI.
      static java.lang.String KEY_PROPERTY_ELEMENT
      The prefix indicating that the key represents a property to be read on the current element.
      static java.lang.String KEY_RANDOM_ID
      Key used to specify a random id as macro value.
      static java.lang.String KEY_REQUEST_ENCODING
      Key used to specify the request encoding as macro value.
      static java.lang.String KEY_REQUEST_FOLDER
      Key used to specify the folder of the request URI as macro value.
      static java.lang.String KEY_REQUEST_LOCALE
      Key user to specify the request locale as macro value.
      static java.lang.String KEY_REQUEST_PARAM
      The prefix indicating that the key represents a HTTP request parameter.
      static java.lang.String KEY_REQUEST_SITEROOT
      Key used to specify the request site root as macro value.
      static java.lang.String KEY_REQUEST_URI
      Key used to specify the request uri as macro value.
      static java.lang.String KEY_SITEMAP_ATTRIBUTE
      Key for accessing sitemap attributes.
      static java.lang.String KEY_VALIDATION_PATH
      Key used to specify the validation path as macro value.
      static java.lang.String KEY_VALIDATION_REGEX
      Key used to specify the validation regex as macro value.
      static java.lang.String KEY_VALIDATION_VALUE
      Key used to specify the validation value as macro value.
      protected java.util.Map<java.lang.String,​java.lang.String> m_additionalMacros
      A map of additional values provided by the calling class.
      protected CmsObject m_cms
      The OpenCms user context to use for resolving macros.
      protected javax.servlet.jsp.PageContext m_jspPageContext
      The JSP's page context to use for resolving macros.
      protected boolean m_keepEmptyMacros
      Indicates if unresolved macros should be kept "as is" or replaced by an empty String.
      protected CmsMessages m_messages
      The messages resource bundle to resolve localized keys with.
      protected java.util.Map<java.lang.String,​java.lang.String[]> m_parameterMap
      The request parameter map, used for better compatibility with multi part requests.
      protected java.lang.String m_resourceName
      The resource name to use for resolving macros.
      static java.util.List<java.lang.String> VALUE_NAMES
      The "magic" commands wrapped in a List.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addDynamicMacro​(java.lang.String name, org.apache.commons.collections.Factory factory)
      Adds a macro whose value will be dynamically generated at macro resolution time.
      void addMacro​(java.lang.String key, java.lang.String value)
      Adds a customized macro to this macro resolver.
      static void copyAndResolveMacro​(CmsObject cms, java.lang.String source, java.lang.String destination, java.util.Map<java.lang.String,​java.lang.String> keyValue, boolean adjustLinks)
      Copies resources, adjust internal links (if adjustLinks==true) and resolves macros (if keyValue map is set).
      static void copyAndResolveMacro​(CmsObject cms, java.lang.String source, java.lang.String destination, java.util.Map<java.lang.String,​java.lang.String> keyValue, boolean adjustLinks, CmsResource.CmsResourceCopyMode copyMode)
      Copies resources, adjust internal links (if adjustLinks==true) and resolves macros (if keyValue map is set).
      static void copyAndResolveMacro​(CmsObject cms, java.lang.String source, java.lang.String destination, java.util.Map<java.lang.String,​java.lang.String> keyValue, boolean adjustLinks, CmsResource.CmsResourceCopyMode copyMode, I_CmsReport report)
      Copies resources, adjust internal links (if adjustLinks==true) and resolves macros (if keyValue map is set).
      static java.lang.String formatMacro​(java.lang.String input)
      Adds macro delimiters to the given input, for example key becomes %(key).
      static java.util.Map<java.lang.String,​java.lang.String[]> getBundleMapFromResources​(java.util.Properties resourceBundle, CmsResource descriptor, CmsObject clonedCms)
      Reads a bundle (key, value, descriptor) from Descriptor Resource and property resource.
      java.lang.String getMacroValue​(java.lang.String macro)
      Resolves a single macro to the macro value, returns null if the macro could not be resolved.
      boolean isKeepEmptyMacros()
      Returns true if macros that could not be resolved are kept "as is" in the input String, false if they are replaced by an empty String.
      static boolean isMacro​(java.lang.String input)
      Returns true if the given input String if formatted like a macro, that is it starts with I_CmsMacroResolver.MACRO_DELIMITER_OLD + I_CmsMacroResolver.MACRO_START_OLD and ends with I_CmsMacroResolver.MACRO_END_OLD.
      static boolean isMacro​(java.lang.String input, java.lang.String macroName)
      Returns true if the given input String is a macro equal to the given macro name.
      static java.lang.String localizedKeyMacro​(java.lang.String keyName, java.lang.Object[] params)
      Returns a macro for the given localization key with the given parameters.
      static CmsMacroResolver newInstance()
      Factory method to create a new CmsMacroResolver instance.
      static I_CmsMacroResolver newWorkplaceLocaleResolver​(CmsObject cms)
      Returns a new macro resolver that loads message keys from the workplace bundle in the user setting's language.
      java.lang.String resolveMacros​(java.lang.String input)
      Resolves the macros in the given input.
      static java.lang.String resolveMacros​(java.lang.String input, CmsObject cms, CmsMessages messages)
      Resolves the macros in the given input using the provided parameters.
      static java.lang.String resolveMacros​(java.lang.String input, I_CmsMacroResolver resolver)
      Resolves macros in the provided input String using the given macro resolver.
      CmsMacroResolver setAdditionalMacros​(java.util.Map<java.lang.String,​java.lang.String> additionalMacros)
      Provides a set of additional macros to this macro resolver.
      CmsMacroResolver setCmsObject​(CmsObject cms)
      Provides an OpenCms user context to this macro resolver, required to resolve certain macros.
      CmsMacroResolver setJspPageContext​(javax.servlet.jsp.PageContext jspPageContext)
      Provides a JSP page context to this macro resolver, required to resolve certain macros.
      CmsMacroResolver setKeepEmptyMacros​(boolean keepEmptyMacros)
      Controls of macros that can't be resolved are left unchanged in the input, or are replaced with an empty String.
      CmsMacroResolver setMessages​(CmsMessages messages)
      Provides a set of CmsMessages to this macro resolver, required to resolve localized macros.
      void setParameterMap​(java.util.Map<java.lang.String,​java.lang.String[]> parameterMap)
      Sets the parameter map.
      CmsMacroResolver setResourceName​(java.lang.String resourceName)
      Provides a resource name to this macro resolver, required to resolve certain macros.
      static java.lang.String stripMacro​(java.lang.String input)
      Strips the macro delimiters from the given input, for example %(key) or ${key} becomes key.
      com.google.common.base.Function<java.lang.String,​java.lang.String> toFunction()
      Returns a function which applies the macro substitution of this resolver to its argument.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • copyAndResolveMacro

        public static void copyAndResolveMacro​(CmsObject cms,
                                       java.lang.String source,
                                       java.lang.String destination,
                                       java.util.Map<java.lang.String,​java.lang.String> keyValue,
                                       boolean adjustLinks)
                                throws CmsException
        Copies resources, adjust internal links (if adjustLinks==true) and resolves macros (if keyValue map is set).

        Parameters:
        cms - CmsObject
        source - path
        destination - path
        keyValue - map to be used for macro resolver
        adjustLinks - boolean, true means internal links get adjusted.
        Throws:
        CmsException - exception

      • copyAndResolveMacro

        public static void copyAndResolveMacro​(CmsObject cms,
                                       java.lang.String source,
                                       java.lang.String destination,
                                       java.util.Map<java.lang.String,​java.lang.String> keyValue,
                                       boolean adjustLinks,
                                       CmsResource.CmsResourceCopyMode copyMode)
                                throws CmsException
        Copies resources, adjust internal links (if adjustLinks==true) and resolves macros (if keyValue map is set).

        Parameters:
        cms - CmsObject
        source - path
        destination - path
        keyValue - map to be used for macro resolver
        adjustLinks - boolean, true means internal links get adjusted.
        copyMode - copyMode
        Throws:
        CmsException - exception

      • copyAndResolveMacro

        public static void copyAndResolveMacro​(CmsObject cms,
                                       java.lang.String source,
                                       java.lang.String destination,
                                       java.util.Map<java.lang.String,​java.lang.String> keyValue,
                                       boolean adjustLinks,
                                       CmsResource.CmsResourceCopyMode copyMode,
                                       I_CmsReport report)
                                throws CmsException
        Copies resources, adjust internal links (if adjustLinks==true) and resolves macros (if keyValue map is set).

        Parameters:
        cms - CmsObject
        source - path
        destination - path
        keyValue - map to be used for macro resolver
        adjustLinks - boolean, true means internal links get adjusted.
        copyMode - copy Mode
        report - report to write logs to
        Throws:
        CmsException - exception

      • formatMacro

        public static java.lang.String formatMacro​(java.lang.String input)
        Adds macro delimiters to the given input, for example key becomes %(key).

        Parameters:
        input - the input to format as a macro
        Returns:
        the input formatted as a macro

      • getBundleMapFromResources

        public static java.util.Map<java.lang.String,​java.lang.String[]> getBundleMapFromResources​(java.util.Properties resourceBundle,
                                                                                                 CmsResource descriptor,
                                                                                                 CmsObject clonedCms)
                                                                                          throws CmsXmlException,
                                                                                                 CmsException
        Reads a bundle (key, value, descriptor) from Descriptor Resource and property resource.

        Parameters:
        resourceBundle - property resource
        descriptor - resource
        clonedCms - cms instance
        Returns:
        Map
        Throws:
        CmsXmlException - exception
        CmsException - exception

      • isMacro

        public static boolean isMacro​(java.lang.String input,
                              java.lang.String macroName)
        Returns true if the given input String is a macro equal to the given macro name.

        Parameters:
        input - the input to check for a macro
        macroName - the macro name to check for
        Returns:
        true if the given input String is a macro equal to the given macro name

      • localizedKeyMacro

        public static java.lang.String localizedKeyMacro​(java.lang.String keyName,
                                                 java.lang.Object[] params)
        Returns a macro for the given localization key with the given parameters.

        Parameters:
        keyName - the name of the localized key
        params - the optional parameter array
        Returns:
        a macro for the given localization key with the given parameters

      • newWorkplaceLocaleResolver

        public static I_CmsMacroResolver newWorkplaceLocaleResolver​(CmsObject cms)
        Returns a new macro resolver that loads message keys from the workplace bundle in the user setting's language.
        Parameters:
        cms - the CmsObject.
        Returns:
        a new macro resolver with messages from the workplace bundle in the current users locale.

      • resolveMacros

        public static java.lang.String resolveMacros​(java.lang.String input,
                                             CmsObject cms,
                                             CmsMessages messages)
        Resolves the macros in the given input using the provided parameters.

        A macro in the form %(key) or ${key} in the content is replaced with it's assigned value returned by the I_CmsMacroResolver.getMacroValue(String) method of the given I_CmsMacroResolver instance.

        If a macro is found that can not be mapped to a value by the given macro resolver, it is left untouched in the input.

        Parameters:
        input - the input in which to resolve the macros
        cms - the OpenCms user context to use when resolving macros
        messages - the message resource bundle to use when resolving macros
        Returns:
        the input with the macros resolved

      • resolveMacros

        public static java.lang.String resolveMacros​(java.lang.String input,
                                             I_CmsMacroResolver resolver)
        Resolves macros in the provided input String using the given macro resolver.

        A macro in the form %(key) or ${key} in the content is replaced with it's assigned value returned by the I_CmsMacroResolver.getMacroValue(String) method of the given I_CmsMacroResolver instance.

        If a macro is found that can not be mapped to a value by the given macro resolver, I_CmsMacroResolver.isKeepEmptyMacros() controls if the macro is replaced by an empty String, or is left untouched in the input.

        Parameters:
        input - the input in which to resolve the macros
        resolver - the macro resolver to use
        Returns:
        the input with all macros resolved

      • stripMacro

        public static java.lang.String stripMacro​(java.lang.String input)
        Strips the macro delimiters from the given input, for example %(key) or ${key} becomes key.

        In case the input is not a macro, null is returned.

        Parameters:
        input - the input to strip
        Returns:
        the macro stripped from the input, or null

      • addDynamicMacro

        public void addDynamicMacro​(java.lang.String name,
                            org.apache.commons.collections.Factory factory)
        Adds a macro whose value will be dynamically generated at macro resolution time.

        The value will be generated for each occurence of the macro in a string.

        Parameters:
        name - the name of the macro
        factory - the macro value generator

      • addMacro

        public void addMacro​(java.lang.String key,
                     java.lang.String value)
        Adds a customized macro to this macro resolver.

        Parameters:
        key - the macro to add
        value - the value to return if the macro is encountered

      • setAdditionalMacros

        public CmsMacroResolver setAdditionalMacros​(java.util.Map<java.lang.String,​java.lang.String> additionalMacros)
        Provides a set of additional macros to this macro resolver.

        Macros added with addMacro(String, String) are added to the same set

        Parameters:
        additionalMacros - the additional macros to add
        Returns:
        this instance of the macro resolver

      • setCmsObject

        public CmsMacroResolver setCmsObject​(CmsObject cms)
        Provides an OpenCms user context to this macro resolver, required to resolve certain macros.

        Parameters:
        cms - the OpenCms user context
        Returns:
        this instance of the macro resolver

      • setJspPageContext

        public CmsMacroResolver setJspPageContext​(javax.servlet.jsp.PageContext jspPageContext)
        Provides a JSP page context to this macro resolver, required to resolve certain macros.

        Parameters:
        jspPageContext - the JSP page context to use
        Returns:
        this instance of the macro resolver

      • setKeepEmptyMacros

        public CmsMacroResolver setKeepEmptyMacros​(boolean keepEmptyMacros)
        Controls of macros that can't be resolved are left unchanged in the input, or are replaced with an empty String.

        Parameters:
        keepEmptyMacros - the replacement flag to use
        Returns:
        this instance of the macro resolver
        See Also:
        isKeepEmptyMacros()

      • setMessages

        public CmsMacroResolver setMessages​(CmsMessages messages)
        Provides a set of CmsMessages to this macro resolver, required to resolve localized macros.

        Parameters:
        messages - the message resource bundle to use
        Returns:
        this instance of the macro resolver

      • setParameterMap

        public void setParameterMap​(java.util.Map<java.lang.String,​java.lang.String[]> parameterMap)
        Sets the parameter map.

        Parameters:
        parameterMap - the parameter map to set

      • setResourceName

        public CmsMacroResolver setResourceName​(java.lang.String resourceName)
        Provides a resource name to this macro resolver, required to resolve certain macros.

        Parameters:
        resourceName - the resource name to use
        Returns:
        this instance of the macro resolver

      • toFunction

        public com.google.common.base.Function<java.lang.String,​java.lang.String> toFunction()
        Returns a function which applies the macro substitution of this resolver to its argument.

        Returns:
        a function performing string substitution with this resolver