Velocity

Velocity - Velocity Template Conversion

The Velocity component outputs dynamically generated data using Velocity template engine technology.

For further details on the Velocity template engine, please refer to http://velocity.apache.org/.

Stream Information

Input	Format	All
	Number of Inputs	Unlimited
	Description	The Velocity component will accept multiple input streams. Each input stream is accessible in the Velocity template using the $in.array method.
Output	Format	Text,XML,CSV,HTML

Component Properties

Name Data Type Mapping Description

Mode

choice

Select whether the Velocity template is specified with the file or it inputs directly
The following properties that use it by the selected specification method are different. The display of the property changes when the specification method is selected.

File	-	Use external file
Inline	-	Use Template value as a template

Template string In & Out If Mode is "Inline", specify velocity template directly

TemplateFilename remoteFile In & Out If Mode is "File", specify the file path of velocity template
The absolute path can not be used.

TemplateHome

pathResolver

Specify the base folder of relative path of template file when Mode is "File".

Project folder [Relative]	-	Start point is the same folder as the project file.
Home folder [ProjectOwner]	-	Start point is the user's home folder.

TemplateEncoding

choice

In & Out

The Velocity template's encoding.

XPathVariablePrefix

string

In & Out

Defines the prefix to use within an XPath expression when referring to variables.

Variables

Loop

This component cannot be the starting point for a loop.

Transaction

Commit	Do nothing
Rollback	Do nothing

Exceptions

Type	Parameter	Stream for error handling flow	Error Code	Description
Exception	None	This component's input stream	-	Cannot find the template file.
			1	Cannot find the `Addon` class.
			2	Cannot create an instance of the `Addon` class.

How to access ASTERIA Objects in the Velocity template

Value Objects

Variables and record field values are converted to Value objects. Value objects have the following methods which can be used to get the object's value:

Method Name	Arguments	Returned JAVA Data Type	Description
strValue()	none	String	The value returned is converted from the ASTERIA String data type.
intValue()	none	int	The value returned is converted from the ASTERIA Integer data type.
longValue()	none	long	The value returned is converted from the ASTERIA Integer data type.
doubleValue()	none	double	The value returned is converted from the ASTERIA Double data type.
decimalValue()	none	BigDecimal	The value returned is converted from the ASTERIA Decimal data type.
dateValue()	none	Date	The value returned is converted from the ASTERIA DateTime data type.
booleanValue()	none	boolean	The value returned is converted from the ASTERIA Boolean data type.
byteValue()	none	byte[]	The value returned is converted from the ASTERIA Binary data type.
isNull()	none	boolean	Returns `True` if the value is null.

A reference to the Value object returns the same value as a reference to the Value object's strValue method.

Variable Objects

Flow variables and this component's LocalVariables can be referenced by their respective variable objects. These variable objects are referenced using the appropriate keyword listed below:

Project variables	$project
Flow variables	$flow
Session variables	$session
System variables	$system
Local variables	$local

A variable object is then referenced using the method below:

Method Name	Arguments	Returned Value	Description
get	String (variable name)	Value	Returns the variable's value. The variable is referenced in the following way: "$flow.var1".

The variable object's value is returned. Similarly, a system variable can be referenced within a Velocity template using the "$system" key word.

If an undefined variable is referenced, the reference string is returned. For example, if the "$flow.var1" reference is made, but no var1 flow variable exists, the String "$flow.var1" is returned. If an empty string would be preferred, use an exclamation mark in the reference. For example, if the "$!flow.var1" reference is made, but no var1 flow variable exists, an empty string is returned.

Sample:

The value of flow variable "var1" is "$flow.get("var1")".
It can be described "$flow.var1" by omitting get.
#if ($project.var2.intValue() == 1)
     Only when the value of project variable "var2" is 
     1 will the character value be output.
#end
#if ($session.var3.strValue() == "abc")
    When making a comparison using an if statement,
    objects must be compared using the appropriate
    strValue() and intValue() methods to get the required
    character string or numerical value. 
    
    Because the types being compared by the expression 
    $session.var3 == "abc" are different,
    the expression will never be true.
#end

The stream array ($in)

This component's input streams are stored in an array referenced by the "$in" key word. Each input stream is accessed using the array method.

This object is a JAVA Collection object. Each stream can be accessed in turn by using the foreach method.

Method Name	Arguments	Return Value	Description
array()	int	Stream	Returns the indexed input stream.
array()	String	Stream	Returns the input stream with the specified link name or originating from the specified component.
size()	none	int	Returns the number of input streams.
variable()	String	Value	Returns the named input stream variable.
variablenames()	none	Iterator	Returns a list iterator of the stream variable in this stream.

Each input stream's data referenced in the "$in" object is stored as a String. A method used on the "$in" object directly, is treated on the first object contained in this array object. For example, the statement "$in.~" has the same result as "$in.array(0).~".

Stream Objects

All input streams, other than XML formatted streams, take the form of a Stream object. To access the contents of the Stream object, the record method is used.

Method Name	Arguments	Returned Value	Description
records	none	Collection	Returns a `Collection` object containing the Record objects.
record()	int	Record	Returns the indexed Record.
text()	none	String	Returns the stream data as a String.
size()	none	int	Returns the number of input streams objects.

The value returned by the text() method has the same value as the Stream. A method used on the stream object directly, is treated on the first object contained in this array object. For example, the statement "$in.array(0).~" has the same result as "$in.array(0).record(0)~".

If the input stream is a single ParameterList, it can be easily referenced using "$in.field1".

Record Objects

A Record object is accessed using the field method. The returned object is a JAVA Collection object. Each object in the Collection can be referenced in turn by using the foreach method.

Method Name	Arguments	Returned Value	Description
fields	none	Collection	Returns a `Collection` object containing all the fields' value objects.
field()	int	Value	Returns the indexed field's value.
field()	String	Value	Returns the specified field's value. A field can be referenced directly as well as with the field method. For example, the statement "field('field1')" is the same as "field1".
name()	int	String	Returns the indexed field name.
getNo()	none	int	Returns the current Record's record number.
size()	none	int	Returns the currently accessed field number in the record.

A Record's field name and field values are returned as String objects.

Sample:

---
$in.text()
---
$in.array(0).text()
---
$in.array("FileGet1")
---
If there is only a single input stream from a component
named "FileGet1", then all the output will be the same.

#foreach ($stream in $in)
    #foreach ($r in $stream.records)
        $r.name(0) = $r.field(0)
        $r.name(1) = $r.field("Field2")
        $r.name(2) = $r.Field3
    #end
#end
---
If there multiple input streams, all the streams and all the
records in these streams can be accessed using the above looping.
Even if there is only a single input stream, the above
#foreach ($r in $in.records) will work. 
---
If thre stream variable, write like this  syntax.

$in.variable("FilePath")

$in.array(0).variable("FilePath")

#set ($stream = $in.array(0))
$stream.variable("FilePath")

XML Stream Objects

An XML stream input will be an XML Stream object. An XML Stream object has all the methods of a regular Stream object. It also has one addition method called doc. The doc method accesses a JDOM object. For more information on JDOM please refer to the documentation found at http://www.jdom.org/.

Method Name	Arguments	Return Value	Description
doc	none	org.jdom.Document	JDOM document object

Sample:

$in.doc.rootElement.getChild("record").getChild("field").text
The value of the document's root element's child element
"record"'s child element "field" is output.

#foreach ($r in $in.doc.rootElement.getChildren("record"))
  $r.getChild("field").text
#end
If there are multiple record elements, the foreach
statement will create a loop.

When a name space is used, the Namespace is passed as the
second argument in methods.
#set ($ns = $in.doc.rootElement.namespace )
#foreach ($r in $in.doc.rootElement.getChild("record", $ns))
  $r.getChild("field", $ns).text
#end
The record element and the field element values can be retrieved 
by using the same name space as the document element.

XPath($xpath)

$xpath is a utility class that can be used to apply XPath queries against an XML stream.

Method Name	Arguments	Return Value	Description
createXPath()	String	XPath	The XPath expression is passed as an argument. The XPath object is then made using the JAXEN XPath class.
booleanValueOf()	String, Object	boolean	The same as createXPath(expr).booleanValueOf(object).
numberValueOf()	String, Object	Number	The same as createXPath(expr).numberValueOf(object).
selectNodes()	String, Object	List	The same as createXPath(expr).selectNodes(object).
selectSingleNode()	String, Object	Object	The same as createXPath(expr).selectSingleNode(object).
stringValueOf()	String, Object	String	The same as createXPath(expr).stringValueOf(object).
valueOf()	String, Object	Object	The same as createXPath(expr).valueOf(object).

The namespace in the XPath expression follows the same namespace found in the input XML stream.

Variables can be referenced in the XPath expression. For example, if the XPathVariablePrefix defined prefix is specified as $fv, a flow variable might be referenced in the following way:

root/field1[@name=$fv:flow.var1]

If the XPathVariablePrefix is not used, the expression is converted using the Velocity engine before being interpreted as an XPath expression.

Sample:

$xpath.stringValueOf("/root/record[1]/field[1]", $in.doc)

The value of the document's root element's first
"record"'s child element "field" is output.

$xpath.booleanValueOf("count(/root/record)=5", $in.doc)
True if there are record elements under the root.

#foreach ($r in $xpath.selectNodes("/root/record", $in.doc))
    $r.getChild("field").text
#end
Because selectNodes returns a list, it is possible to use it with foreach.


$xpath.stringValueOf("/root/record[@name='$flow.var1']/field", $in.doc)

After it is converted by Velocity, the above-mentioned "$flow.var1" is
used by the XPath. 
When you want to process the variable in XPath:

$xpath.stringValueOf("/root/record[@name=$fv:flow.var1]/field", $in.doc)
Use the Prefix specified by the XPathVariablePrefix settings.

$xpath.stringValueOf("/ns:root/ns:record[1]/ns:field", $in.doc)
XPath that uses a name space. It is necessary to use the NamespacePrefix "ns"
when specifying a field definition for the input stream. 

$xpath.stringValueOf("field[1]", $in.doc.rootElement.getChild("record"))
It is possible to specify a context for the XPath as the second argument.

#set ($expr = $xpath.createXPath("field[1]"))
#foreach ($r in $in.rootDocument.getChild("record"))
    $expr.stringValueOf($r)
#end
It is possible to use the XPath object created using
createXPath in a loop.
$expr.stringValueOf($r) and $xpath.stringValueOf ("Field 1" $r) give
the same results, but because an object is created in
every loop it is faster.

System($sys)

Various general system functions are accessible using the "$sys" method.

Method Name	Arguments	Return Value	Description
escape()	String	String or Value	Converts the ">", "<", "&", and """ characters to their respective escape sequence characters. For example, ">" converts to ">".
outputXML()	org.jdom.Document	String	Returns the JDOM document as a String.
outputXML()	org.jdom.Document, boolean	String	Returns the JDOM document as a String. The second argument specifies indentation.
outputXML()	org.jdom.Element	String	Returns the JDOM Element as a String.
outputXML()	org.jdom.Element, boolean	String	Returns the JDOM Element as a String. The second argument specifies indentation.
strToInt()	String	int	Converts the String to an int value.
strToDouble()	String	double	Converts the String to a double value.
getCurrentDate()	none	Date	Returns the current date.
formatDecimal()	Value or arbitrary numeric type, String	String	The first argument is converted to a character string by the format of the second argument.
formatDate()	Value or Date, String	String	The first argument is converted to a character string by the format of the second argument.
regexpReplace()	String, String, String, boolean, boolean, boolean	String	This function performs regular expression pattern matching on the first argument. Patterns found in the first argument that match the second argument are replaced by the third argument. The fourth argument specifies whether the query distinguishes between upper and lower case characters. The fifth argument specifies if all matches are to be replaced. If not, only the first match is replaced. The sixth argument specifies whether meta characters may be used in the third argument's string. Refer to the `REGEXPREPLACE` function's help for details on the meta characters that can be used. The fourth, fifth and sixth arguments are optional. If omitted, they default to true.

The convertDomToString method has been replaced with the outputXML method allows for indentation. It is still possible to use the convertDomToString method, but it is advised that outputXML for the final output.

Sample:

$sys.escape($in.text())
The entire input stream is escaped and output.

$sys.outputXML($in.doc, true)
The input stream is indented and output.

$sys.outputXML($in.doc.rootElement.getChild("record"))
The input stream's XML data below the record element is output.

$sys.formatDate($sys.getCurrentDate(), "yyyy/MM/dd")
Output the current date.

#set ($num = 50000)
$num
$sys.formatDecimal($num, $local.FORMAT.strValue())
$sys.formatDecimal($flow.Num1, $local.FORMAT.strValue())
## Because "##" is defined as the beginning of a comment line,
## a character string like "#,##0" cannot be buried directly 
## in a template. 
## In such a case, use a different method such as using a local variable.

$sys.regexpReplace($contents, "(s?https?://[-_.!~*'()a-zA-Z0-9;/?:@&=+$,%#]+)", '<a href="$1">$1</a>')
URL links that match the second argument are replaced by the hyperlink specified by the third argument.

Output encoding($encoding)

Specify the output encoding.
Use when specifying the "charset" of HTML.

Topic

The Velocity template is cached by the engine. In order to confirm after changing TemplateEncoding, a template file is updated or the restart of FlowService is needed.
When referring to external file using #include and #parse in the Velocity template, start point is the project owner's home folder. Note that start point is not the same folder as the project file or the Velocity template file.