org.opencms.util
Class CmsMacroResolver

java.lang.Object
  org.opencms.util.CmsMacroResolver

All Implemented Interfaces:

I_CmsMacroResolver

public class CmsMacroResolver
extends java.lang.Object
implements I_CmsMacroResolver

Resolves macros in the form of %(key) or ${key} in an input String.

Starting with OpenCms 7.0, the preferred form of a macro is %(key). This is to avoid conflicts / confusion with the JSP EL, which also uses the ${key} syntax.

The macro names that can be resolved depend of the context objects provided to the resolver using the set... methods.

Since:

6.0.0

Version:

$Revision: 1.29 $

Author:

Alexander Kandzior, Thomas Weckert

Field Summary

static java.lang.String	KEY_ATTRIBUTE The prefix indicating that the key represents an OpenCms runtime attribute.
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_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_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_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_URI Key used to specify the request uri as macro value.
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	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.lang.String	m_resourceName The resource name to use for resolving macros.
static java.util.List	VALUE_NAMES The "magic" commands wrapped in a List.

Fields inherited from interface org.opencms.util.I_CmsMacroResolver

MACRO_DELIMITER, MACRO_DELIMITER_OLD, MACRO_END, MACRO_END_OLD, MACRO_START, MACRO_START_OLD

Constructor Summary

CmsMacroResolver()

Method Summary

void	addMacro(java.lang.String key, java.lang.String value) Adds a customized macro to this macro resolver.
static java.lang.String	formatMacro(java.lang.String input) Adds macro delimiters to the given input, for example key becomes %(key).
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.
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 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.
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.

Methods inherited from class java.lang.Object

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

Field Detail

KEY_ATTRIBUTE

public static final java.lang.String KEY_ATTRIBUTE

The prefix indicating that the key represents an OpenCms runtime attribute.

See Also:

Constant Field Values

KEY_CURRENT_ORGUNIT_DESCRIPTION

public static final java.lang.String KEY_CURRENT_ORGUNIT_DESCRIPTION

Key used to specify the description of the current organizational unit as macro value.

See Also:

Constant Field Values

KEY_CURRENT_ORGUNIT_FQN

public static final java.lang.String KEY_CURRENT_ORGUNIT_FQN

Key used to specify the full qualified name of the current organizational unit as macro value.

See Also:

Constant Field Values

KEY_CURRENT_TIME

public static final java.lang.String KEY_CURRENT_TIME

Key used to specify the current time as macro value.

See Also:

Constant Field Values

KEY_CURRENT_USER_CITY

public static final java.lang.String KEY_CURRENT_USER_CITY

Key used to specify the city of the current user as macro value.

See Also:

Constant Field Values

KEY_CURRENT_USER_COUNTRY

public static final java.lang.String KEY_CURRENT_USER_COUNTRY

Key used to specify the country of the current user as macro value.

See Also:

Constant Field Values

KEY_CURRENT_USER_DISPLAYNAME

public static final java.lang.String KEY_CURRENT_USER_DISPLAYNAME

Key used to specify the display name of the current user as macro value.

See Also:

Constant Field Values

KEY_CURRENT_USER_EMAIL

public static final java.lang.String KEY_CURRENT_USER_EMAIL

Key used to specify the email address of the current user as macro value.

See Also:

Constant Field Values

KEY_CURRENT_USER_FIRSTNAME

public static final java.lang.String KEY_CURRENT_USER_FIRSTNAME

Key used to specify the first name of the current user as macro value.

See Also:

Constant Field Values

KEY_CURRENT_USER_FULLNAME

public static final java.lang.String KEY_CURRENT_USER_FULLNAME

Key used to specify the full name of the current user as macro value.

See Also:

Constant Field Values

KEY_CURRENT_USER_LASTLOGIN

public static final java.lang.String KEY_CURRENT_USER_LASTLOGIN

Key used to specify the last login date of the current user as macro value.

See Also:

Constant Field Values

KEY_CURRENT_USER_LASTNAME

public static final java.lang.String KEY_CURRENT_USER_LASTNAME

Key used to specify the last name of the current user as macro value.

See Also:

Constant Field Values

KEY_CURRENT_USER_NAME

public static final java.lang.String KEY_CURRENT_USER_NAME

Key used to specify the user name of the current user as macro value.

See Also:

Constant Field Values

KEY_CURRENT_USER_STREET

public static final java.lang.String KEY_CURRENT_USER_STREET

Key used to specify the street of the current user as macro value.

See Also:

Constant Field Values

KEY_CURRENT_USER_ZIP

public static final java.lang.String KEY_CURRENT_USER_ZIP

Key used to specify the zip code of the current user as macro value.

See Also:

Constant Field Values

KEY_LOCALIZED_PREFIX

public static final java.lang.String KEY_LOCALIZED_PREFIX

Key prefix used to specify the value of a localized key as macro value.

See Also:

Constant Field Values

KEY_OPENCMS

public static final java.lang.String KEY_OPENCMS

Identifier for "magic" parameter names.

See Also:

Constant Field Values

KEY_PAGE_CONTEXT

public static final java.lang.String KEY_PAGE_CONTEXT

The prefix indicating that the key represents a page context object.

See Also:

Constant Field Values

KEY_PROJECT_ID

public static final java.lang.String KEY_PROJECT_ID

Key used to specify the project id as macro value.

See Also:

Constant Field Values

KEY_PROPERTY

public static final java.lang.String KEY_PROPERTY

The prefix indicating that the key represents a property to be read on the current request URI.

See Also:

Constant Field Values

KEY_PROPERTY_ELEMENT

public static final java.lang.String KEY_PROPERTY_ELEMENT

The prefix indicating that the key represents a property to be read on the current element.

See Also:

Constant Field Values

KEY_REQUEST_ENCODING

public static final java.lang.String KEY_REQUEST_ENCODING

Key used to specify the request encoding as macro value.

See Also:

Constant Field Values

KEY_REQUEST_FOLDER

public static final java.lang.String KEY_REQUEST_FOLDER

Key used to specify the folder of the request URI as macro value.

See Also:

Constant Field Values

KEY_REQUEST_LOCALE

public static final java.lang.String KEY_REQUEST_LOCALE

Key user to specify the request locale as macro value.

See Also:

Constant Field Values

KEY_REQUEST_PARAM

public static final java.lang.String KEY_REQUEST_PARAM

The prefix indicating that the key represents a HTTP request parameter.

See Also:

Constant Field Values

KEY_REQUEST_URI

public static final java.lang.String KEY_REQUEST_URI

Key used to specify the request uri as macro value.

See Also:

Constant Field Values

KEY_VALIDATION_PATH

public static final java.lang.String KEY_VALIDATION_PATH

Key used to specify the validation path as macro value.

See Also:

Constant Field Values

KEY_VALIDATION_REGEX

public static final java.lang.String KEY_VALIDATION_REGEX

Key used to specify the validation regex as macro value.

See Also:

Constant Field Values

KEY_VALIDATION_VALUE

public static final java.lang.String KEY_VALIDATION_VALUE

Key used to specify the validation value as macro value.

See Also:

Constant Field Values

VALUE_NAMES

public static final java.util.List VALUE_NAMES

The "magic" commands wrapped in a List.

m_additionalMacros

protected java.util.Map m_additionalMacros

A map of additional values provided by the calling class.

m_cms

protected CmsObject m_cms

The OpenCms user context to use for resolving macros.

m_jspPageContext

protected javax.servlet.jsp.PageContext m_jspPageContext

The JSP's page context to use for resolving macros.

m_keepEmptyMacros

protected boolean m_keepEmptyMacros

Indicates if unresolved macros should be kept "as is" or replaced by an empty String.

m_messages

protected CmsMessages m_messages

The messages resource bundle to resolve localized keys with.

m_resourceName

protected java.lang.String m_resourceName

The resource name to use for resolving macros.

Constructor Detail

CmsMacroResolver

public CmsMacroResolver()

Method Detail

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

isMacro

public 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.

Parameters:

input - the input to check for a macro

Returns:

true if the given input String if formatted like a macro

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

newInstance

public static CmsMacroResolver newInstance()

Factory method to create a new CmsMacroResolver instance.

Returns:

a new instance of a CmsMacroResolver

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

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

getMacroValue

public java.lang.String getMacroValue(java.lang.String macro)

Description copied from interface: I_CmsMacroResolver

Resolves a single macro to the macro value, returns null if the macro could not be resolved.

Specified by:

getMacroValue in interface I_CmsMacroResolver

Parameters:

macro - the macro to resolve

Returns:

the resolved macro or null if the macro could not be resolved

See Also:

I_CmsMacroResolver.getMacroValue(java.lang.String)

isKeepEmptyMacros

public boolean isKeepEmptyMacros()

Description copied from interface: I_CmsMacroResolver

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.

Specified by:

isKeepEmptyMacros in interface I_CmsMacroResolver

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

See Also:

I_CmsMacroResolver.isKeepEmptyMacros()

resolveMacros

public java.lang.String resolveMacros(java.lang.String input)

Resolves the macros in the given input.

Calls resolveMacros(String) until no more macros can be resolved in the input. This way "nested" macros in the input are resolved as well.

Specified by:

resolveMacros in interface I_CmsMacroResolver

Parameters:

input - the input to resolve the macros in

Returns:

the input with all macros resolved

See Also:

I_CmsMacroResolver.resolveMacros(java.lang.String)

setAdditionalMacros

public CmsMacroResolver setAdditionalMacros(java.util.Map 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

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