Red Hat Training

A Red Hat training course is available for Red Hat JBoss Data Virtualization

10.6. Recursion Editor (XML)

10.6.1. What is Recursion?

Some XML schema define data structures that contain self referencing elements or datatypes. When generating XML documents, such data structures can produce an endless repetition of nested tags. This self nesting pattern is known as recursion.
When generating virtual documents from XML Schema, the Teiid Designer detects recursive data structures in the XML Schema model and halts the recursive nesting pattern after two cycles. These two cycles serve different purposes when mapping the document:
  • The first cycle can be thought of as an entry condition for the recursion. The mapping class located at this node defines a normal mapping transformation like that of any other in the document model.
  • The second cycle defines a mapping transformation that will be performed repeatedly until conditions are met that will halt the document instance being generated by the Teiid Designer Server. This fragment of the document model is called the recursive fragment. The mapping transformation for this fragment is no different from the first, except that you can access the first cycle's mapping class attributes, plus you have the opportunity to specify the conditions that will halt the recursion.
You can recognize a mapping class located at the second, recursive document fragment by the looping arrow button in the top left hand corner of the diagram object as shown below.
When you model a virtual document based on an XML Schema model containing recursion, you can choose whether to treat the nested fragments as recursive. Use recursion only when the data access pattern from your data source(s) is also recursive; in other words, when the same query transformation is to be executed over and over to generate and map the nested document's data content.
By default, the Teiid Designer does not mark the recursive fragments in document models to execute recursively in the Teiid Designer Server. To take advantage of this behavior, you must open the Recursion Editor in the recursive mapping class , mark the transformation query as recursive, and specify the recursion limit properties.

10.6.2. Recursion Editor (XML)

The Recursion Editor lets you enable and limit recursion. The Recursion Editor button only displays on mapping classes, which have recursive patterns. For example, if you have an element named Employee which contains a element named Supervisor which itself contains an Employee element nested within it, you might need to limit the number of times the elements are nested within the document.
You can set the following conditions to limit the recursion:
  • A fixed number of results to the query.
  • An SQL based criteria limit condition.
  • A combination of both.
To open the Recursion Editor, click the Recursion Editor button on the displayed mapping class.
Open Recursion Editor Button

Figure 10.30. Open Recursion Editor Button

Recursion Editor

Figure 10.31. Recursion Editor

10.6.3. Edit Recursion Properties

To edit recursion properties:
  1. Select the Enable Recursion checkbox if you want the Teiid Designer Server to perform the query you specify to generate the nested tags within the XML document.
  2. Click the arrows beside the Count Limit box to limit the number of times to recursively perform the query. If you do not set a Limit Condition in the text area, the recursion finishes when the query reaches this limit. You can only set this limit to a maximum supported by your Teiid Designer Server. For more information about this limit, contact your system administrator.
  3. Click the Action When Count Limit Exceeded drop-down menu to instruct the Teiid Designer Server what to do if it encounters more results for the query than the count limit before it reaches the limit condition.
  4. Click the Edit button to launch the SQL to build a limiting condition for this recursion.

Note

The Teiid Designer Server will evaluate this condition each time it recursively performs this query. If this criteria clause evaluates false, the Teiid Designer Server performs the query recursively again unless it has reached the Count Limit. If the criteria evaluates true, the Teiid Designer Server performs the mapping for the current level and ends its recursive loop.
When you have created the criteria, it displays in the Limit Condition box.
When the Teiid Designer Server dynamically populates your XML documents at runtime, it will use the recursion specifications you entered here.