General Actions:
Velocity Module
Last modified by Marius Dumitru Florea on 2012/05/21 13:14
 | Adds support for Velocity scripting |
| Type | JAR |
| Developed by | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Enterprise, XWiki Enterprise Manager |
| Compatibility | XWiki 3.0M3+ |
Table of contents
Description
This module offers APIs to evaluate content with Velocity.
The following concepts are exposed:
- VelocityEngine: This is the object on which you call evaluate()
- VelocityConfiguration: Default Velocity configuration. Sets default configuration parameters and default tools (see below)
- VelocityContextFactory: Allows to create Velocity Context. Context are used when evaluating in order to expose some variable to the script content
- VelocityFactory: Allows to create several VelocityEngine based on a key you defined. For example XWiki Platform uses this to have one VelocityEngine per Skin. This allows each Skin to provide its own set of Velocimacros.
- VelocityContextInitializer: Allows to callback components that implements this Role when VelocityFactory is called to create a new Velocity Context. This allows your code to automatically bind new variables in the Velocity Context.
To see more of the API read the Velocity Module Javadoc
Velocity Tools
For security reasons we're not exposing some APIs to Velocity scripting (such as Reflection or Threading APIs). In addition Velocity is a template language and doesn't have the full support a complete development language has (for example you cannot instantiate new classes or you cannot handle exceptions just to name 2). Thus we need to offer some Tools (i.e. API) that are meant to be used from Velocity to make it easy to create powerful scripts in Velocity code.
The following Velocity tools are made available:
- Collections Tool: $collectionstool (since 4.0M1)
- Comparison Date Tool (extends Date Tool): $datetool
- Escape Tool (extends the standard Velocity escape tool): $escapetool (since 2.7RC1)
We have extended the standard escape tool. See the API below. - JSON Tool: $jsontool (since 4.0M2)
- List Tool: $listtool
- Math Tool: $mathtool
- Message Tool: $msg This tool is used to provide internationalized messages based on keys. For more details see the How to Write Internationalized Applications tutorial.
- Number Tool: $numbertool
- Regex Tool: $regextool (since 2.0RC2)
- Sort Tool: $sorttool
- String Tool: $stringtool (since 3.4M1)
Escape Tool
/**
* <p>
* Tool for working with escaping in Velocity templates. It provides methods to escape outputs for Velocity, Java,
* JavaScript, HTML, XML and SQL.
* </p>
* <p>
* Extends the default EscapeTool from velocity-tools since the XML escape performed by it doesn't work inside HTML
* content, since {@code apos} is not a valid HTML entity name, and it always escapes non-ASCII characters, which
* increases the HTML length considerably, while also making the source unreadable.
* </p>
*
* @since 2.7RC1
*/
public class EscapeTool extends org.apache.velocity.tools.generic.EscapeTool
{
/**
* Escapes the XML special characters in a <code>String</code> using numerical XML entities.
*
* @param content the text to escape, may be {@code null}
* @return a new escaped {@code String}, {@code null} if {@code null} input
*/
@Override
public String xml(Object content);
/**
* Encode a text using the Quoted-Printable format, as specified in section 6.7 of <a
* href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>. UTF-8 is used as the character encoding, and no line
* breaking is performed.
*
* @param content the text to encode
* @return the text converted into the Quoted-Printable format
*/
public String quotedPrintable(Object content);
/**
* Encode a text using the Q encoding specified in <a href="http://www.ietf.org/rfc/rfc2047.txt">RFC 2047</a>. UTF-8
* is used as the character encoding, and no line breaking is performed. The resulting text is already wrapped with
* the encoded word markers, starting with {@code =?UTF-8?Q?} and ending with {@code ?=}.
*
* @param content the text to encode
* @return the text converted into an encoded word using the Q encoding
*/
public String q(Object content);
/**
* Encode a text using the B encoding specified in <a href="http://www.ietf.org/rfc/rfc2047.txt">RFC 2047</a>. UTF-8
* is used as the character encoding, and no line breaking is performed. The resulting text is already wrapped with
* the encoded word markers, starting with {@code =?UTF-8?B?} and ending with {@code ?=}.
*
* @param content the text to encode
* @return the text converted into an encoded word using the B encoding
*/
public String b(Object content);
}
* <p>
* Tool for working with escaping in Velocity templates. It provides methods to escape outputs for Velocity, Java,
* JavaScript, HTML, XML and SQL.
* </p>
* <p>
* Extends the default EscapeTool from velocity-tools since the XML escape performed by it doesn't work inside HTML
* content, since {@code apos} is not a valid HTML entity name, and it always escapes non-ASCII characters, which
* increases the HTML length considerably, while also making the source unreadable.
* </p>
*
* @since 2.7RC1
*/
public class EscapeTool extends org.apache.velocity.tools.generic.EscapeTool
{
/**
* Escapes the XML special characters in a <code>String</code> using numerical XML entities.
*
* @param content the text to escape, may be {@code null}
* @return a new escaped {@code String}, {@code null} if {@code null} input
*/
@Override
public String xml(Object content);
/**
* Encode a text using the Quoted-Printable format, as specified in section 6.7 of <a
* href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>. UTF-8 is used as the character encoding, and no line
* breaking is performed.
*
* @param content the text to encode
* @return the text converted into the Quoted-Printable format
*/
public String quotedPrintable(Object content);
/**
* Encode a text using the Q encoding specified in <a href="http://www.ietf.org/rfc/rfc2047.txt">RFC 2047</a>. UTF-8
* is used as the character encoding, and no line breaking is performed. The resulting text is already wrapped with
* the encoded word markers, starting with {@code =?UTF-8?Q?} and ending with {@code ?=}.
*
* @param content the text to encode
* @return the text converted into an encoded word using the Q encoding
*/
public String q(Object content);
/**
* Encode a text using the B encoding specified in <a href="http://www.ietf.org/rfc/rfc2047.txt">RFC 2047</a>. UTF-8
* is used as the character encoding, and no line breaking is performed. The resulting text is already wrapped with
* the encoded word markers, starting with {@code =?UTF-8?B?} and ending with {@code ?=}.
*
* @param content the text to encode
* @return the text converted into an encoded word using the B encoding
*/
public String b(Object content);
}
JSON Tool
/**
* Velocity tool to facilitate serialization of Java objects to the JSON format.
*
* @since 4.0M2
*/
public class JSONTool
{
/**
* Serialize a Java object to the JSON format.
* <p>
* Examples:
* <ul>
* <li>numbers and boolean values: 23, 13.5, true, false</li>
* <li>strings: "one\"two'three" (quotes included)</li>
* <li>arrays and collections: [1, 2, 3]</li>
* <li>maps: {"number": 23, "boolean": false, "string": "value"}</li>
* <li>beans: {"enabled": true, "name": "XWiki"} for a bean that has #isEnabled() and #getName() getters</li>
* </ul>
*
* @param object the object to be serialized to the JSON format
* @return the JSON-verified string representation of the given object
*/
public String serialize(Object object);
}
* Velocity tool to facilitate serialization of Java objects to the JSON format.
*
* @since 4.0M2
*/
public class JSONTool
{
/**
* Serialize a Java object to the JSON format.
* <p>
* Examples:
* <ul>
* <li>numbers and boolean values: 23, 13.5, true, false</li>
* <li>strings: "one\"two'three" (quotes included)</li>
* <li>arrays and collections: [1, 2, 3]</li>
* <li>maps: {"number": 23, "boolean": false, "string": "value"}</li>
* <li>beans: {"enabled": true, "name": "XWiki"} for a bean that has #isEnabled() and #getName() getters</li>
* </ul>
*
* @param object the object to be serialized to the JSON format
* @return the JSON-verified string representation of the given object
*/
public String serialize(Object object);
}
Regex Tool
/**
* Velocity Tool offering various Regex-based APIs to make it easy to manipulate regular expressions from Velocity.
*
* @since 2.0RC2
*/
public class RegexTool
{
/**
* Result of a Regex search.
*/
public class RegexResult
{
/**
* @return the captured group
*/
public String getGroup();
/**
* @return the capture group's start position
*/
public int getStart();
/**
* @return the capture group's end position
*/
public int getEnd();
}
/**
* @param content the content to parse
* @param regex the regex to look for in the passed content
* @return empty list if the passed regex doesn't match the content or several {@link RegexResult} objects
* containing the matched position and matched content for all capturing groups, the first group
* representing the whole . The first object is represents the entire pattern
*/
public List<RegexResult> find(String content, String regex);
/**
* Compiles a regular expression into a java {@code Pattern} object.
*
* @param regex the textual representation of the regular expression
* @return the {@code Pattern} object corresponding to the regular expression, or {@code null} if the expression is
* invalid
* @since 2.3M1
*/
public Pattern compile(String regex);
/**
* Returns a literal pattern <code>String</code> for the specified <code>String</code>.
* <p>
* This method produces a <code>String</code> that can be used to create a <code>Pattern</code> that would match the
* string <code>s</code> as if it were a literal pattern.
* </p>
* Metacharacters or escape sequences in the input sequence will be given no special meaning.
*
* @param s The string to be literalized
* @return A literal string replacement
* @since 2.4M2
*/
public String quote(String s);
}
* Velocity Tool offering various Regex-based APIs to make it easy to manipulate regular expressions from Velocity.
*
* @since 2.0RC2
*/
public class RegexTool
{
/**
* Result of a Regex search.
*/
public class RegexResult
{
/**
* @return the captured group
*/
public String getGroup();
/**
* @return the capture group's start position
*/
public int getStart();
/**
* @return the capture group's end position
*/
public int getEnd();
}
/**
* @param content the content to parse
* @param regex the regex to look for in the passed content
* @return empty list if the passed regex doesn't match the content or several {@link RegexResult} objects
* containing the matched position and matched content for all capturing groups, the first group
* representing the whole . The first object is represents the entire pattern
*/
public List<RegexResult> find(String content, String regex);
/**
* Compiles a regular expression into a java {@code Pattern} object.
*
* @param regex the textual representation of the regular expression
* @return the {@code Pattern} object corresponding to the regular expression, or {@code null} if the expression is
* invalid
* @since 2.3M1
*/
public Pattern compile(String regex);
/**
* Returns a literal pattern <code>String</code> for the specified <code>String</code>.
* <p>
* This method produces a <code>String</code> that can be used to create a <code>Pattern</code> that would match the
* string <code>s</code> as if it were a literal pattern.
* </p>
* Metacharacters or escape sequences in the input sequence will be given no special meaning.
*
* @param s The string to be literalized
* @return A literal string replacement
* @since 2.4M2
*/
public String quote(String s);
}
Velocity Uberspectors
The introspection behaviour in Velocity can be customized by implementing an uberspector. Velocity supports by default only one uberspector. To overcome this limitation we have implemented an uberspector that forwards all calls to a chain of uberspectors.
Method Arguments Uberspector
A chainable uberspector that tries to convert method arguments to formal parameter types when the passed arguments don't match the method signature. In other words, it looks for a method matching the passed arguments and if none is found then it tries the convert the arguments to match the available method signatures (the available methods with the same name and the same number of parameters but with different parameter types). E.g.:
$obj.someMethod('VALUE')
// will forward to
obj.someMethod(SomeEnum.VALUE)
// if obj has a method with signature someMethod(SomeEnum) and not someMethod(String)
// will forward to
obj.someMethod(SomeEnum.VALUE)
// if obj has a method with signature someMethod(SomeEnum) and not someMethod(String)
But this is not limited to enums. The conversion is done using the Properties Module which means you can create and register custom converters for data types specific to your application domain.