DocFlex Technology - Documentation - Element Iterator (details)

1. Location Paths
2. Collecting Elements by Location Rules
3. Recursive Location Rules
4. Specifying Element Iteration Scope
   • Simple Location Rules
   • Advanced Location Rules
   • Sequence
   • Custom
5. Sorting Element Iteration Scope
   • none (original order)
   • reverse original order
   • by element attribute
   • by element name
   • by element name
   • by compound key

1.  Location Paths

Location Paths are the expressions similar to XPath, which are used in DocFlex templates to specify the search of the elements or the attributes.

Although eventually they are string, during designing the templates in the DocFlex Template Designer, the Location Paths are normally not needed to enter directly. Instead, they are constructed using special dialogs or can be selected in the Location Path Chooser, like the one shown on this screenshot:

Each Location Path is interpreted relatively to a certain selected element (context node), which normally is the generator's context element. As the result of such an interpretation, a set of elements (Element Location Paths) or attributes (Attribute Location Paths) is generated.

The structure of each Location Path used in DocFlex is the same as that of XPath and looks as the following:

Step1 / Step2 / ... / StepN

where

Step1, ..., StepN-1

Element Location Steps

StepN

Element Location Step or Attribute Location Step

Each Location Path is interpreted by the successive interpretation of the Location Steps defined in it. During the interpretation of each step, an intermediate set of the DSM's nodes is collected. That set is called the step's result set. The result set of the last step becomes the result of the whole Location Path interpretation. When a certain step produces an empty set, so will be the result of the whole Location Path.

Each Location Step is always interpreted relatively to a certain its own context node (i.e. an element) according to the rules:

1. The Step1 is interpreted relatively to the Location Path's initial context node.
2. Each StepN that follows is interpreted repeatedly against every element from the result set produced on the previous StepN-1. All new nodes collected during those interpretations form the result set of StepN.

Every Element Location Step has the following structure:

axis :: ETs [filter]

where

axis

Specifies the search axis that is a subset of DSM's nodes from which the step's result set is collected. Currently, DocFlex supports the following axes:

child

Includes children of the step's context node. This axis is used by default (i.e. when no axis:: prefix is specified in 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 axis is an extension of the XPath standard introduced in DocFlex. It includes those elements of the Data Source Model (which is a real or virtual XML-document) whose ID references are the values of the specified context node attribute.

The attribute is the name of a certain context element's attribute (whose type should be either IDREF or IDREFS).

Such a specification is interpreted in the following way.

When the context element contains an attribute with 'attribute' name, all values of that attribute are interpreted as the identifiers of elements that may be contained in the DSM. Each identifier is used to find a corresponding element, and, if found, that element is added to the step's result set.

Example:

elementReference^::ClassDoc

{ expr }

This axis, called formula-axis, is another extension of XPath introduced in DocFlex. It covers functionally all other axes and is, probably, the ultimate axis imaginable.

The elements included in that axis are produced by the FlexQuery expression specified between the curly brackets. The expression should return the enumeration of new elements, which it may produce from the step's context node (the element) passed to the expression as the generator context element (accessible via the contextElement variable).

For example, the step:

child::Person

will do the same as the step:

{ findChildren("Person") }::Person

The real power of the formula-axis is that you can program within the embedded expression any method of finding elements (including finding them using element maps). That profoundly transforms capabilities of the entire search possible to organize using Location Paths!

Note: The expression specified in formula-axis should always return the Enumeration type. Otherwise, the generator will raise an error.

The returned enumeration should contain objects of GOMElement or DSMElement types (objects of other types will be ignored).

The null value returned by the expression will be interpreted as an empty enumeration.

ETs

Specifies one or several matching Element Types. Each element, to be included in the step's result set, should comply with 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.
• The following expression: (ET1 | ET1 | ... | ETn), where each ETn is an Element Type name.
• The asterisk wildcard (*), which will include all elements regardless of their type

filter

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 context element (via the contextElement variable). The previous context element is overshadowed (it is restored again after the Location Path processing is finished).

Each Attribute Location Step has the following structure:

@attribute

Compound Location Paths

lpath1 | lpath2 | ... | lpathN

2.  Collecting Elements by Location Rules

Each Element Location Rule has the following structure:

Matching Element Types → Element Location Path

where

Matching Element Types

the list of Element Types to which this rule is applied. If the rule matches with any element type, the list can be replaced with the wildcard: *

Element Location Path

the Element Location Path specifying the set of the elements produced by the rule

As in the case of template components, for each rule an additional enabling condition can be defined in the form of the boolean FlexQuery-expression.

A set of Element Location Rules is interpreted relatively to a certain context element (which is normally the same as the context element received by the section).

Each Element Location Rule is interpreted in the following way. At first, the rule is tested for compatibility with the context element's type and, in the case it has an enabling condition, if the condition is satisfied (the context element is accessible within the enabling condition expression via the generator's context element variable). If the both tests passed the rule's Element Location Path is interpreted relatively to the context element and a set of new elements produced. These elements are added to the total resulting set of all rules.

Example:

Let's consider the data source that provides the basic information about a Java-project. It can be described with the following DTD:

<!ELEMENT field>
<!ELEMENT method>
<!ELEMENT class (field*,method*,class*)>
<!ELEMENT package (class*,package*)>

Here are the sample Element Location Rules defined for this data source:

1. Collect all classes (including the inner classes) contained both in the context element and in all its descendants:

   * → descendant::class

2. If the context element is a package collect all top-level classes contained both in it and in all its subpackages:

   package → child-or-self::package/child::class

3.  Recursive Location Rules

It can be seen from the description above that the only way to specify searching of elements at the arbitrary depth from the context node is using one of the descendant-axes in the Element Location Path of a rule, and in this way, the search will involve all the context node's subtree at the Element Location Step where a descendant-axis is used.

However, in some situations, it may require to limit the search to only some branches of a subtree. Constructing the Element Location Paths using descendant-axes not always allows to achieve the necessary effect. Even more difficulties arise when searching elements at the arbitrary depth involves using link-axes.

The problem was solved in DocFlex by introduction the Recursive Location Rules.

Recursive Location Rules are the normal Element Location Rules that, in addition, have a special recursive flag . This affects their interpretation.

The set of the Element Location Rules which includes the recursive rules is interpreted according to the following repeatable steps:

Step 1:  All the rules (recursive and not) are interpreted relatively to the context element received by the Element Iterator as described in the previous section. As result, some intermediate set of new elements is produced. All these elements are added to the generated EIS.

Step N+1:  For the new element from the intermediate set generated at the Step N, the interpretations of the rules are repeated with each element selected as the rules' context one. But now, only those rules are used that have the recursive flag. All new elements produced by those interpretations are accumulated into a new intermediate set. They are also added to the generated EIS.

The iterations of the steps are continued until on some step no new elements produced.

Note: DocFlex distinguishes elements by their ID. Therefore, only those elements are considered as the new ones whose IDs have not yet occured on the previous iterations. Such an approach helps to prevent the infinite looping when the processed elements contains cyclic references, however, it requires each element to have the unique ID.

Example:

Let's consider a little more complicated version of the previous example. Now, the data source providing the information about a Java-project allows to know a parent of each class (if any it has) and the interfaces the class directly implements.

The new DTD will be the following:

<!ELEMENT field>
<!ELEMENT method>
<!ELEMENT class (field*,method*,class*,interface*)>
<!ELEMENT interface (field*,method*)>
<!ELEMENT package (class*,interface*,package*)>

<!ATTLIST class extends IDREF>
<!ATTLIST interface extends IDREFS>
<!ATTLIST class implements IDREFS>

Let now our task is to collect all interfaces directly or indirectly implemented by a given class (this will include the interfaces directly implemented either by the class itself or by one of its ancestor classes and the interfaces that are the ancestors of those implemented directly). This can be done using the following set of Recursive Location Rules:

class     → extends^::class 
class     → implements^::interface 
interface → extends^::interface 

The rules should be interpreted with the interested class as the initial context element. The result set should be filtered for the elements of interface type.

4.  Specifying Element Iteration Scope

There are four methods to specify the Element Iteration Scope (EIS) generation in the Element Iterator:

• Simple Location Rules
• Advanced Location Rules
• Sequence
• Custom

Simple Location Rules

This is a simplified method, which allows to quickly and naturally define the Element Location Rule in the most cases. It requires specifying only four settings:

1. Target Element Type
   
   Defines one or many element types: TargetETs which the elements of the generated EIS should conform to.
2. Include Descendants
   
   Specifies if the search should include all descendants of the context element.
3. Include Self
   
   Specifies if the context element itself can be included into the EIS (in the case its type is appropriate)
4. Filter Expression
   
   Defines a filter for the EIS.

Assigning of those settings will result in building automatically one of the following Element Location Rules:

* → child::TargetETs [filter]
* → descendant::TargetETs [filter]
* → child-or-self::TargetETs [filter]
* → descendant-or-self::TargetET [filter]

Advanced Location Rules

This is the most comprehensive method of defining Element Location Rules. It gives access to all features implemented in DocFlex. The generation of the EIS is specified with the following settings:

1. Location Rules
   
   The list of the Element Location Rules specifying how the EIS is generated

   Defining a single Location Rule:

   

   Defining a Location Step:

   

2. Target Element Type
   
   Defines one or many element types that the final EIS is filtered for to contain only elements of those types
3. Filter Expression
   
   Specifies an additional filter for EIS

Sequence

An alternative method of the EIS generation not based on Element Location Rules. The EIS is produced as the sequence of the connected elements, according to the following settings:

1. Expression for First Element
   
   The FlexQuery-expression calculating the first element for the EIS. The calculation normally should be based on the context element received by the section and may involve other generator variables.
2. Expression for Subsequent Element
   
   All other EIS elements (except the first one) are calculated by this FlexQuery-expression. At each step, if the previous element was not null it is made the context element. Then, the expression is processed and the next element is produced.
3. Target Element Type
   
   Specifies the type of the elements that are included into the result EIS. In effect, this setting defines a filter that is applied to the EIS, once the initial set has been produced.
4. Filter Expression
   
   Allows to define an additional filter for the EIS.

Custom

A yet another alternative method of EIS generation. It allows to organize iterations by an arbitrary set of elements provided by the specified FlexQuery-expression.

The following settings should be assigned in the Element Iterator properties:

1. Target Element Type

   Specifies the Element Type, to which the elements included in the result EIS should conform. The initial set of elements is filtered according to this condition.

2. Expression for Element Enumeration

   The FlexQuery-expression which should return an Enumeration of the elements for iteration.

   The expression may employ various capabilities provided by FlexQuery functions (such as findElementsByLPath(), findElementsByLRules(), findElementsByKey()).

   It is also possibility to generate a set of iterated elements by an external custom-witten Java class called using the callForName() function.

3. Filter Expression

   Allows to define an additional filter for the result EIS.

5.  Sorting Element Iteration Scope

There are following options to specify sorting of the Element Iteration Scope (EIS):

• none (original order)
• reverse original order
• by element attribute
• by element name
• by element value
• by compound key

none (original order)

No sorting. The EIS is remained in the original order (i.e. the one that is naturally formed when the elements are being inserted in the EIS).

reverse original order

Reverses the original order. This option may be particularly useful when the EIS is generated by Sequence method.

by element attribute

The elements of the EIS are sorted by the value of the specified attribute (according to its data type).

Additional settings:

1. ordering: ascending/descending
2. case sensitive (for character values only)

by element name

The elements of the EIS are sorted by their names (i.e. the names of their Element Types) in lexicographical order. This option makes sense when the EIS contains many elements of the different types.

Additional settings:

1. ordering: ascending/descending
2. case sensitive (for character values only)

by element value

The elements of the EIS are sorted by their values (regarding data types)

Additional settings:

1. ordering: ascending/descending
2. case sensitive (for character values only)

by compound key

This is the most common method of sorting the EIS. It includes all previous methods and allows much more, though it might seem a little complicated. In this case, the elements of the EIS are sorted by an arbitrary compound key generated for each element.

Each compound key consists of a certain sequence of the subkeys:

subkey1; subkey2; ...; subkeyN

that is generated for each element before the sorting. The compound keys are compared by comparing consecutively their constituent subkeys in the order in which the subkeys follow.

Each subkey has its own method of calculation. This method also determines the subkey's data type, according to which the particular subkeys are compared.

The subkey calculation method can be specified as one of the following:

1. by Location Path
   
   The value of the subkey is assigned from the value of an element or attribute retrieved by the specified Location Path. The Location Path is interpreted relatively to the EIS element for which the whole key is generated. The Location Path also determines the subkey's data type.
2. by Formula
   
   The value of the subkey is calculated by the specified FlexQuery-expression, which also determines the subkey's data type. The expression should derive the subkey value from the EIS element for which the whole key is generated. For doing so, the element is temporarily made the generator's context element and in this way can be accessed from within the expression.

In addition to the calculation method, the comparison of the subkeys may be adjusted with following settings:

1. subkey ordering: ascending/descending
2. case sensitivity (for character subkeys only)