Package org.devacfr.maven.skins.reflow

Class SkinConfigTool

java.lang.Object

org.apache.velocity.tools.generic.SafeConfig

org.devacfr.maven.skins.reflow.SkinConfigTool

All Implemented Interfaces:

ISkinConfig

@DefaultKey("config")
public class SkinConfigTool
extends org.apache.velocity.tools.generic.SafeConfig
implements ISkinConfig

An Apache Velocity tool that simplifies retrieval of custom configuration values for a Maven Site.

The tool is configured to access Maven site configuration of a skin inside <custom> element of site descriptor. It supports global properties (defined at skin level) and per-page properties (defined in <page><mypage> element). The per-page properties override the global ones.

A sample configuration would be like that:

 
 <custom>
   <reflowSkin>
     <prop1>value1</prop1>
     <prop2>
       <prop21>value2</prop21>
     </prop2>
     <pages>
       <mypage project="myproject">
         <prop1>override value1</prop1>
       </mypage>
     </pages>
   </reflowSkin>
 </custom>
 
 

To get the value of prop1, one would simply use $config.prop1. This would return "override value1". Then $config.prop2 would return "value2" - the global value.

The tool allows querying the value easily, falling back from page to global configuration to null, if none is available. It also provides convenience accessors for common values.

Note

Since:

1.0

Author:

Andrius Velykis, Christophe Friederich

Field Summary

Fields

Modifier and Type	Field	Description
static String	DEFAULT_KEY
static String	SKIN_KEY	By default use Reflow skin configuration tag.

Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY

Constructor Summary

Constructors

Constructor	Description
SkinConfigTool()

Method Summary

Modifier and Type	Method	Description
protected void	configure(org.apache.velocity.tools.generic.ValueParser values)
<T> T	eval(String vtl, Class<T> requiredClass)	Evaluate a velocity expression in the current context.
org.codehaus.plexus.util.xml.Xpp3Dom	get(String property)	Default accessor for config properties.
<T> Optional<T>	getAttributeValue(String property, String attribute, Class<T> targetType)	Gets the attribute value of the given attribute of property.
<T> T	getAttributeValue(String property, String attribute, Class<T> targetType, T defaultValue)	Gets the attribute value of the given attribute of property.
<T> Optional<T>	getAttributeValue(org.codehaus.plexus.util.xml.Xpp3Dom element, String attribute, Class<T> targetType)	Get the value contained in specific attribute of element parameter.
<T> T	getAttributeValue(org.codehaus.plexus.util.xml.Xpp3Dom element, String attribute, Class<T> targetType, T defaultValue)	Get the value contained in specific attribute of element parameter.
String	getBodyContent()
Date	getBuildOutputTimestamp()	Gets the reproduce build timestamp whether property 'project.build.outputTimestamp' is fill in.
List<String>	getChildren(org.codehaus.plexus.util.xml.Xpp3Dom parentNode)	Gets the list of all children name for the parentNode.
<T extends Context<Context<?>>> T	getContext()
<T> T	getContextValue(String key, Class<T> type)	Gets the associated value to key stored in Velocity context.
String	getCurrentFileLocation()
String	getCurrentFileName()	See Doxia Sitetools - Site Renderer for more information.
String	getDatePosition()	Gets the date position of the site.
String	getFileId()
org.codehaus.plexus.util.xml.Xpp3Dom	getGlobalProperties()
HtmlTool	getHtmlTool()	Gets the tool HtmlTool.
String	getKey()
String	getNamespace()
org.codehaus.plexus.util.xml.Xpp3Dom	getPageProperties()
org.apache.maven.project.MavenProject	getProject()
String	getProjectId()
String	getProjectLocation()
<T> Optional<T>	getPropertyValue(String property, Class<T> targetType)	Gets the text value of the given property.
<T> T	getPropertyValue(String property, Class<T> targetType, T defaultValue)	Gets the text value of the given property.
String	getPublishDate()	Gets the publish date of the site.
String	getPublishDateMessage()	Gets the publish date message of the site.
String	getResourcePath()
String	getShortTitle()	Gets the short title of the site.
org.apache.maven.doxia.site.SiteModel	getSiteModel()
String	getTitle()	Gets the title of the site.
<T> T	getToolbox(String toolName, Class<T> toolType)	Gets the associated tool to name stored in toolbox of Velocity context.
org.apache.velocity.context.Context	getVelocityContext()
String	getVersion()	Gets the version of the site.
String	getVersionMessage()	Gets the version message of the site.
String	getVersionPosition()	Gets the position of the version in the site.
boolean	is(String property)	A convenience method to check if the value of the property is "true".
boolean	isActiveLink(String href)	Gets the indicating if the link is active.
boolean	isExternalLink(String url)
boolean	isValue(String property, String value)	A convenience method to check if the property is set to a specific value.
boolean	not(String property)	A convenience method to check if the value of the property is "false".
String	relativeLink(String href)
String	renderSnippet(String snippet)
String	renderSnippets(String bodyContent)	Renders the snippets found in the body content.
void	setContextValue(String key, Object value)	Sets the value in Velocity context associated to key.
protected void	setKey(String key)	Sets the key under which this tool has been configured.
static String	slugFilename(String fileName)	Converts a filename to pageId format.
String	value(String property)	Retrieves the text value of the given property, e.g. as in <myprop>value</myprop>.

Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_KEY

public static final String DEFAULT_KEY

See Also:

Constant Field Values

SKIN_KEY

public static final String SKIN_KEY

By default use Reflow skin configuration tag.

See Also:

Constant Field Values

Constructor Detail

SkinConfigTool

public SkinConfigTool()

Method Detail

configure

protected void configure(org.apache.velocity.tools.generic.ValueParser values)

Overrides:

configure in class org.apache.velocity.tools.generic.SafeConfig

See Also:

SafeConfig.configure(ValueParser)

renderSnippets

@Nonnull
public String renderSnippets(String bodyContent)
                      throws Exception

Renders the snippets found in the body content.

Specified by:

renderSnippets in interface ISkinConfig

Parameters:

bodyContent - the body content.

Returns:

Returns the String representing the transformed body content.

Throws:

Exception - if any.

renderSnippet

@Nonnull
public String renderSnippet(String snippet)
                     throws Exception

Specified by:

renderSnippet in interface ISkinConfig

Throws:

Exception

setKey

protected void setKey(String key)

Sets the key under which this tool has been configured.

Parameters:

key - the key of config

Since:

1.0

getKey

public String getKey()

Returns:

Returns the key under which this tool has been configured. The default is `config`.

Since:

1.0

getContextValue

@Nullable
public <T> T getContextValue(@Nonnull
                             String key,
                             @Nonnull
                             Class<T> type)

Gets the associated value to key stored in Velocity context.

Specified by:

getContextValue in interface ISkinConfig

Type Parameters:

T - the type of expected value.

Parameters:

key - the key name of associated value in Velocity context.

type - the the type of expected value.

Returns:

Returns the associated value to key stored in Velocity context.

setContextValue

public void setContextValue(@Nonnull
                            String key,
                            @Nullable
                            Object value)

Sets the value in Velocity context associated to key.

Specified by:

setContextValue in interface ISkinConfig

Parameters:

key - the key name of associated value in Velocity context.

value - the new value

getToolbox

@Nullable
public <T> T getToolbox(@Nonnull
                        String toolName,
                        @Nonnull
                        Class<T> toolType)

Gets the associated tool to name stored in toolbox of Velocity context.

Specified by:

getToolbox in interface ISkinConfig

Type Parameters:

T - the type of expected tool.

Parameters:

toolName - the name of tool associated in Velocity context.

toolType - the expected class of tool.

Returns:

Returns the associated tool to name stored in toolbox of Velocity context.

getHtmlTool

@Nonnull
public HtmlTool getHtmlTool()

Gets the tool HtmlTool.

Specified by:

getHtmlTool in interface ISkinConfig

Returns:

Returns the tool HtmlTool.

Since:

2.1

get

@Nullable
public org.codehaus.plexus.util.xml.Xpp3Dom get(@Nonnull
                                                String property)

Default accessor for config properties. Instead of using $config.get("myproperty"), one can utilise Velocity fallback onto the default getter and use $config.myproperty.

Specified by:

get in interface ISkinConfig

Parameters:

property - the property of interest

Returns:

configuration node if found in the following sequence:

1. In page configuration
2. In global configuration
3. null otherwise

value

@Nullable
public String value(@Nonnull
                    String property)

Retrieves the text value of the given property, e.g. as in <myprop>value</myprop>.

Parameters:

property - the property of interest

Returns:

the configuration value if found in page or globally, null otherwise.

Since:

1.0

See Also:

get(String)

getPropertyValue

@Nullable
public <T> T getPropertyValue(@Nonnull
                              String property,
                              @Nonnull
                              Class<T> targetType,
                              @Nullable
                              T defaultValue)

Gets the text value of the given property.

Specified by:

getPropertyValue in interface ISkinConfig

Type Parameters:

T - the type of returned object.

Parameters:

property - the property to use

targetType - the returned target type use to convert value.

defaultValue - the default value used if property doesn't exist.

Returns:

Returns a converted value of the given property.

getPropertyValue

@Nonnull
public <T> Optional<T> getPropertyValue(@Nonnull
                                        String property,
                                        @Nonnull
                                        Class<T> targetType)

Gets the text value of the given property.

Specified by:

getPropertyValue in interface ISkinConfig

Type Parameters:

T - the type of returned object.

Parameters:

property - the property to use

targetType - the returned target type use to convert value.

Returns:

Returns a converted value of the given property.

getChildren

public List<String> getChildren(org.codehaus.plexus.util.xml.Xpp3Dom parentNode)

Gets the list of all children name for the parentNode.

Parameters:

parentNode - the parent node to use (can be null.

Returns:

Returns a list of String representing the name of all children, which may be empty but never null.

Since:

1.3

getAttributeValue

@Nullable
public <T> T getAttributeValue(@Nonnull
                               String property,
                               @Nonnull
                               String attribute,
                               @Nonnull
                               Class<T> targetType,
                               @Nullable
                               T defaultValue)

Gets the attribute value of the given attribute of property.

Specified by:

getAttributeValue in interface ISkinConfig

Type Parameters:

T - the type of returned object.

Parameters:

property - the property to use

attribute - the attribute to use.

targetType - the returned target type use to convert value.

defaultValue - the default value used if property doesn't exist.

Returns:

Returns a converted value of the given property.

getAttributeValue

@Nonnull
public <T> Optional<T> getAttributeValue(@Nonnull
                                         String property,
                                         @Nonnull
                                         String attribute,
                                         @Nonnull
                                         Class<T> targetType)

Gets the attribute value of the given attribute of property.

Specified by:

getAttributeValue in interface ISkinConfig

Type Parameters:

T - the type of returned object.

Parameters:

property - the property to use

attribute - the attribute to use.

targetType - the returned target type use to convert value.

Returns:

Returns a converted value of the given property.

getAttributeValue

@Nullable
public <T> T getAttributeValue(@Nonnull
                               org.codehaus.plexus.util.xml.Xpp3Dom element,
                               @Nonnull
                               String attribute,
                               @Nonnull
                               Class<T> targetType,
                               @Nullable
                               T defaultValue)

Get the value contained in specific attribute of element parameter.

Specified by:

getAttributeValue in interface ISkinConfig

Type Parameters:

T - the type of returned value.

Parameters:

element - the xml element.

attribute - the attribute name.

targetType - the class of converted returned value.

defaultValue - the value to return if attribute is empty or null.

Returns:

Returns the converted value of specific attribute of element parameter if exists, otherwise returns the default value.

getAttributeValue

@Nonnull
public <T> Optional<T> getAttributeValue(@Nonnull
                                         org.codehaus.plexus.util.xml.Xpp3Dom element,
                                         @Nonnull
                                         String attribute,
                                         @Nonnull
                                         Class<T> targetType)

Get the value contained in specific attribute of element parameter.

Specified by:

getAttributeValue in interface ISkinConfig

Type Parameters:

T - the type of returned value.

Parameters:

element - the xml element.

attribute - the attribute name.

targetType - the class of converted returned value.

Returns:

Returns the converted value of specific attribute of element parameter if exists, otherwise returns an empty Optional.

is

public boolean is(String property)

A convenience method to check if the value of the property is "true".

Parameters:

property - the property of interest

Returns:

true if the configuration value is set either in page or globally, and is equal to "true".

Since:

1.0

See Also:

get(String)

not

public boolean not(String property)

A convenience method to check if the value of the property is "false". Useful for properties that are enabled by default - checks if the property is set to "false" explicitly.

Specified by:

not in interface ISkinConfig

Parameters:

property - the property of interest

Returns:

true if the configuration value is set either in page or globally, and is equal to "false". Note that this will return false if property is not set at all.

See Also:

ISkinConfig.get(String)

isValue

public boolean isValue(String property,
                       String value)

A convenience method to check if the property is set to a specific value.

Parameters:

property - the property of interest

value - the property value to check

Returns:

true if the configuration value is set either in page or globally, and is equal to value.

Since:

1.0

See Also:

get(String)

getProjectId

@Nullable
public String getProjectId()

Specified by:

getProjectId in interface ISkinConfig

Returns:

Returns the String representing the projectId.

getFileId

@Nullable
public String getFileId()

Specified by:

getFileId in interface ISkinConfig

Returns:

Returns the String representing the fileId.

getContext

@Nonnull
public <T extends Context<Context<?>>> T getContext()

Specified by:

getContext in interface ISkinConfig

Returns:

the context

getVelocityContext

public org.apache.velocity.context.Context getVelocityContext()

Specified by:

getVelocityContext in interface ISkinConfig

Returns:

the velocity Context

getProject

@Nonnull
public org.apache.maven.project.MavenProject getProject()

Specified by:

getProject in interface ISkinConfig

Returns:

the project

getSiteModel

@Nonnull
public org.apache.maven.doxia.site.SiteModel getSiteModel()

Specified by:

getSiteModel in interface ISkinConfig

Returns:

the SiteModel

getPageProperties

@Nonnull
public org.codehaus.plexus.util.xml.Xpp3Dom getPageProperties()

Specified by:

getPageProperties in interface ISkinConfig

Returns:

Returns the page level Xpp3Dom.

getGlobalProperties

@Nonnull
public org.codehaus.plexus.util.xml.Xpp3Dom getGlobalProperties()

Specified by:

getGlobalProperties in interface ISkinConfig

Returns:

Returns the root level Xpp3Dom.

getShortTitle

@Nonnull
public String getShortTitle()

Gets the short title of the site.

Specified by:

getShortTitle in interface ISkinConfig

Returns:

Returns the short title of the site.

getTitle

@Nonnull
public String getTitle()

Gets the title of the site.

Specified by:

getTitle in interface ISkinConfig

Returns:

Returns the title of the site.

getPublishDate

@Nonnull
public String getPublishDate()

Gets the publish date of the site.

Specified by:

getPublishDate in interface ISkinConfig

Returns:

Returns the publish date of the site.

getPublishDateMessage

@Nonnull
public String getPublishDateMessage()

Gets the publish date message of the site.

Specified by:

getPublishDateMessage in interface ISkinConfig

Returns:

Returns the publish date message of the site.

getDatePosition

@Nonnull
public String getDatePosition()

Gets the date position of the site.

Specified by:

getDatePosition in interface ISkinConfig

Returns:

Returns the date position of the site.

getVersion

@Nonnull
public String getVersion()

Gets the version of the site.

Specified by:

getVersion in interface ISkinConfig

Returns:

Returns the version of the site.

getVersionPosition

@Nonnull
public String getVersionPosition()

Gets the position of the version in the site.

Specified by:

getVersionPosition in interface ISkinConfig

Returns:

Returns the position of the version in the site.

getVersionMessage

@Nonnull
public String getVersionMessage()

Gets the version message of the site.

Specified by:

getVersionMessage in interface ISkinConfig

Returns:

Returns the version message of the site.

getNamespace

@Nonnull
public String getNamespace()

Specified by:

getNamespace in interface ISkinConfig

Returns:

Returns a String representing the namespace.

getBodyContent

@Nonnull
public String getBodyContent()

Specified by:

getBodyContent in interface ISkinConfig

Returns:

Returns the html body content stored in velocity context.

Since:

2.1

getProjectLocation

@Nonnull
public String getProjectLocation()

Returns:

Returns the location of project.

getCurrentFileName

@Nonnull
public String getCurrentFileName()

See Doxia Sitetools - Site Renderer for more information.

Returns:

Returns a String representing the name of current file of the (HTML) document being rendered, relative to the site root.

getCurrentFileLocation

@Nonnull
public String getCurrentFileLocation()

Returns:

Returns a String representing the location path of current rendered file.

eval

@Nullable
public <T> T eval(@Nullable
                  String vtl,
                  @Nonnull
                  Class<T> requiredClass)

Evaluate a velocity expression in the current context.

Specified by:

eval in interface ISkinConfig

Type Parameters:

T - Tthe type of expected returned value.

Parameters:

vtl - The velocity expression to evaluate

requiredClass - the class of returned value.

Returns:

Returns the value returned by the evaluated velocity expression.

relativeLink

public String relativeLink(String href)

Specified by:

relativeLink in interface ISkinConfig

Parameters:

href - link to relative.

Returns:

Returns Relativizes the link.

isExternalLink

public boolean isExternalLink(String url)

Specified by:

isExternalLink in interface ISkinConfig

Parameters:

url - a url.

Returns:

Returns true whether the link is a external link to the site.

isActiveLink

public boolean isActiveLink(@Nullable
                            String href)

Gets the indicating if the link is active.

Specified by:

isActiveLink in interface ISkinConfig

Parameters:

href - the link to check.

Returns:

Returns true the link is active, otherwise false.

slugFilename

@Nullable
public static String slugFilename(@Nullable
                                  String fileName)

Converts a filename to pageId format.

Parameters:

fileName - the filename to convert

Returns:

Returns a String representing the pageId of filename.

getResourcePath

@Nonnull
public String getResourcePath()

Specified by:

getResourcePath in interface ISkinConfig

Returns:

Returns a String representing the relative path to root site.

getBuildOutputTimestamp

@Nullable
public Date getBuildOutputTimestamp()
                             throws ParseException

Gets the reproduce build timestamp whether property 'project.build.outputTimestamp' is fill in.

Specified by:

getBuildOutputTimestamp in interface ISkinConfig

Returns:

Returns a instance of Date representing the reproduce build timestamp whether property 'project.build.outputTimestamp' is fill in.

Throws:

ParseException - if the build timestamp can not be parsed.