The functions for conversion objects from one data type into another.
Function Summary | |
---|---|
Object[]
|
toArray(Object obj)
Converts a specified object to Array. |
Boolean
|
toBoolean(Object obj)
Converts a specified object to Boolean type. |
GOMElement
|
toElement(Object obj)
Converts an object to the |
Enumeration
|
toEnum(Object obj)
Converts a specified object to Enumeration. |
Number
|
toNumber(Object obj)
Converts a specified object to Number |
String
|
toString(Object obj)
Converts a specified object to String. |
String
|
toString(Object[] a,
String delimiter)
This function is a synonym for
|
Vector
|
toVector(Object obj)
Converts a specified object to Vector. |
The utility functions for manipulations with strings.
Function Summary | |
---|---|
Vector
|
breakString(String str,
String delimiter)
Breaks the specified string into fragments divided by the specified delimiter and returns a Vector containing those fragments. |
String
|
charAt(String str,
Number index)
Returns a string made of a single character taken from the specified string at the specified index. |
String
|
collapseString(String str)
Returns a string produced from the specified one with the leading and trailing whitespace (except '\n') removed and all the other sequences of contiguous whitespace replaced by a single space. |
String
|
dup(String s,
Number num)
Returns a string made of the specified string repeated |
Boolean
|
endsWith(String str,
String suffix)
Tests if the specified string ends with the specified suffix (or one among several specified suffixes). |
String
|
firstSentence(String doc)
Return the first sentence of the text contained in the specified string parameter. |
Number
|
indexOf(String str,
String search)
Returns the index within the specified string of the first occurence of the specified substring, starting at the specified index. |
Number
|
lastIndexOf(String str,
String search)
Searches the string backwards for the specified substring, starting from the specified index, and returns an index to it. |
Number
|
len(String s)
Returns the length of the specified string. |
String
|
mergeStrings(Object[] strings,
String delimiter)
Creates a new string made of fragments contained in the specified Vector or Array
and delimited with the substring specified in the |
String
|
replace(String s,
String oldSubstr,
String newSubstr)
Returns a new string that is the specified string in which
all occurences of |
Boolean
|
startsWith(String str,
String prefix)
Tests if the specified string starts with the specified prefix (or one among several specified prefixes) beginning a specified index. |
String
|
substring(String s,
Number beginIndex)
Returns a new string that is a substring of the specified string. |
String
|
toLowerCase(String s)
Returns the specified string, converted to lowercase. |
String
|
toString(Object obj)
Converts a specified object to String. |
String
|
toString(Object[] a,
String delimiter)
This function is a synonym for
|
String
|
toUpperCase(String s)
Returns the specified string, converted to uppercase. |
String
|
trim(String s)
Returns the specified string with white space removed from the front and end. |
The utility functions for manipulations with Arrays, Vectors and Enumerations.
Function Summary | |
---|---|
Vector
|
addElement(Vector v,
Object element)
Appends or inserts the specified element into the Vector. Returns the same Vector object. |
Object[]
|
Array(...)
This function creates an array from the elements passed in the function parameters. |
Number
|
compare(Object o1,
Object o2)
Compares two objects specified in the arguments and returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second. |
Number
|
count(Enumeration e)
Counts the number of elements contained in the Enumeration. |
Object
|
elementAt(Object[] a,
Number index)
Returns the element of the Array at the specified index. |
Object
|
elementAt(Vector a,
Number index)
Returns the element of the Vector at the specified index. |
Vector
|
generateVector(Enumeration source,
String subqueryExpr)
Allows to generate a Vector from elements of another Vector, Array, or Enumeration. |
Number
|
indexOf(Object[] a,
Object obj)
Returns the index within the specified Array of the first occurence of the
given object, starting at the specified index, and testing for equality using the
Java |
Number
|
indexOf(Vector a,
Object obj)
Returns the index within the specified Vector of the first occurence of the
given object, starting at the specified index, and testing for equality using the
Java |
Number
|
lastIndexOf(Object[] a,
Object obj)
Searches the Array backwards for the specified object, starting from the specified index, and returns an index to it. |
Number
|
lastIndexOf(Vector a,
Object obj)
Searches the Vector backwards for the specified object, starting from the specified index, and returns an index to it. |
Number
|
length(Object[] a)
Returns the number of elements in the array. |
Object
|
max(Object o1,
Object o2)
This function is a shortcut of the following expression: |
Object
|
maxElement(Object[] a)
Returns the maximum element of the given Array or Vector,
according to the comparison rules described in
|
String
|
mergeStrings(Object[] strings,
String delimiter)
Creates a new string made of fragments contained in the specified Vector or Array
and delimited with the substring specified in the |
Object
|
min(Object o1,
Object o2)
This function is a shortcut of the following expression: |
Object
|
minElement(Object[] a)
Returns the minimum element of the given Array or Vector,
according to the comparison rules described in
|
Object
|
nextElement(Enumeration e)
Returns the next element of the enumeration. |
Vector
|
removeElement(Vector v,
Number index)
Removes the element at the specified position in the Vector. |
Vector
|
reverseVector(Vector v)
Reverses the order of the elements in the specified Vector. |
Number
|
size(Vector v)
Returns the number of elements in the Vector. |
Object[]
|
toArray(Object obj)
Converts a specified object to Array. |
Enumeration
|
toEnum(Object obj)
Converts a specified object to Enumeration. |
String
|
toString(Object[] a,
String delimiter)
This function is a synonym for
|
Vector
|
toVector(Object obj)
Converts a specified object to Vector. |
Vector
|
Vector(...)
This function creates a Vector from the elements passed in the function parameters. |
The functions which help to access elements and attributes.
Function Summary | |
---|---|
Enumeration
|
filterElements(Enumeration elementEnum,
String targetElementTypes,
String filterExpr)
This function receives the specified enumeration of elements
(i.e. |
GOMElement
|
findElementById(Object elementId)
Finds an element by the specified element unique identifier. |
Enumeration
|
findElementsByIds(Object[] elementIds)
Finds elements by the element unique identifiers contained in the specified array and returns the enumeration of the found elements. |
GOMElement
|
findElementByKey(Object elementMapId,
Enumeration elementEnum,
String keysExpr,
Object key)
This function effectively does the same as the following call:
|
Enumeration
|
findElementsByKey(Object elementMapId,
Enumeration elementEnum,
String keysExpr,
Object key)
If you are going to process data sources with a large number of elements, this function might help you to make your templates work faster. |
GOMElement
|
findElementByLPath(GOMElement contextElement,
String lpath)
Finds elements by the specified Element Location Path interpreted against the specified context element and returns the first of the found elements. |
Enumeration
|
findElementsByLPath(GOMElement contextElement,
String lpath)
Finds elements by the specified Element Location Path interpreted against the specified context element and returns an enumeration of the found elements. |
Enumeration
|
findElementsByLRules(GOMElement contextElement,
Object[] locationRules,
String targetElementTypes,
String filterExpr)
This function provides even more powerful way of collecting elements within
DSM (Data Source Model)
as compared with the |
DSMElementType
|
findElementType(String name)
Finds an Element Type with a given name. |
GOMAttribute
|
getAttr(GOMElement element,
String attrName)
Returns a |
Object
|
getAttrValue(GOMElement element,
String attrName)
Returns a value of the specified attribute contained in the specified element. |
Object[]
|
getAttrValues(GOMElement element,
String attrName)
Returns an array of all values (a vector value) associated with the specified attribute of the specified element. |
Boolean
|
getAttrBooleanValue(GOMElement element,String attrName)
This function works as a shortcut of one of the calls:
|
Number
|
getAttrNumberValue(GOMElement element,
String attrName)
This function works as a shortcut of one of the calls:
|
String
|
getAttrStringValue(GOMElement element,
String attrName)
This function works as a shortcut of one of the calls:
|
Object[]
|
getElementIds(Enumeration elementEnum)
Returns an array containing unique identifiers of the elements contained in the specified enumeration. |
Object
|
getValueByLPath(GOMElement contextElement,
String lpath)
Finds elements/attributes by the specified Location Path interpreted against the specified context element. |
Object[]
|
getValuesByLPath(GOMElement contextElement,
String lpath)
Finds elements or attributes by the specified Location Path interpreted against the specified context element and returns an array containing all values of the found elements or attributes. |
CompoundHashKey
|
HashKey(Object subkey1,
Object subkey2, ...)
Creates a compound hash-key from the subkeys specified in the function parameters. |
Boolean
|
instanceOf(GOMElement element,
String elementTypeName)
Tests if the specified element is an instance of the specified Element Type. |
Object
|
LocationRule(String ruleSpec,
Boolean recursive)
This function is used to specify parameters for the
|
DSMElementType
|
resolveElementType()
Finds an Element Type associated with the given element. |
GOMElement
|
toElement(Object obj)
Converts an object to the |
The functions to access the template parameters.
Function Summary | |
---|---|
Object
|
getParam(String paramName)
Returns the template parameter with the specified name. |
String
|
getStringParam(String paramName)
This function is a shortcut of the following call:
|
Number
|
getNumberParam(String paramName)
This function is a shortcut of the following call:
|
Boolean
|
getBooleanParam(String paramName)
This function is a shortcut of the following call:
|
The functions to call Stock-Sections from within expression.
Function Summary | |
---|---|
String
|
callStockSection(GOMElement contextElement,
String stockSectionName)
This function allows to call from within a FlexQuery expression any Stock-Section defined in the given template. |
Boolean
|
checkStockSectionOutput(GOMElement contextElement,
String stockSectionName)
This function allows to test whether a particular Stock-Section would have a non-empty output if it was executed in the current generator context with the specified context element passed to it and the specified Stock-Section parameters. |
The functions which allow to determine existence of specific hyper-targets within the whole generated documentation and to find particular document files by different criteria.
Function Summary | |
---|---|
String
|
documentByHyperTarget(Object targetKey)
Returns the absolute path name of a generated document file which contains a hypertarget with the specified set of keys. |
String
|
documentByTemplate(String templateNames)
Returns the absolute path name of the first document file which was (or will be) produced by the specified template (or a list of templates). |
Boolean
|
hyperTargetExists(Object targetKey)
Allows to determine, if a hypertarget with the specified set of keys exists somewhere in the whole generated documentation. |
Miscellaneous functions.
Function Summary | |
---|---|
Object
|
callForName(String className)
This function allows to call execution of external custom-written Java classes from within any FlexQuery-expressions specified in your templates. |
Number
|
clearVars(String namePrefix)
|
Number
|
compare(Object o1,
Object o2)
Compares two objects specified in the arguments and returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second. |
String
|
date()
|
String
|
dateTime()
|
String
|
echo(String s)
This function prints the argument it received into the standard system output and then returns the argument as the function result. |
Object
|
execSubquery(String expr)
Executes a subquery expression specified in the function parameter and returns the result returned by the subquery. |
Object
|
getVar(String name)
|
Boolean
|
instanceOfClass(Object obj,
String className)
Tests whether the specified object is an instance of the specified Java class. |
Object
|
max(Object o1,
Object o2)
This function is a shortcut of the following expression: |
Object
|
min(Object o1,
Object o2)
This function is a shortcut of the following expression: |
String
|
resolveURL(String spec,
String contextURL)
|
Object
|
setVar(String name,
Object value)
|
Vector addElement(Vector v, Object element) Vector addElement(Vector v, Object element, Number index)
Appends or inserts the specified element into the Vector. Returns the same Vector object.
Parameters:v
element
index
If not specified, the element will be added at the end of the Vector.
If less than 0, the element will be inserted at the first position.
If greater or equal the current Vector size, the element will be added at the end of the Vector.
Tip:
You may call this function in a more method-like style:
That's why the operated Vector is returned as the function result. The following will append two elements to the Vector:v.addElement(element)
v.addElement(element1).addElement(element2)
Object[] Array(...)
This function creates an array from the elements passed in the function parameters. The number of parameters may be from zero to unlimited.
Examples:
The following call creates an empty array (same as in Java: new Object[0]
):
The following creates an array of three Number objects:Array()
This creates an array of three String objects:Array(1,2,3)
Array("1","2","3")
Vector breakString(String str, String delimiter) Vector breakString(String str, String delimiter, Boolean trimSpaces) Vector breakString(String str, Object[] delimiters, Boolean trimSpaces)
Breaks the specified string into fragments divided by the specified delimiter and returns a Vector containing those fragments.
Parameters:
str
delimiter
delimiters
In the case of multiple delimiters, the one is used at each string breaking cycle, whose position occurs the first within the rest of the string.
trimSpaces
true
, the empty fragments and those consist of only white spaces will
be ignored and not included in the result Vector.
If this parameter is not specified, it is assumed to be false
.
See Also:
mergeStrings()
Examples:
(1) The following call
will produce Vector:breakString("Vini -> vidi -> vici", "->");
(2) The call{ "Vini ", " vidi ", " vici" }
will return:breakString("one, two and three", Array (",", "and"), true);
{ "one", "two", "three" }
Object callForName(String className) Object callForName(String className, Object param) Object callForName(String className, Object[] params)
This function allows to call execution of external custom-written Java classes from within any FlexQuery-expressions specified in your templates. Thus, it provides the ultimate way to extend functionality of DocFlex templates so as to meet your specific needs not supported by DocFlex directly.
The custom Java class should implement the
com.docflex.api.generator.FlexCallHandler
interface provided by DocFlex API.
The function works the following way:
Once the class is called the first time, it is searched by
the fully qualified name specified in the className
parameter.
If no class with such a name found or what is found does not implement the
FlexCallHandler
interface, the generator rises an exception and
then terminates.
As the specified class is successfully found, an instance of it is created
and initialized with the
initCallHandler(GOMContext context)
method.
That instance is stored then by the generator during the rest of the generation
session and reused each time the class is called again.
When the generation is about to finish (even at the time it is terminated
by an exception or a user request), all created
FlexCallHandler
instances are disposed with the
disposeCallHandler()
method called for each instance object. This allows to release any resources you could
associate with a particular call handler.
Having a FlexCallHandler
instance object, the generator invokes its
execCall(GOMContext context, Object[] params)
method each time the callForName()
function is executed.
The object returned by this method becomes the function result.
Parameters:
className
param
params
FlexCallHandler.execCall()
method.
Note: In addition to those parameters,
the
FlexCallHandler.execCall()
method always receives a GOMContext
object which provides access to all generator's variables.
Example:
Tip:toEnum (callForName( "com.docflex.together.rwi.RWICallHandler", "get_known_implementing_classes"))
You may use the callForName()
function to generate your own sets
of elements and then process them with an
Element Iterator
defined in your template.
To do this, you should invoke the Element Iterator's properties dialog and specify in the 'Iteration Scope' tab the "Custom" Element Collecting Method.
Then, fill in the 'Expression for Element Enumeration' field the call to
callForName()
function generating the enumeration of the elements
you want to iterate and enclose the call
in toEnum()
as parameter, like shown
in the example above (it is needed, since this field accepts only enumerations).
For more details, see documentation: Element Iterator (details) | Specifying Element Iteration Scope | Custom.
String callStockSection(GOMElement contextElement, String stockSectionName) String callStockSection(GOMElement contextElement, String stockSectionName, Object param) String callStockSection(GOMElement contextElement, String stockSectionName, Object[] params) String callStockSection(String stockSectionName) String callStockSection(String stockSectionName, Object param) String callStockSection(String stockSectionName, Object[] params)
This function allows to call from within a FlexQuery expression any Stock-Section defined in the given template.
When called by this function, a Stock-Section is always executed in the Text Output formatting context independently on any formatting specified within the Stock-Section itself. So, everything the Stock-Section produces will be a plain text which is returned as the function result.
In any other respect, calling the Stock-Section using this function will be identical to call it via a template component (e.g. Call Stock-Section Section or Call Stock-Section Control).
You can use this feature to program generating small text fragments that you may need in your FlexQuery scripts. This will allow to utilize capabilities of major template components and to employ the Stock-Sections as procedures enhancing FlexQuery scripts.
Parameters:
contextElement
stockSection.contextElement
generator variable).
If this parameter is not specified, the
generator's context element
is used by default
(see GOMContext.contextElement
).
stockSectionName
param
params
The Stock-Section parameters can be accessed within the Stock-Section
using the stockSection.params
generator variable.
Tip:
You may call this function in a method-like style, e.g.:
methodElement.callStockSection("Method Header")
See Also:
checkStockSectionOutput(),
Array(),
stockSection
generator variable.
String charAt(String str, Number index)
Returns a string made of a single character taken from the specified string at the specified index.
An index should range from 0 to str.length()-1
.
The first character of the sequence is at index 0, the next at index 1, and so on.
If index is out of that range, an empty string is returned.
Example:
will return string:charAt("caramela",4);
Tip:"m"
You may call this function in a more method-like style:
s.charAt(index)
String checkStockSectionOutput(GOMElement contextElement, String stockSectionName) String checkStockSectionOutput(GOMElement contextElement, String stockSectionName, Object param) String checkStockSectionOutput(GOMElement contextElement, String stockSectionName, Object[] params) String checkStockSectionOutput(String stockSectionName) String checkStockSectionOutput(String stockSectionName, Object param) String checkStockSectionOutput(String stockSectionName, Object[] params)
This function allows to test whether a particular Stock-Section would have a non-empty output if it was executed in the current generator context with the specified context element passed to it and the specified Stock-Section parameters.
Technically, a call of this function is identical to the following expression:
However,callStockSection(..) != ""
checkStockSectionOutput()
will work much faster
than this since no actual output is generated. All what this function does
is to find out whether the output from a particular Stock-Section exists
or not.
You may find it helpful to use this function in the Enabling Conditions of some template components to program switching them on/off depending on whether some pieces of the output may or will be produced by this template somewhere else.
Parameters:
contextElement
stockSection.contextElement
generator variable).
If this parameter is not specified, the
generator's context element
is used by default
(see GOMContext.contextElement
).
stockSectionName
param
params
The Stock-Section parameters can be accessed within the Stock-Section
using the
stockSection.params
generator variable.
Tip:
You may call this function in a method-like style, e.g.:
See Also:diagram.checkStockSectionOutput ("Diagram Doc", Array("Use-Case Diagram", true));
callStockSection(),
Array(),
stockSection
generator variable.
Number clearVars(String namePrefix)
String collapseString(String str)
Returns a string produced from the specified one with the leading and trailing whitespace (except '\n') removed and all the other sequences of contiguous whitespace replaced by a single space.
You may use this function to remove all extra spaces from the string and remain all '\n', so when you print the result string, each line will never start or end with a space.
Number compare(Object o1, Object o2)
Compares two objects specified in the arguments and returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.
The arguments are compared according to the following rules:
null
, the one is considered
greater which is not null
.
(If both arguments are null
the function returns 0.)
java.util.Date.compareTo()
method.
Object[] a1 = (Object[]) o1; Object[] a2 = (Object[]) o2; int n = Math.min (a1.length, a2.length); for (int i = 0; i < n; i ++) { int result = compare(a1[i], a2[i]); if (result != 0) return result; } return (a1.length < a2.length) ? -1 : (a1.length > a2.length) ? 1 : 0;The
compare()
method used in this code does the same as the
one being described here.
Vector v1 = (Vector) o1; Vector v2 = (Vector) o2; int n = Math.min (v1.size(), v2.size()); for (int i = 0; i < n; i ++) { int result = compare(v1.get(i), v2.get(i)); if (result != 0) return result; } return (v1.size() < v2.size()) ? -1 : (v1.size() > v2.size()) ? 1 : 0;The
compare()
method used in this code does the same as the
one being described here.
java.lang.Comparable
interface
the function returns result of the call:
((Comparable) o1).compareTo (o2);
o1.toString().compareTo (o2.toString())
This function is related to other comparison functions:
min(),
max(),
minElement(),
maxElement()
Number count(Enumeration e)
Counts the number of elements contained in the Enumeration.
This function works the following way:
int counter = 0; while (e.hasMoreElements()) { counter ++; e.nextElement(); } return counter;
String date()
String dateTime()
String documentByHyperTarget(Object targetKey) String documentByHyperTarget(Object[] targetKey) String documentByHyperTarget(Object[] targetKey, Boolean strict)
Returns the absolute path name of a generated document file which contains a hypertarget with the specified set of keys. If such a document does not exist, the function returns an empty string.
This function returns the correct result only during the generation phase (even though the document may not have been physically generated yet). During the estimation phase, the function will always return an empty string.
To know exactly which phase currently is,
use the generator variable:
output.estimationPhase
This function may be especially helpful, when you need to setup the content of a frameset document generated by a frameset template (see 'Frameset Structure' tab in the frameset template's properties dialog). With the use of this function, you may specify which generated documents should be initially loaded into particular frame windows.
Parameters:
targetKey
targetKeys
Each hypertarget is identified with a number of keys which may be objects of any type.
The keys are generated automatically for each hypertarget during the
estimation phase
by the FlexQuery expressions specified in hypertarget definitions within the properties
of template components. The hypertarget keys are tested for equality using
the Java Object.equals()
method.
A hypertarget is considered matching to the specified keys when each key has a separate equal pair among the hypertarget's keys. In the case, a two specified keys are equal, they should match to different hypertarget's keys (that is, if the specified keys include "one", "one", the matching hypertarget should also contain two keys "one", "one").
strict
true
, in addition to the matching condition mentioned
above, the hypertarget should have no other keys besides those matching to the
specified ones.
If not specified, the parameter is assumed to be false
.
See Also:
hyperTargetExists(),
documentByTemplate(),
Array(),
output.estimationPhase
generator variable.
String documentByTemplate(String templateNames)
Returns the absolute path name of the first document file which was (or will be) produced by the specified template (or a list of templates). If such a document does not exist (i.e. neither of the specified templates will ever produce any document), the function returns an empty string.
This function returns the correct result only during the generation phase (even though the interested document may not have been physically generated yet). During the estimation phase, the function will always return an empty string.
To know exactly which phase currently is,
use the generator variable:
output.estimationPhase
This function may be especially helpful, when you need to setup the content of a frameset document generated by a frameset template (see 'Frameset Structure' tab in the frameset template's properties dialog). With the use of this function, you may specify which generated documents should be initially loaded into particular frame windows.
Parameter:
templateNames
Each specified template name should be the pure name of the template file. This is just the last name in the pathname's name sequence without extension (i.e. without ".tpl" suffix).
The function returns the pathname of the document which is generated the first by one of the specified templates during the whole generation session.
See Also:
documentByHyperTarget(),
output.estimationPhase
generator variable.
Example 1
The following call will return the pathname of the document file which is generated the first
either by 'overview-summary.tpl'
template or 'class.tpl'
template:
Let's see where it is needed. Suppose, we construct a set of templates which can generated a framed documentation by a number of classes or a single class. Our documentation may contain detailed documents for each class (generated bydocumentByTemplate("overview-summary;class")
class.tpl
) plus a single
overview summary document for all classes (generated by overview-summary.tpl
).
Now, we want our documentation to display the summary document only when there are more than one documented classes (otherwise, the summary will contain just one item and will be redundant). If only one class documented, we would like to see its details immediately.
To achieve this, we construct/call the overview-summary.tpl
in such
a way that it will never produce any output when less than 2 classes are processed.
Then, the documentByTemplate()
call specified above would setup
the main frame window as needed.
Example 2
Suppose, the template 'all-diagram-index.tpl'
is designed to produce
a single document with an index of all diagrams in our documentation.
We have constructed that template so that it never produces anything if there are
no diagrams to be documented.
Now, in some other document, we would like to have a link to that diagram index, so we could invoke the index when we click on that link. However, in addition to that, we do not want the text of that link to appear when there is no index document!
Here is how this problem could be solved. We just need to specify in the component generating the link the following Enabling Condition:
documentByTemplate("all-diagram-index") != ""
String dup(String s, Number num)
Returns a string made of the specified string repeated num
number of times.
If num
<= 0, an empty string is returned.
Example:
will return:dup("blah-", 3)
"blah-blah-blah-"
String echo(String s)
This function prints the argument it received into the standard system output and then returns the argument as the function result.
Effectively, it does nothing, but it may be helpful when debugging templates.
Object elementAt(Object[] a, Number index)
Returns the element of the Array at the specified index.
If the index
is negative or not less than the Array length
then null
is returned.
Tip:
You may call this function in a method-like style:
a.elementAt(index)
Object elementAt(Vector a, Number index)
Returns the element of the Vector at the specified index.
If the index
is negative or not less than the current Vector size
then null
is returned.
Tip:
You may call this function in a method-like style:
v.elementAt(index)
Boolean endsWith(String str, String suffix) Boolean endsWith(String str, Object[] suffixes)
Tests if the specified string ends with the specified suffix (or one among several specified suffixes).
Parameters:
str
suffix
suffixes
true
if the string ends with at least one of them.
You may call this function in a method-like style:
str.endsWith(suffix)
Object execSubquery(String expr)Executes a subquery expression specified in the function parameter and returns the result returned by the subquery.
The specified subquery is executed as if it was inserted in place of the function call. You may use within the subquery any other variables assigned within the calling expressions before the call of this function.
You may use this function to construct necessary queries dynamically. (For instance, you may adjust the behavior of some subtemplate via passing to it a single compact subexpression testing some external condition instead of passing an equivalent batch of parameters representing that condition and then sorting them out using some cumbersome expression statically specified within that subtemplate.)
Note: The subquery expression is compiled dynamically within the implementation of this function. Thus, there is no way to check it before execution. Syntax errors within the subquery will cause an exception during the execution of this function. You may write and check the subquery separately using the Subexpression Editor and, then, insert it as string into the main expression.
Example:
The following expression is an Element Iterator filter specified within some subtemplate:
This filter has a static part (testing whether the value of thegetAttrStringValue("$shapeType") != "Note" && (getStringParam("nodeFilter") == "" || execSubquery(getStringParam("nodeFilter")).toBoolean())
'$shapeType'
attribute is not equal "Note"
) and may include a dynamic part passed
via the template parameter 'nodeFilter'
.
Enumeration filterElements(Enumeration elementEnum, String targetElementTypes, String filterExpr)
This function receives the specified enumeration of elements
(i.e. GOMElement
objects) and from those of them
which satisfy the specified conditions forms another enumeration
returned as the function result.
The initial element ordering is preserved.
Parameters:
elementEnum
filterExpr
When specified, this subquery is executed for each tested element.
If the subquery returns true
, the element is included in the result
enumeration.
The tested element is accessible within the subquery as the generator's
context element
(via contextElement
variable).
The previous context element is overshadowed (it is restored again after this function finishes).
However, you may use within the filtering subquery any other variables assigned within the calling expressions before the call of this function. (Using this, you may pass into the filtering subquery the previous context element, if you need.)
Note: The filtering subquery is compiled dynamically within the implementation of this function. Thus, there is no way to check it before execution. Syntax errors within the subquery will cause an exception during the execution of this function. You may write and check the filtering subquery separately using the Subexpression Editor and, then, insert it as string into the main expression.
Example:
This expression returns an enumeration of those elements contained in the source enumerationclassName = getAttrStringValue("name"); e.filterElements("Method", "getAttrStringValue('class') == className");
'e'
'Method'
Element Type;'class'
attribute has a value equal to the value
of the 'name'
attribute of the generator's current
context element.GOMElement findElementById(Object elementId)
Finds an element by the specified element unique identifier.
If no element with such an identifier exists in the current
DSM (Data Source Model),
the function returns null
.
See Also:
findElementsByIds(),
getElementIds(),
GOMElement.id
Enumeration findElementsByIds(Object[] elementIds)
Finds elements by the element unique identifiers contained in the specified array and returns the enumeration of the found elements.
Effectively, this function does the same as the following Java code would do:
Vector v = new Vector(); for (int i = 0; i < elementIds.length; i ++) { GOMElement element = findElementById(elementIds[i]); if (element != null) v.add(element); } return v.elements();
See Also:
findElementsById(),
getElementIds(),
GOMElement.id
GOMElement findElementByKey(Object elementMapId, Enumeration elementEnum, String keysExpr, Object key)
This function effectively does the same as the following call:
That is, it returns the first element of the enumeration returned by the similar call offindElementsByKey (elementMapId, elementEnum, keysExpr, key).nextElement()
findElementsByKey()
function.
However, calling findElementByKey()
will work somewhat faster.
So, if your element hash-map is not supposed to index multiple elements
with the same key (or you always need only one element per a request),
using this function will be preferable.
For more details, see description of
findElementsByKey()
function.
Enumeration findElementsByKey(Object elementMapId, Enumeration elementEnum, String keysExpr, Object key)
If you are going to process data sources with a large number of elements, this function might help you to make your templates work faster.
The idea of this function is that when you frequently need to obtain from a large number of elements some collections of them using rather complicated and varying query (which may depend on some external parameters), you may find that in many instances such a query can be actually presented as a composition of two subqueries:
(Of course, such an approach may cost some memory, but given that during processing of a template some of its components may be implicitly executed a lot number of times, this will pay off and may considerably boost the generator performance.)
The FlexQuery engine incorporates an implementation of that idea provided
via the findElementsByKey()
function.
We shall show how it can be used in the example below.
But first, let's look into the function parameters.
Parameters:
elementMapId
FlexQuery engine is able to maintain a lot of such hash-maps. So, they themselves are stored in a hashtable and accessed via certain keys.
Therefore, any object representing a hash-map identifier should be good enough
to be used as a hash-key. That is, it should have appropriately implemented method
Object.hashCode()
in the implementing Java class. The simple data types
(like String
and Number
) do satisfy this. However,
in certain situations, it might be tricky to find how to express a hash-map identifier
in the form of a simple data type object. (Normally, this would involve writing
some complicated expression that converts everything that identifies a hash-map
into a single long string.)
The HashKey()
function provides
a way to solve this problem.
Using it, you can create a compound hash-key object which encloses several
simple ones.
For example, suppose you need to maintain a lot of hash-maps each of which is connected with a certain element and identified with the element's ID plus a "some-methods" string (that's because you may also have a similar set of hash-maps connected with the same elements but representing "some-fields" instead). Then, you can create identifiers for those hash-maps using the following call:
HashKey(element.id, "some-methods")
elementEnum
This enumeration should provide just those elements which might be produced with some "heavy" query, as described above. Now, you may wonder, how does any optimization happen here, if as a function parameter, that enumeration should be generated every time the function call is executed?
Actually, that's not the case. Here's how it works.
FlexQuery processor treats each parameter in a function call as a separate subexpression. Those parameter subexpressions are compiled into separate subqueries. When a function is called, the parameter subqueries are not automatically executed before the call. Instead, they are passed to the function implementation. So, it is the function implementation where the parameter subqueries are actually executed and the parameter values are obtained.
The findElementsByKey()
function is implemented so that
elementMapId
parameter and searches
the corresponding hash-map.elementEnum
parameter subquery
is executed and the new hash-map is created.
That means, the generation of elementEnum
enumeration should be specified
entirely within the parameter subexpression. For example, the call
will work differently (and presumably faster) rather than the expression:findElementsByKey (element.id, element.findElementsByLPath("Field"), ...)
Although, the returned result will be the same.e = element.findElementsByLPath("Field"); findElementsByKey(element.id, e, ...)
keysExpr
When the hash-map is created, this subexpression is executed for each element included in the hash-map and should return an object which will be treated as the element's key.
The keys-subexpression may also return an array of different objects all of which will also be treated as the element's keys. In that case, the element will be presented in the hash-map by several keys simultaneously.
The element is accessible within the keys-subexpression as
the generator's context element
(via the contextElement
variable).
The previous context element is overshadowed at that moment
(it is restored after this function finishes).
You may also use within the keys-subexpression any other variables assigned
within the calling expressions before the call of this function.
Notes:
elementEnum
, the parameter keysExpr
is processed only when a new hash-map is created (see description of the
elementEnum
parameter).key
Example:
The following example was taken from the real template -- the class.tpl
template included in the DocFlex/Javadoc.
The task was the following:
For an element representing a Java interface, we need to obtain all Java classes implementing that interface.
The list of interfaces implemented by a class includes:
Using the findElementsByKey()
function provides a necessary solution.
Here's how this can be done:
If the interested interface is presented by thefindElementsByKey ( "All Known Implementing Classes", findElementsByLPath (mainContext.rootElement, "classes^::ClassDoc[! getAttrBooleanValue('isInterface')]"), 'getElementIds( findElementsByLRules ( Array ( LocationRule ("* -> interfaces^::ClassDoc", true), LocationRule ("* -> superclass^::ClassDoc", true) ), "ClassDoc", "getAttrBooleanValue(\'isInterface\')" ) )', interfaceElement.id );
interfaceElement
element,
this call will return all classes implementing that interface.
Here's the explanation for all parameters:
(1) |
"All Known Implementing Classes" This specifies the hash-map identifier. It's just a string since that hash-map is the only one for the whole generation session. |
(2) |
findElementsByLPath (mainContext.rootElement, "classes^::ClassDoc[! getAttrBooleanValue('isInterface')]") This provides an enumeration of all classes in the project. |
(3) |
'getElementIds( findElementsByLRules ( Array ( LocationRule ("* -> interfaces^::ClassDoc", true), LocationRule ("* -> superclass^::ClassDoc", true) ), "ClassDoc", "getAttrBooleanValue(\'isInterface\')" ) )' This is a keys-subexpression which returns an array of the unique identifiers of all interfaces implemented by a given class. Those identifiers will be the keys associated with the class element in the hash-map. |
(4) |
interfaceElement.id Specifies the key. This is just the unique identifier of the element representing the interface for which we want to know all classes implementing it. |
You may use the findElementsByKey()
function to optimize processing
of some Element Iterator
sections in your templates.
Some template components (and especially template sections) may be partially executed by the generator a lot of times with practically the same context parameters. This allows the generator to know whether certain components would have any output in the given context. (Generally, this is needed to fulfill some non-procedural capabilities presented in DocFlex template.)
If some of the Element Iterators
in your templates are specified so they collect the iterated elements using some complicated
Location Rules
whose processing may involve massive internal calculations, you may dramatically
improve performance of your templates by switching those Element Iterators
to use the findElementsByKey()
function.
What you will need, in that case, is to rewrite the element collecting settings
specified in those
Element Iterators
in the form of findElementsByKey()
function calls (like the one shown in the example). Then, in each the Element Iterator's
properties you should specify the "Custom" Element Collecting Method
in the 'Iteration Scope' tab and fill in the 'Expression for Element Enumeration'
field the findElementsByKey()
function call you prepared.
For more details about those settings, see documentation: Element Iterator (details) | Specifying Element Iteration Scope | Custom.
See Also:
HashKey(),
findElementByKey(),
findElementsByLRules(),
findElementsByLPath()
GOMElement
findElementByLPath(GOMElement contextElement, String lpath)GOMElement
findElementByLPath(String lpath)
Finds elements by the specified
Element Location Path
interpreted against the specified context element and returns the first of the found elements.
If no elements found, the function returns null
.
Effectively, this function does the same as one of the following calls (although, it will work faster):
orfindElementsByLPath(contextElement, lpath).nextElement()
findElementsByLPath(lpath).nextElement()
See Also:
findElementsByLPath(),
nextElement()
Enumeration findElementsByLPath(GOMElement contextElement, String lpath) Enumeration findElementsByLPath(String lpath)
Finds elements by the specified Element Location Path interpreted against the specified context element and returns an enumeration of the found elements.
Parameters:
contextElement
If this parameter is not specified, the Location Path will be interpreted against the generator's context element, which is the same as the call:
contextElement.findElementsByLocationPath(lpath)
See Also: GOMContext.contextElement
lpath
Use Location Path Builder to quickly construct a Location Path needed for this parameter.
You may call this function in a method-like style, e.g.:
element.findElementsByLocationPath(lpath)
Location Paths Reference
Location Paths are expressions similar to the expression of XPath. Each Location Path has the following structure:
Step1 / Step2 / ... / StepN
The Location Paths which specify the search of elements are called Element Location Paths. They consist of only Element Location Steps.
Those specifying the search of attributes are called Attribute Location Paths.
The steps from Step1
to StepN-1
of an Attribute Location Path
are also Element Location Steps. However, the last step is an Attribute Location Step (see below).
Each Element Location Step may have the following structure:
axis :: ETs [filter]
where
axis
- Specifies a search axis -- i.e. a subset of the element tree from which the elements are collected at the particular step. DocFlex supports the following axes:
Axis Description child
Includes children of the step's context node. This axis is used by default (i.e. when no axis::
prefix is specified at the location step).self
Includes only the step's context node itself child-or-self
Includes the step's context node and all its children descendant
Includes all descendants of the step's context node (i.e. its children, children of the children and so on) descendant-or-self
Includes the step's context node and all its descendants attribute^
This is the link-axis, which is an extension of the XPath introduced by DocFlex. It contains those elements of the whole DSM (Data Source Model) whose IDs (unique identifiers) are the values of the specified attribute
of the step's context node.See Also:
GOMElement.id
ETs
- Specifies one or several matching Element Types. Each element, to be included in the step's result set, should conform to at least one of the specified matching Element Types.
The list of the matching Element Types can be defined:
- As a single Element Type name.
- As the following expression:
where each(ET1 | ET1 | ... | ETn)
ET
is an Element Type name.- As an asterisk (
*
), which allows to include all elements regardless of their typefilter
- This is a boolean FlexQuery-expression which defines the subquery for the location step filter.
When specified this subquery is executed for each element to be included in the step's result set. An element is included in the result set only when the subquery returns
true
.The tested element is accessible within the subquery as the generator's context element (via
contextElement
variable). The previous context element is overshadowed (it is restored again after the Location Path processing is finished).Note: The filtering subquery is compiled dynamically within the implementation of this function. Thus, there is no way to check it before execution. Syntax errors within the subquery will cause an exception during the processing of the Location Path.
Each Attribute Location Step has the following structure:
@attribute
where attribute
is the name of the searched attribute.
The Attribute Location Paths are normally used to collect values of
the same attribute by a number of elements at once.
Compound Location Paths
You may join several Location Paths using '|' delimiter into a single expression:
lpath1 | lpath2 | ... | lpathN
Such an expression, called Compound Location Path, is interpreted by
consecutive interpretation of the Location Paths contained in it.
The result is a union of elements or attributes produced by each constituent
Location Path.
See Also:
findElementByLPath(),
findElementsByLRules(),
getValuesByLPath()
Examples:
The following expression counts those children of the generator's current context element, which are instances of 'Class' Element Type:
count (findElementsByLPath ("Class"))
This expression was taken from the real template:
It returns all those elements:findElementsByLPath (rootElement, "classes^::ClassDoc [getAttrBooleanValue('isInterface')]")
true
Enumeration findElementsByLRules(GOMElement contextElement, Object[] locationRules, String targetElementTypes, String filterExpr) Enumeration findElementsByLRules(Object[] locationRules, String targetElementTypes, String filterExpr)
This function provides even more powerful way of collecting elements within
DSM (Data Source Model)
as compared with the findElementsByLPath()
function.
It allows to collect elements using a whole bunch of
Location Paths
whose processing may be automatically repeated during a single call.
Now, rather a single Location Path, the search of elements is specified using an array of Location Rules. Each Location Rule consists of the following settings:
findElementsByLPath()
function)At first, the rule is tested for compatibility with the context element. That is
If the Enabling Condition specified, it is tested against the context element
(which is temporary made the
generator's context element
and can be accessed within the expression via the
contextElement
variable);
If there are Matching Element Types, the context element is tested if it is an instance of at least one of them.
The whole set of Location Rules is interpreted according to the following steps:
true
(they are called
Recursive Location Rules)
are processed with this element selected as the rule's context element.
The new generated elements are added to the total result set.
This step is repeated until at the previous step no new elements have been produced.
After that, the total result set is filtered according to the list of Target Element Types and the filter expression specified in the function parameters and, then, returned in the form of an enumeration as the function result.
Parameters:
contextElement
If this parameter is not specified, the generator's context element is used by default.
See Also: GOMContext.contextElement
locationRules
LocationRule()
.
See this function for more detail.
Use Location Rule Builder to quickly construct a Location Rule needed for this parameter.
targetElementTypes
filterExpr
When specified, this subquery is executed for each tested element.
If the subquery returns true
, the element is included in the result
enumeration.
The tested element is accessible within the subquery as the
generator's context element
(via the contextElement
variable).
The previous context element is overshadowed (it is restored again after this function finishes).
You may use within the filtering subquery any other variables assigned within the calling expressions before the call of this function.
Note: The filtering subquery is compiled dynamically within the implementation of this function. Thus, there is no way to check it before execution. Syntax errors within the subquery will cause an exception during the execution of this function. You may write and check the filtering subquery separately using the Subexpression Editor and, then, insert it as string into the main expression.
See Also:
LocationRule(),
findElementsByLPath(),
getValuesByLPath()
Example:
As example of usage of findElementsByLRules()
function
(together with Location Rules),
let's consider the following model:
The model describes a certain Java project and may be built of elements of various types. We shall focus on only two Element Types:
Java classes and interfaces have the following relationships:'Class'
-- represents a Java class
'Interface'
-- represents a Java interface
Classes/interfaces may extend other classes/interfaces, which is reflected by the'extends'
attribute in both'Class'
and'Interface'
Element Types.
Classes may also implement certain interfaces, which is reflected by theUsing DTD specification, those attributes may be described as the following:'implements'
attribute in the'Class'
Element Types.
Now, let's we want to collect all interfaces implemented by a certain class. This would include:<!ATTLIST Class extends IDREF> <!ATTLIST Interface extends IDREFS> <!ATTLIST Class implements IDREFS>
'classElement'
parameter:
findElementsByLRule(classElement, Array( LocationRule("* -> extends^::(Class|Interface)", true), LocationRule("Class -> implements^::Interace", true) ), "Interface", null);
DSMElementType findElementType(String name)
Finds an Element Type with a given name.
If not found, returns null
.
See Also:
instanceOf(),
resolveElementType(),
GOMElement.elementType
String firstSentence(String doc)
Return the first sentence of the text contained in the specified string parameter.
The sentence end is determined by calling
java.text.BreakIterator.getSentenceInstance()
method with the default locale. In addition, a line will be terminated by
some embedded HTML tags: <p> </p> <h1> <h2> <h3>
<h4> <h5> <h6> <hr> <pre> or </pre>.
This function is used to obtain an annotation text placed in summary tables.
Vector generateVector(Enumeration source, String subqueryExpr) Vector generateVector(Object[] source, String subqueryExpr) Vector generateVector(Object[] source, String subqueryExpr, Number fromIndex) Vector generateVector(Object[] source, String subqueryExpr, Number fromIndex, Number toIndex) Vector generateVector(Vector source, String subqueryExpr) Vector generateVector(Vector source, String subqueryExpr, Number fromIndex) Vector generateVector(Vector source, String subqueryExpr, Number fromIndex, Number toIndex)
Allows to generate a Vector from elements of another Vector, Array, or Enumeration.
This function iterates by the source's elements and for each one executes
a subquery whose expression is provided in the subqueryExpr
parameter.
The object returned by the subquery is added to the new Vector.
The subquery receives the original element in the _element
variable accessible within it.
Other variables created within the calling expressions (before this function call)
are also accessible within the subquery.
Effectively, this function would be the same as the following block:
However, at the moment,v = Vector(); i = fromIndex; while (i < toIndex && i < source.size()) { _element = source.elementAt(i); newElement = // the subquery operators generating // a new element from _element variable v.addElement(newElement); i = i + 1; } return v;
while
operator is not
supported in FlexQuery expressions, hence the need of this function.
Parameters:
source
subqueryExpr
Note: Since the subquery is compiled dynamically within the implementation of this function, there is no way to check it before execution. You may write and check the subquery separately using the Subexpression Editor and, then, insert it as string into the main expression.
fromIndex
toIndex
Example:
The following script converts a sequence number like "1.2.5.9"
(which initially is simply a string) into a Vector of its subnumbers
having the Number
type:
(This may allow, for instance, to use a Vector representations to compare such sequence numbers according to their subnumbers.)s = getAttrStringValue ("sequenceNumber"); v = breakString(s, "."); generateVector (v, "toNumber(_element)")
GOMAttribute getAttr(GOMElement element, String attrName) GOMAttribute getAttr(String attrName)
Returns a GOMAttribute
object which represents the specified attribute contained in the specified element.
If the element has no attribute with the given name, null
is returned.
GOMAttribute
type provides the most complete information about a particular
attribute, which is obtained dynamically both from the
DSM (Data Source Model)
representing the current data source and the
DSM Type providing the data type
information about the whole class of data sources this template was designed for.
You may rarely need using this function. If the only what you need is to obtain
a value of a particular attribute,
use getAttrValue()
or
getAttrValues()
functions instead.
Parameters:
element
getAttr(contextElement, attrName)
attrName
Note: Some DSM Types may support pseudo- (or formula-) attributes. Such attributes are specified with the FlexQuery expressions which calculate the attributes' values from another (real) attributes, possible with the use of some functions.
Pseudo-attributes are treated the same way as the normal ones. (That's actually why the pseudo-attributes were introduced in the first place). Obtaining a value of a pseudo-attribute will just evoke the internal processing of its formula (therefore, if an error occurred during this, it will be reported accordingly). Externally, accessing pseudo-attributes looks the same as the accessing the normal ones. So does this function.
See Also:
getAttrValue(),
getAttrValues(),
GOMAttribute
Tip:
You may call this function in a more method-like style:
element.getAttr(attrName)
Object getAttrValue(GOMElement element, String attrName) Object getAttrValue(String attrName)
Returns a value of the specified attribute contained in the specified element. In the case, the attribute has multiple values, the function returns the first one.
If the element has no attribute with the given name, null
is returned.
Parameters:
element
getAttrValue(contextElement, attrName)
attrName
Note: Some DSM Types may support pseudo- (or formula-) attributes. Such attributes are specified with the FlexQuery expressions which calculate the attributes' values from another (real) attributes, possible with the use of some functions.
Pseudo-attributes are treated the same way as the normal ones. (That's actually why the pseudo-attributes were introduced in the first place). Obtaining a value of a pseudo-attribute will just evoke the internal processing of its formula (therefore, if an error occurred during this, it will be reported accordingly). Externally, accessing pseudo-attributes looks the same as the accessing the normal ones. So does this function.
See Also:
GOMAttribute.value,
getValueByLPath()
Tip:
You may call this function in a more method-like style:
element.getAttrValue(attrName)
Object[] getAttrValues(GOMElement element, String attrName) Object[] getAttrValues(String attrName)
Returns an array of all values (a vector value) associated with the specified attribute of the specified element. In the case of a single-value attribute, the function returns a single-element array containing the attribute's value.
If the element has no attribute with the given name, an empty array is returned.
Parameters:
element
getAttrValues(contextElement, attrName)
attrName
Note: Some DSM Types may support pseudo- (or formula-) attributes. Such attributes are specified with the FlexQuery expressions which calculate the attributes' values from another (real) attributes, possible with the use of some functions.
Pseudo-attributes are treated the same way as the normal ones. (That's actually why the pseudo-attributes were introduced in the first place). Obtaining a value of a pseudo-attribute will just evoke the internal processing of its formula (therefore, if an error occurred during this, it will be reported accordingly). Externally, accessing pseudo-attributes looks the same as the accessing the normal ones. So does this function.
See Also:
GOMAttribute.values,
getValuesByLPath()
Tip:
You may call this function in a more method-like style:
element.getAttrValues(attrName)
Boolean getAttrBooleanValue(GOMElement element, String attrName) Boolean getAttrBooleanValue(String attrName)
This function works as a shortcut of one of the calls:
getAttrValue(element, attrName).toBoolean()
or
getAttrValue(attrName).toBoolean()
See Also:
getAttrValue(),
toBoolean()
Number getAttrNumberValue(GOMElement element, String attrName) Number getAttrNumberValue(String attrName)
This function works as a shortcut of one of the calls:
getAttrValue(element, attrName).toNumber()
or
getAttrValue(attrName).toNumber()
See Also:
getAttrValue(),
toNumber()
String getAttrStringValue(GOMElement element, String attrName) String getAttrStringValue(String attrName)
This function works as a shortcut of one of the calls:
getAttrValue(element, attrName).toString()
or
getAttrValue(attrName).toString()
See Also:
getAttrValue(),
toString()
Object[] getElementIds(Enumeration elementEnum)
Returns an array containing unique identifiers of the elements contained in the specified enumeration.
This function works as the opposite to the function
findElementsByIds()
.
See Also:
findElementsByIds(),
GOMElement.id
Object getParam(String paramName)
Returns the template parameter
with the specified name.
If there is no parameter with such a name, the function returns null
.
The template parameters should be declared within the template's properties (see Template Properties dialog).
The values of template parameters are represented by instances of the following Java types:
Parameter Type | Representing Java Class |
---|---|
string |
java.lang.String |
number |
java.lang.Number |
boolean |
java.lang.Boolean |
enum |
java.lang.String |
text |
java.lang.String |
object |
java.lang.Object |
getStringParam(),
getNumberParam(),
getBooleanParam()
String getStringParam(String paramName)
This function is a shortcut of the following call:
getParam(paramName).toString()
See Also:
getParam(),
toString()
Number getNumberParam(String paramName)
This function is a shortcut of the following call:
getParam(paramName).toNumber()
See Also:
getParam(),
toNumber()
Boolean getBooleanParam(String paramName)
This function is a shortcut of the following call:
getParam(paramName).toBoolean()
See Also:
getParam(),
toBoolean()
Object getValueByLPath(GOMElement contextElement, String lpath) Object getValueByLPath(String lpath)
Finds elements/attributes by the specified
Location Path
interpreted against the specified context element. As soon as an element/attribute with
a non-null
value found, that value is returned as the function result.
If no such elements/attributes exist, the function returns null
.
Effectively, this function does the same as one of the following calls (although, it will work faster):
orgetValuesByLPath(contextElement, lpath).elementAt(0)
getValuesByLPath(lpath).elementAt(0)
See Also:
getValuesByLPath(),
elementAt()
Object[] getValuesByLPath(GOMElement contextElement, String lpath) Object[] getValuesByLPath(String lpath)
Finds elements or attributes by the specified Location Path interpreted against the specified context element and returns an array containing all values of the found elements or attributes.
Parameters:
contextElement
If this parameter is not specified, the Location Path will be interpreted against the generator's context element, which is the same as the call:
contextElement.getValuesByLocationPath(lpath)
See Also: GOMContext.contextElement
lpath
Use Location Path Builder to quickly construct a Location Path needed for this parameter.
Tip:
You may call this function in a method-like style, e.g.:
element.getValuesByLocationPath(lpath)
See Also:
getValueByLPath(),
findElementsByLPath()
Examples:
This call will return all values ofgetValuesByLPath("link/@boss|link/@workers")
'boss'
and 'workers'
attributes
contained in all 'link'
children of the generator's current
context element.
Object getVar(String name)
CompoundHashKey HashKey(Object subkey1, Object subkey2, ...) CompoundHashKey HashKey(Object[] subkeys)
Creates a compound hash-key from the subkeys specified in the function parameters.
Specifically, it is an object which may serve as a hash-map key identified solely by the subkeys enclosed in it, provided that the subkey objects themselves are good to be used as hash-keys (for example, all simple data types well fit to this condition).
That means the following:
Suppose we have two subkeys: subkey1
and subkey2
.
Then, any Java implementation of compound hash-keys should satisfy the following
conditions:
the underlying Java objects must be equal, i.e.key1 = HashKey (subkey1, subkey2); key2 = HashKey (subkey1, subkey2);
should always returnkey1.equals(key2)
true
.
Object.hashCode()
method should be implemented
so that the returned value is derived from the values of the enclosed subkeys
(at best, it may be produced from the values returned by
subkey1.hashCode()
and subkey2.hashCode()
calls).
Parameters:
Two or more separately specified subkeys or an array of subkeys.
Example:
Tip:HashKey (classElement.id, "overridden-methods")
Currently, the main purpose of this function is to use it with the
findElementsByKey()
function (see its description).
Boolean hyperTargetExists(Object targetKey) Boolean hyperTargetExists(Object[] targetKeys) Boolean hyperTargetExists(Object[] targetKeys, Boolean strict)
Allows to determine, if a hypertarget with the specified set of keys exists somewhere in the whole generated documentation.
This function returns the correct result only during the
generation phase.
During the estimation phase,
it always returns false
.
To know exactly which phase currently is,
use the generator variable:
output.estimationPhase
Note: Be careful when using this function (especially, within enablings conditions of template components and filtering expressions)! Incorrect use may cause the following side effects:
The hypertargets defined within the affected components may be generated incorrectly (therefore, hyperlinks targeted to them may never be generated).
If such components include Element Iterators or call Element Iterators from themselves, the generation progress bar may be distorted (which may result in a premature filling it up or, vice versa, filling only part of it when the generation is actually about to finish).
targetKey
targetKeys
Each hypertarget is identified with a number of keys which may be objects of any type.
The keys are generated automatically for each hypertarget during the
estimation phase
by the FlexQuery expressions specified in hypertarget definitions within the properties
of template components. The hypertarget keys are tested for equality using
the Java Object.equals()
method.
A hypertarget is considered matching to the specified keys when each key has a separate equal pair among the hypertarget's keys. In the case, a two specified keys are equal, they should match to different hypertarget's keys (that is, if the specified keys include "one", "one", the matching hypertarget should also contain two keys "one", "one").
strict
true
, in addition to the matching condition mentioned
above, the hypertarget should have no other keys besides those matching to the
specified ones.
If not specified, the parameter is assumed to be false
.
See Also:
documentByHyperTarget(),
Array(),
output.estimationPhase
generator variable.
Number indexOf(String str, String search) Number indexOf(String str, String search, Number fromIndex)
Returns the index within the specified string of the first occurence of the specified substring, starting at the specified index.
Parameters:
str
search
fromIndex
See Also:
lastIndexOf()
Tip:
You may call this function in a method-like style, e.g.:
str.indexOf("blah", 5)
Number indexOf(Object[] a, Object obj) Number indexOf(Object[] a, Object obj, Number fromIndex)
Returns the index within the specified Array of the first occurence of the
given object, starting at the specified index, and testing for equality using the
Java java.lang.Object.equals()
method.
Returns -1 if the object is not found.
Parameters:
a
obj
fromIndex
See Also:
lastIndexOf()
Tip:
You may call this function in a method-like style:
a.indexOf(obj, fromIndex)
Number indexOf(Vector a, Object obj) Number indexOf(Vector a, Object obj, Number fromIndex)
Returns the index within the specified Vector of the first occurence of the
given object, starting at the specified index, and testing for equality using the
Java java.lang.Object.equals()
method.
Returns -1 if the object is not found.
Parameters:
v
obj
fromIndex
See Also:
lastIndexOf()
Tip:
You may call this function in a method-like style:
v.indexOf(obj, fromIndex)
Boolean instanceOf(GOMElement element, String elementTypeName) Boolean instanceOf(String elementTypeName)
Tests if the specified element is an instance of the specified Element Type.
Note: Since in some DSM Types
(Data Source Models), there is no direct inherent association between elements and
Element Types.
Testing if an element conforms to a certain Element Type can be made much quicker
than finding the exact Element Type associated with this element.
Use this function instead of the
GOMElement.elementType
property, when the only you need is to test whether the element
is of a particular Element Type.
Parameters:
element
contextElement.instanceOf(elementTypeName)
elementTypeName
If no such an Element Type exists, the function will return false
.
See Also:
resolveElementType(),
findElementType(),
GOMElement.elementType
Tip:
You may call this function in a method-like style, e.g.:
element.instanceOf("UseCase")
Boolean instanceOfClass(Object obj, String className)
Tests whether the specified object is an instance of the specified Java class.
Parameters:
obj
className
Tip:
You may call this function in a method-like style:
Example:obj.instanceOfClass(className)
The following expression
tests whether the value of the template parametergetParam("v").instanceOfClass("java.util.Vector")
"v"
is
an instance of java.util.Vector
class.
Number lastIndexOf(String str, String search) Number lastIndexOf(String str, String search, Number fromIndex)
Searches the string backwards for the specified substring, starting from the specified index, and returns an index to it.
Returns -1 if the substring is not found.
Parameters:
str
search
fromIndex
str.len()-1
is assumed.
See Also:
indexOf()
Tip:
You may call this function in a method-like style, e.g.:
str.lastIndexOf(".")
Number lastIndexOf(Object[] a, Object obj) Number lastIndexOf(Object[] a, Object obj, Number fromIndex)
Searches the Array backwards for the specified object, starting from the specified index,
and returns an index to it.
The object equality is tested using the Java java.lang.Object.equals()
method.
Returns -1 if the object is not found.
Parameters:
a
obj
fromIndex
See Also:
indexOf()
Tip:
You may call this function in a method-like style:
a.lastIndexOf(obj, fromIndex)
Number lastIndexOf(Vector a, Object obj) Number lastIndexOf(Vector a, Object obj, Number fromIndex)
Searches the Vector backwards for the specified object, starting from the specified index,
and returns an index to it.
The object equality is tested using the Java java.lang.Object.equals()
method.
Returns -1 if the object is not found.
Parameters:
v
obj
fromIndex
See Also:
indexOf()
Tip:
You may call this function in a method-like style:
v.lastIdexOf(obj, fromIndex)
Number len(String s)
Returns the length of the specified string.
Tip:
This function may be called in a method-like style:
s.len()
Number length(Object[] a)
Returns the number of elements in the array.
Tip:
This function may be called in a method-like style:
a.length()
Object LocationRule(String ruleSpec, Boolean recursive) Object LocationRule(String ruleSpec, Boolean recursive, String enablingCondExpr)
This function is used to specify parameters for the
findElementsByLRules()
function.
It creates a Location Rule Definition object which
is a specification of a Location Rule.
Each Location Rule specification includes the following settings:
findElementsByLRules()
function for more details about these settings.
Use Location Rule Builder
to quickly construct a Location Rule
instantly encoded as a LocationRule()
function call.
Parameters:
ruleSpec
The left part (before arrow) specifies the list of Matching Element Types. The asterisk (* -> lpath
ET -> lpath
(ET1 | ET2 | ... | ETn) -> lpath
*
) means the rule matches to any Element Type.
The right part (after arrow) specifies the Element Location Path.
See findElementsByLPath()
function for more information about Location Paths.
recursive
findElementsByLRules()
for more details.
enablingCondExpr
true
.)
The tested element is accessible within the subquery as the
generator's context element
(via the contextElement
variable).
The previous context element is overshadowed (it is restored after the subquery processing finished).
You may use within the subquery any other variables assigned within the calling expressions before
the call of this function.
Note: The Enabling Condition subquery is compiled dynamically within the implementation of this function. Thus, there is no way to check it before execution. Syntax errors within the subquery will cause an exception during the execution of this function.
See Also:
findElementsByLRules(),
findElementsByLPath()
Example:
See discussion about this particular Location Rule at the "Example" section of the description forLocationRule("* -> extends^::(Class|Interface)", true)
findElementsByLRules()
function.
Object max(Object o1, Object o2)
This function is a shortcut of the following expression:
See Also:compare(o1, o2) >= 0 ? o1 : o2;
compare()
Object maxElement(Object[] a) Object maxElement(Vector v)
Returns the maximum element of the given Array or Vector,
according to the comparison rules described in
compare()
function.
See Also:
compare()
Tip:
You may call this function in a method-like style:
a.maxElement() v.maxElement()
String mergeStrings(Object[] strings, String delimiter) String mergeStrings(Vector strings, String delimiter)
Creates a new string made of fragments contained in the specified Vector or Array
and delimited with the substring specified in the delimiter
parameter.
Parameters:
strings
The Array's or Vector's elements are not required to be String objects.
Actually, what is taken from each element is the string returned by the call
element.toString()
.
If an element is null
, it is simply ignored.
delimiter
See Also:
breakString()
Examples:
The following expression
will return string:a = Array ("Vini", "vidi", "vici"); mergeStrings (a, " -> ");
The call"Vini -> vidi -> vici"
will return:mergeStrings (Vector (1,2,3), ",");
"1,2,3"
Object min(Object o1, Object o2)
This function is a shortcut of the following expression:
See Also:compare(o1, o2) <= 0 ? o1 : o2;
compare()
Object minElement(Object[] a) Object minElement(Vector v)
Returns the minimum element of the given Array or Vector,
according to the comparison rules described in
compare()
function.
See Also:
compare()
Tip:
You may call this function in a method-like style:
a.minElement() v.minElement()
Object nextElement(Enumeration e)
Returns the next element of the enumeration.
If the enumeration contains no more elements, returns null
.
Tip:
You may also call this function in a method-like style:
e.nextElement()
Vector removeElement(Vector v, Number index)
Removes the element at the specified position in the Vector. Returns the same Vector object.
This function does nothing if the specified index is < 0 or >= the Vector size.
Tip:
This function may be called in a more method-like style:
v.removeElement(0)
String replace(String s, String oldSubstr, String newSubstr)
Returns a new string that is the specified string in which
all occurences of oldSubstr
are replaced with the newSubstr
.
Tip:
You may call this function in a method-like style:
Examples:s.replace(oldSubstr, newSubstr)
"java.lang.Object".replace(".", "/")
returns"java/lang/Object"
"Vini, vidi, vici".replace(",", " ->")
returns"Vini -> vidi -> vici"
DSMElementType resolveElementType() DSMElementType resolveElementType(GOMElement element) DSMElementType resolveElementType(GOMElement element, String elementTypeNames) DSMElementType resolveElementType(String elementTypeNames)
Finds an Element Type associated with the given element.
When the element suits to several Element Types having inheritance relationship (if supported by the underlying DSM Type), this function finds the best suited Element Type (i.e. the lowest heir).
Parameters:
element
contextElement.resolveElementType(..)
)
elementTypeNames
This may speed up the search of the appropriate Element Type. For instance, if the provided name is of a top-level Element Type known to suit this element, the search will start from this type and descend to the best suited its heir.
See Also:
instanceOf(),
toElement(),
findElementType(),
GOMElement.elementType
String resolveURL(String spec, String contextURL)
Vector reverseVector(Vector v)
Reverses the order of the elements in the specified Vector.
Returns the same Vector object (whose elements are reversed). No new Vector object is created!
Object setVar(String name, Object value)
Number size(Vector v)
Returns the number of elements in the Vector.
Tip:
This function may be called in a method-like style:
v.size()
Boolean startsWith(String str, String prefix) Boolean startsWith(String str, String prefix, Number toffset) Boolean startsWith(String str, Object[] prefixes) Boolean startsWith(String str, Object[] prefixes, Number toffset)
Tests if the specified string starts with the specified prefix (or one among several specified prefixes) beginning a specified index.
Parameters:
str
prefix
prefixes
true
if the string starts with at least one of them.
tooffset
Tip:
You may call this function in a method-like style, e.g.:
str.startsWith("blah", 5)
String substring(String s, Number beginIndex) String substring(String s, Number beginIndex, Number endIndex)
Returns a new string that is a substring of the specified string.
The substring begins at the specified beginIndex
and extends to the character
at index endIndex-1
. Thus the length of the substring is endIndex-beginIndex
.
Parameters:
s
beginIndex
endIndex
s.length()
is assumed.
You may call this function in a method-like style:
Examples:s.substring(beginIndex, endIndex)
"hamburger".substring(4, 8)
returns"urge"
"smiles".substring(1, 5)
returns"mile"
Object[] toArray(Object obj)
Converts a specified object to Array according to the following rules:
If obj
is already an Array object
(i.e. an instance of java.lang.Object[]
),
the function works simply as a type cast operator,
same as it would be in Java: (Object[]) obj
If obj
is an Enumeration, the function returns an Array
produced from the Enumeration's elements.
If obj
is instance of java.util.Collection
Java class
(which also includes a Vector),
the returned Array is created as: ((Collection) obj).toArray()
If obj
is instance of java.util.Map
Java class,
the returned Array is created as: ((Map) obj).values().toArray()
If obj
is null
, an empty Array is returned
At last, if obj
is neither of the above, the function returns
a single-element Array with this object as the only element.
You may call this function in a more method-like style:
obj.toArray()
Boolean toBoolean(Object obj)
Converts a specified object to Boolean type according to the following:
If obj
is already a Boolean object
(i.e. an instance of java.lang.Boolean
),
the function works simply as a type cast operator,
same as it would be in Java: (Boolean) obj
If obj
is not null
and obj.toString().toLowerCase()
returns "true"
, "yes"
or "on"
,
then the function returns true
.
In all other cases, the function returns false
You may call this function in a more method-like style:
obj.toBoolean()
GOMElement toElement(Object obj) GOMElement toElement(Object obj, String elementTypeNames)
Converts an object to the GOMElement
type.
Initially, the object should be either
GOMElement
or
DSMElement
.
Otherwise, the function returns null
.
Parameters:
obj
elementTypeNames
resolveElementType()
function.
See Also:
resolveElementType(),
instanceOf()
Tip:
You may call this function in a more method-like style, e.g.:
obj.toElement() obj.toElement("UseCase")
Enumeration toEnum(Object obj)
Converts a specified object to Enumeration according to the following rules:
If obj
is instance of java.util.Enumeration
Java class,
the function works simply as a type cast operator,
same as it would be in Java: (Enumeration) obj
If obj
is a Vector or an Array, the function returns
the Enumeration of its elements.
If obj
is instance of java.util.Hashtable
Java class,
the returned Enumeration is produced as: ((Hashtable) obj).elements()
If obj
is null
, the null
is returned
At last, if obj
is neither of the above, the function returns
a single-element Enumeration containing just this object.
You may call this function in a more method-like style:
obj.toEnum()
String toLowerCase(String s)
Returns the specified string, converted to lowercase.
Tip:
This function may be called in a method-like style:
s.toLowerCase()
Number toNumber(Object obj)
Converts a specified object to Number according to the rules:
If obj
is already a Number object
(i.e. an instance of java.lang.Number
),
the function works simply as a type cast operator,
same as it would be in Java: (Number) obj
If obj
is not null
, the function tries to parse the
string returned by obj.toString()
call as integer, fixed-point or floating-point
decimal number value.
If the string is successfully parsed, the result Number object is returned.
If the string does not contain a parsable number or
obj
parameter is null
, the function returns 0
.
You may call this function in a more method-like style:
obj.toNumber()
String toString(Object obj)
Converts a specified object to String according to the following:
If obj
is already a String object
(i.e. an instance of java.lang.String
),
the function works simply as a type cast operator,
same as it would be in Java: (String) obj
If obj
is null
, an empty string is returned
In all other cases, the function returns result of a Java call obj.toString()
You may call this function in a more method-like style:
obj.toString()
String toString(Object[] a, String delimiter)
This function is a synonym for
mergeStrings()
function.
See Also:
mergeStrings(),
breakString()
String toUpperCase(String s)
Returns the specified string, converted to uppercase.
Tip:
This function may be called in a method-like style:
s.toUpperCase()
Vector toVector(Object obj)
Converts a specified object to Vector according to the following rules:
If obj
is already a Vector object, the function returns just it
so its type becomes specified for further operations.
This is similar to Java type cast operator: (Vector) obj
If obj
is an Array, the function returns a Vector
containing elements of that array.
If obj
is an Enumeration, the function returns a Vector
produced from the Enumeration's elements.
If obj
is instance of java.util.Collection
Java class,
the returned Vector is created as: new Vector((Collection) obj)
If obj
is instance of java.util.Map
Java class,
the returned Vector is created as: new Vector(((Map) obj).values())
At last, if obj
is neither of the above, the function returns
a Vector with this object as the only Vector element.
You may call this function in a more method-like style:
obj.toVector()
String trim(String s)
Returns the specified string with white space removed from the front and end.
Tip:
This function may be called in a method-like style:
s.trim()
Vector Vector(...)
This function creates a Vector from the elements passed in the function
parameters. The number of parameters may be from zero to unlimited.
The underlying Java object representing the Vector is an instance of
java.util.Vector
class.
Examples:
The following call creates an empty Vector (same as in Java: new Vector()
):
The following creates a Vector of three Number objects:Vector()
This creates a Vector of three String objects:Vector(1,2,3)
Vector("1","2","3")