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(value="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 and 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 and Description
SkinConfigTool()

Method Summary

Modifier and Type	Method and 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> T	getAttributeValue(String property, String attribute, Class<T> targetType, T defaultValue) Gets the attribute value of the given attribute of property.
<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.
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.
Context<?>	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	getFileId()
org.codehaus.plexus.util.xml.Xpp3Dom	getGlobalProperties()
String	getKey()
String	getNamespace()
org.codehaus.plexus.util.xml.Xpp3Dom	getPageProperties()
org.apache.maven.project.MavenProject	getProject()
String	getProjectId()
String	getProjectLocation()
<T> T	getPropertyValue(String property, Class<T> targetType, T defaultValue) Gets the text value of the given property.
String	getResourcePath()
org.apache.maven.doxia.site.SiteModel	getSiteModel()
<T> T	getToolbox(String toolName, Class<T> toolType) Gets the associated tool to name stored in toolbox of Velocity context.
org.apache.velocity.tools.ToolContext	getVelocityContext()
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)
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)

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.

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.

Since:

2.0

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.

Since:

2.0

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.

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 Context<?> getContext()

Specified by:

getContext in interface ISkinConfig

Returns:

the context

getVelocityContext

public org.apache.velocity.tools.ToolContext getVelocityContext()

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.

getNamespace

@Nonnull
public String getNamespace()

Specified by:

getNamespace in interface ISkinConfig

Returns:

Returns a String representing the namespace.

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)

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.

Returns:

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

Throws:

ParseException