org.tinyjee.maven.dim.extensions
Class ScriptInvoker

java.lang.Object
  java.util.AbstractMap<K,V>
      java.util.HashMap<String,Object>
          org.tinyjee.maven.dim.extensions.ScriptInvoker

All Implemented Interfaces:

Serializable, Cloneable, Map<String,Object>

public class ScriptInvoker
extends HashMap<String,Object>

ScriptInvoker is a 'source-class' compatible helper class providing a runtime environment that allows to load and execute script code using the JSR-223 interface (scripting for java).

Scripts can provide input for velocity templates or they can produce content directly. When invoked, this extension first populates all given macro parameters within the script context, evaluates the script and copies any changes or newly allocated variables back into the original parameters map. When an additional source was specified these resulting parameters are available in the template via $paramName.
Any text output that is produced by scripts is set into "source-content" and is displayed when no source is given.

The following global variables are exposed in the script context, in addition to the standard template parameters:

• "globals" points to an instance of "Globals" which allows to access base path, path resolution logic, loading & attaching content, etc.
• "scriptName" is a string that is filled with the absolute path to the script file.

This extension is only useful when JSR-223 is available. Starting from Java 6, JavaScript is the only script engine that is available by default. Adding other script engines to the dependency set of module or site-plugin enables scripting languages like: Groovy, Ruby, Python and others that offer integration with JSR-223.

Usage:

%{include|source=template.vm|source-class=org.tinyjee.maven.dim.extensions.ScriptInvoker|script=my-script.js}
%{include|source-class=org.tinyjee.maven.dim.extensions.ScriptInvoker|script=my-script.js}

or when using the alias:

%{include|source=template.vm|source-script=my-script.js}
%{include|source-script=my-script.js}

Notes:

• Under normal circumstances it is preferable to create your own 'source-class' compatible helper class using Java as it adds unit testing and compiler checks. Scripting however, when combined with "site:run" allows to create content with scripts very quickly as no additional compilation step is needed to see live changes to the site.
• Scripts run in a request scope with global bindings (global variables) being shared amongst executions and script engines. Whether this has an effect on the scripts depends on the implementation of the script interpreter and the language itself.

Author:

Juergen_Kellerer, 2011-10-15

See Also:

Serialized Form

Nested Class Summary

static class

ScriptInvoker.AliasHandler Implements the "PARAM_ALIAS" alias functionality.

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Field Summary

static String	PARAM_ALIAS Defines a shortcut for the request properties 'source-class' and 'script'.
static String	PARAM_SCRIPT Sets the URL or local path to the script file to load and evaluate.

Constructor Summary

ScriptInvoker(File baseDir, Map<String,Object> requestParams)
Constructs a new Script Invoker.

Method Summary

Methods inherited from class java.util.HashMap

clear, clone, containsKey, containsValue, entrySet, get, isEmpty, keySet, put, putAll, remove, size, values

Methods inherited from class java.util.AbstractMap

equals, hashCode, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode

Field Detail

PARAM_ALIAS

public static final String PARAM_ALIAS

Defines a shortcut for the request properties 'source-class' and 'script'.

If this parameter is present inside the request parameters list, the system will effectively behave as if 'source-class' and 'script' where set separately.

See Also:

Constant Field Values

PARAM_SCRIPT

public static final String PARAM_SCRIPT

Sets the URL or local path to the script file to load and evaluate.

The specified file is resolved in exactly the same way as when using the parameter "source" (see Macro reference).

Notes:

• In addition to setting a file path, the parameter can be used to define an inline script snippet using the syntax "eval[type]:script...". E.g. for javascript this looks like %{include|source-script=eval[js]:print("Hello World");}.
• When no further source is specified, any text output produced by the script (e.g. via print "some text") is included into the current page. STDERR is always sent to both locations, the build logs and the page. Unhandled script errors will break the build.
• As velocity template processing is applied at a later stage, the script output is processed by velocity unless the parameter "source-is-template" is set to false or another "source" was specified. Thus a script can dynamically generate a velocity template and provide the parameters for the template context (though this might be kind of a overkill).

See Also:

Constant Field Values

Constructor Detail

ScriptInvoker

public ScriptInvoker(File baseDir,
                     Map<String,Object> requestParams)
              throws Exception

Constructs a new Script Invoker.

Parameters:

baseDir - the base dir to of the maven module.

requestParams - the request params of the macro call.

Throws:

Exception - In case of loading or transforming fails.