Working with the XSLT/XQuery Debugger

The following topics are present about how to follow XSLT/XQuery processing and detect errors in your stylesheets or XQuery documents:

Steps in a typical debug process

To debug a stylesheet or XQuery document follow the procedure:

  1. Open the source XML document and the XSLT/XQuery document.

  2. If you are in the <oXygen/> XML perspective switch to the <oXygen/> XSLT Debugger perspective in case of XSLT debugging or to the the <oXygen/> XQuery Debugger in case of XQuery debugging with one of the actions (here explained for XSLT):

    • Window->Open Perspective->Other ...+<oXygen/> XSLT Debugger

    • The toolbar button Debug scenario

  3. Select the source XML document in the XML source selector of the Control toolbar In case of XQuery debugging if your XQuery document has no implicit source set the source selector value to NONE.

  4. Select the XSL/XQuery document in the XSL/XQuery selector of the Control toolbar.

  5. Set XSLT/XQuery parameters from the button available on the Control toolbar.

  6. Set one or more breakpoints.

  7. Step through the stylesheet using the buttons available on the Control toolbar: Step into, Step over, Step out, Run, Run to cursor, Run to end, Pause, Stop

  8. Examine the information in the Information Views to find the bug in the transformation process.

Note

Initially only the two available Saxon XSLT/XQuery Processors are active in the Debugger perspective.If you select Xalan XSLT Processor an warning message is shown requiring Xalan version 2.7.0. To set Xalan 2.7.0 you need to copy xalan.jar and serializerOxygen.jar from [oxygen]/lib and put it to the endorsed folder from your JRE/JDK used for running Eclipse (you can find it in Help->About Eclipse Platform+Configuration Details java.endorsed.dirs entry) and restart Eclipse.

Using breakpoints

The <oXygen/> XSLT/XQuery Debugger allows you to interrupt XSLT/XQuery processing to gather information about variables and processor execution at particular points.

Inserting breakpoints

To insert a breakpoint:

  1. In the XML source document or the XSLT/XQuery document that you want to set a breakpoint, place your cursor on the line where you want the breakpoint to be. You can set breakpoints on XML source only for XSLT debugging sessions.

  2. Select Edit->Breakpoints->Create or directly click with the mouse the left side stripe of the editor window on the line where you want the breakpoint to be.

Removing breakpoints

To remove a breakpoint:

  • Click with the mouse the left side stripe of the editor window on the line with the breakpoint or select Edit->Breakpoints->Remove all

Viewing processing information

Detailed information about the debugger status are provided using the information views.

Context node view

The context node is valid only for XSLT debugging session and is a source node corresponding to the XSL expression being evaluated. It is also called the context of execution. The context node implicitly changes as the processor hits various steps (at the point where XPath expressions are evaluated). This node has the same value as evaluating '.' (dot) XPath expression on XWatch View. The value of the context node is presented as a tree in the view.

Figure 7.4. The Context node view

The Context node view

The context node is presented in a tree-like fashion. The value of the selected attribute or node are shown in the right side panel.

XPath watch view

Shows XPath expressions to be evaluated during debugging. Expressions are evaluated dynamically as the processor changes its source context.

Figure 7.5. The XPath watch view

The XPath watch view

Table 7.1. XWatch details

ColumnDescription
ExpressionXPath expression to be evaluated (should be XPath 1.0 or 2.0 compliant).
ValueResult of XPath expression evaluation. Value has a type (see Possible Values in the section the section called “Variables view”). For Node Set results the number of nodes in the set is shown in parenthesis.

Remarks

  • Expressions referring to variables names are not evaluated. In case of an XPath error, you get an Error line.

  • The expression list is not deleted at the end of transformation (it is preserved during sessions).

  • To insert a new expression click the last line on the expression column and enter it or right click and select the Add action. Press enter on cell to add and evaluate.

  • To delete an expression click on its Expression column and delete its content or right click and select the Remove action. Press enter on cell to commit changes.

  • If the expression result type is a Node Set you can click on it (Value column) and you will see on the right side its value. (see Nodeset View).

  • Copy, Add, Remove and Remove All actions are offered in every row's contextual menu.

Breakpoints view

Lists all breakpoints set on opened documents. Once you set a breakpoint it is automatically added in this list. Breakpoints can be set on XSL/XQuery documents and in XML documents for XSLT debugging sessions.

Figure 7.6. The Breakpoints view

The Breakpoints view

Table 7.2. Breakpoints details

ColumnDescription
EnabledIf checked, the current condition is evaluated and taken into account.
ResourceResource file where the breakpoint is set.
LineLine number inside resource where the breakpoint is set.

Valid Breakpoint

  • Not all set breakpoints are valid. For example if the breakpoint is set on one empty or commented line or the line is not reached by the processor (no template to match it, line containing only an end tag), that breakpoint is invalid.

  • Clicking a record highlights the breakpoint line into the document.

Break conditions view

Lists all defined break conditions. Unlike breakpoints, break conditions are not associated with a document, but they represent XPath expressions evaluated in the current debugger context. In order to be processed their evaluation result should be a boolean value.

Figure 7.7. The Break conditions view

The Break conditions view

Table 7.3. Break conditions details

ColumnDescription
EnabledIf checked, the current condition is evaluated and taken into account.
ConditionXSLT/XQuery expression to be evaluated during debugging. The expression will be evaluated at every debug step.
ValueBoolean result of the evaluated condition or error message if the condition expression cannot be evaluated.

When the Debugger hits an active break condition it pauses the execution of the transformation and places a small marker on the left side of the line where the break condition occured. The tooltip of the marker explains the cause of the pause. To disable further pauses when the same condition occurs you have to uncheck the Enabled column of the corresponding line in the Break conditions view.

Important

  • The contextual menu on table has the Add, Remove, Remove All, Enable All, Disable All options.

Messages view

<xsl:message> instructions are one way to signal special situations encountered during transformation as well as a raw way of doing the debugging. This view is available only for XSLT debugging sessions and shows all <xsl:message> calls executed by the XSLT processor during transformation.

Figure 7.8. The Messages view

The Messages view

Table 7.4. Messages details

ColumnDescription
MessageMessage content.
TerminateSignals if processor will terminate the transformation or not once it encounters the message (true/false respectively)
ResourceResource file where <xsl:message> instruction is defined.

Remarks

  • Clicking a record from the table highlights the <xsl:message> declaration line.

  • Message table values can be sorted by clicking the corresponding column header (ascending, descending, no sort)

Stack view

Shows the current execution stack of both source and XSL/XQuery nodes. During transformation two stacks are managed: one of source nodes being processed and the other for XSL/XQuery nodes being processed. <oXygen/> shows both node types into one common stack. The source (XML) nodes are preceded by a red color icon while XSL/XQuery nodes are preceded by a green color icon. The advantage of this approach is that you can always see the source scope on which a XSL/XQuery instruction is executed (the last red color node on the stack). The stack is oriented upside down.

Figure 7.9. The Stack view

The Stack view

Table 7.5. Stack details

ColumnDescription
# Order number, represents the depth of the node (0 is the stack base).
XML/XSL/XQuery NodeNode from source or stylesheet document currently being processed. One particular stack node is the document root, noted as #document.
AttributesAttributes of the node (list of id="value" pairs).
ResourceResource file where the node is located.

Remarks

  • Clicking a record from the stack highlights that node's location inside resource.

  • Using Saxon, the stylesheet elements are qualified with XSL proxy, while on Xalan you only see their names. (example <xsl:template> on Saxon and template on Xalan).

  • Only Saxon processor shows element attributes.

  • Xalan processor shows the "built-in" rules.

Trace history view

Usually the XSLT/XQuery processors signal the following events during transformation:

  • entering a source (XML) node.

  • leaving a source (XML) node.

  • entering a XSL/XQuery node.

  • leaving a XSL/XQuery node.

The trace history catches all these events, so you can see how the process evolved. The red icon lines denote source nodes while the green icon lines denote XSL/XQuery nodes.

It is possible to save the element trace in a structured XML document. It is available on the context menu of the view. In this way you have the possibility to compare the trace results from different debug sessions.

Figure 7.10. The Trace History View

The Trace History View

Table 7.6. Trace History details

ColumnDescription
DepthStarts from 0 and represents the level of overlapping for that node. This is similar with the # order number from stack at the moment the node was processed.
XML/XSL/XQuery NodeRepresents the node from the processed source or stylesheet document. One particular node is the document root, noted as #document. Every node has an arrow in front of it representing what action was performed on it (entering or leaving).
AttributesAttributes of the node (list of id="value" pairs).
ResourceResource file where the node is located.

Remarks

  • Clicking a record highlights that node's location inside the resource.

  • Only Saxon processor shows element attributes.

  • Xalan processor shows the "built-in" rules.

Templates view

The <xsl:template> is the basic element for stylesheets transformation. This view is only available during XSLT debugging sessions and shows all <xsl:template> instructions used by the transformation. By seeing the number of hits for each of the templates you get an idea of the stylesheet coverage by template rules with respect to the input source.

Figure 7.11. The Templates view

The Templates view

Table 7.7. Templates details

ColumnDescription
MatchMatch attribute of the <xsl:template>.
HitsNumber of hits for the <xsl:template>. Shows how many times the XSLT processor used this particular template.
PriorityTemplate priority as established by XSLT processor.
ModeMode attribute of the <xsl:template>.
NameName attribute of the <xsl:template>.
ResourceResource file where template is located.

Remarks

  • Clicking a record highlights that template definition inside resource.

  • Saxon only shows the applied templates having at least one hit from the processor. Xalan shows all defined templates, with or without hits.

  • Template table values can be sorted by clicking the corresponding column header (ascending, descending, no sort)

  • Xalan shows the "built-in" rules.

Node set view

This view is always used in relation with Variables View and XWatch View and shows a nodeset value in a tree form. Once you click a variable having as value a nodeset or tree fragment or an XPath expression evaluated to a nodeset in the above views the node set view gets updated with the respective value.

Figure 7.12. The Node Set view

The Node Set view

The nodes/values set is presented in a tree-like fashion. The value of the selected attribute or node are shown in the right side panel.

Remarks

  • In case of longer values for Value/Attributes column content, the interface shows three suspension points (...) at the end. A more detailed value is available as tooltip.

  • Clicking a record highlights the location of that node into the source or stylesheet view.

Variables view

During transformation variables and parameters play an important role.

<oXygen/> uses the following icons to differentiate variables/parameters:

  • Global variable.

  • Local variable.

  • Global parameter.

  • Local parameter.

The values types of a variable are marked by icons explained below:

Possible Values

  • Boolean.

  • String.

  • Numeric.

  • Node set.

  • Tree fragment.

  • Date. (XSLT 2.0 only)

  • Object.

  • Any.

Figure 7.13. The Variables view

The Variables view

Table 7.8. Variables details

ColumnDescription
NameName of the variable/parameter.
ValueCurrent value for the variable/parameter.

Remarks

  • Clicking a record highlights the variable definition line.

  • Variable values could differ depending on the transformation engine used or stylesheet version set.

  • If the value of the variable is a node-set or a tree-fragment, clicking on it causes the Node set view to be shown with corresponding set of values.

  • Variable table values can be sorted by clicking the corresponding column header (ascending, descending, no sort)

Determining what XSL/XQuery expression generated particular output

In order to quickly spot the XSL templates or XQuery expressions with problems it is important to know what XSL template in the XSL stylesheet or XQuery expression in the XQuery document and what element in the source XML document generated a specified area in the output. Some of the debugging capabilities, for example "Step in" can be used for this purpose. Using "Step in" you can see how output is generated and link it with the XSL/XQuery element being executed in the current source context. However, this can become difficult on complex stylesheets or XQuery documents that generates a large output.

Output to source mapping is a powerful feature that makes this output to source mapping persistent that is you can click on the text from the Output document view and the editor will select the XML source context and the XSL/XQuery element that generated the text.

Figure 7.14. Output to Source Mapping

Output to Source Mapping
  1. If you are in the <oXygen/> XML perspective switch to the <oXygen/> XSLT Debugger or <oXygen/> XQuery Debugger perspective with one of the actions (here explained for XSLT):

    • Window->Open Perspective->Other ...+<oXygen/> XSLT Debugger

    • The toolbar button Debug scenario

  2. Select the source XML document in the XML source selector of the Control toolbar. In case of XQuery debugging without an implicit source choose the NONE value.

  3. Select the XSL/XQuery document in the XSL/XQuery selector of the Control toolbar

  4. Select the XSLT/XQuery engine in the XSLT/XQuery engine selector of the Control toolbar

  5. Set XSLT/XQuery parameters from the button available on the Control toolbar

  6. Apply the stylesheet or XQuery transformation using the button Run to end available on the Control toolbar:

  7. Inspect the mapping by clicking a section of the output from the Output view of the <oXygen/> XSLT Debugger or <oXygen/> XQuery Debugger perspectives to have the XSL/XQuery element and the source context highlighted.