<oXygen/> XML Editor User Guide

Working with Debugger

This section explains the working process involving the use of Debugger perspective.

Getting Started

<oXygen/> provides two perspectives, Editor and Debugger. <oXygen/> starts by default in the Editor perspective. Switching between Editor and Debugger perspectives is easy and can be done at any time during a working session even when no files have been opened. To switch to Debugger perspective click the button .

Unlike Editor perspective, Debugger perspective requires that at least one document (XML) and one stylesheet (XSL) are opened before the debug functionality and features become of any use. These files can be opened while in Editor perspective before switching to Debugger perspective, or directly from within the Debugger perspective. You can switch back to Editor perspective by clicking the Editor button .

When switching from Editor perspective to Debugger perspective, the opened files are sorted by extension into the Source document view (XML) and Stylesheet document view (XSL) panes.

The Debug Process

The debug procedure described below (see Typical Debug Process), assumes <oXygen/> is already in Debugger perspective and at least one document (XML) and one stylesheet (XSL) are already opened. Some samples have been provided in order to get used with the XSLT debugging process. They can be found in the samples/debugger subdirectory of your <oXygen/> installation.

When a debug process is running, it is adviseable to stop the process before attempting to edit source documents or stylesheets. Editing during an active debug process will result in inaccurate informations being displayed in the Information View. The process must also be stopped in order to switch to Editor perspective.

During the debug process, if the transformation engine reaches a node from a file that has not been opened, this file will be opened into the corresponding pane and the node will be highlighted. This is most likely to happen in the cases of XML entity files or XSL imported/included files.

Errors encountered during debugging are reported in the <oXygen/> results panel.

At the end of debugging process, only the content from the following views is preserved (all other views are cleared):

Procedure 6.1. Typical Debug Process

  1. From Source document view (XML) select a source document.

  2. From Stylesheet document view (XSL) select a stylesheet document.

  3. From the Control Toolbar use the XML source selector control to select a source document.

  4. From the Control Toolbar use the XSL stylesheet selector control to select a stylesheet.

  5. From the Control Toolbar use the XSLT engine selector control to select one of the available processing engines.

  6. Configure the XSLT parameters. Once set, these parameters are preserved between debugging sessions.

  7. Start the debugging using the active control buttons (see Control view for description of control functions).

Output to Source Mapping

Every section of the output it is generated by an XSL stylesheet element in the context of an XML source node.

During debugging, it is important to know this mapping from output to source in order to quickly spot the templates with problems. 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 style element being executed in the current source context. However, this can become difficult on complex stylesheets that generates a large output.

Output to source mapping is a powerful feature that makes this 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 element that generated the text.

Figure 6.3. Output to Source Mapping

Output to Source Mapping

Additionally, you can inspect the mapping by clicking a section of the output from the XHTML view tab of the Output document view to have the stylesheet element and the source context highlighted.

Figure 6.4. XHTML Output Mapping

XHTML Output Mapping

Understanding Information Views

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

Context node view

The context node 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 XPath watch view.

Figure 6.5. The Context node view

The Context node view

Table 6.1. Context node details

Column Description
Name Name of source (XML) node.
Attributes/Value Attributes or value of the XML node. If attributes exist, they are shown under the form of attributeName ="attributeValue", otherwise the text content of the node is shown.

XPath watch view

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

Figure 6.6. The XPath watch view

The XPath watch view

Table 6.2. XWatch details

Column Description
Expression XPath expression to be evaluated (should be XPath 1.0 or 2.0 compliant).
Value Result of XPath expression evaluation. Value has a type (see Possible Values in the section Variables view). For Node Set results the number of nodes in the set is shown in parenthesis.
[Important]Remarks
  • Expressions reffering 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. Press enter on cell to add and evaluate.

  • To delete an expression click on its Expression column and delete its content. 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 Node set view).

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 both XML and XSL documents.

Figure 6.7. The Breakpoints view

The Breakpoints view

Table 6.3. Breakpoints details

Column Description
Resource Resource file where the breakpoint is set. Entire path of resource file is available as tooltip.
Line Line number inside resource where the breakpoint is set.
[Important]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.

  • The contextual menu on table has "Remove" and "Go to" options.

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

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 shows all <xsl:message> calls executed by the XSLT processor during transformation.

Figure 6.8. The Messages view

The Messages view

Table 6.4. Messages details

Column Description
Message Message content.
Terminate Signals if processor will terminate the transformation or not once it encounters the message (true/false respectively)
Resource Resource file where <xsl:message> instruction is defined. The complete path of the resource is available as tooltip.
[Important]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 style nodes. During transformation two stacks are managed: one of source nodes being processed and the other for stylesheet nodes being processed. <oXygen/> shows both node types into one common stack. The source (XML) nodes are preceded by a red color icon while stylesheet 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 stylesheet instruction is executed (the last red color node on the stack). The stack is oriented upside down.

Figure 6.9. The Stack view

The Stack view

Table 6.5. Stack details

Column Description
# Order number, represents the depth of the node (0 is the stack base).
XML/XSL Node Node from source or stylesheet document currently being processed. One particular stack node is the document root, noted as #document.
Attributes Attributes of the node (list of id="value" pairs).
Resource Resource file where the node is located. Entire path is available as tooltip.
[Important]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 processors signal the following events during transformation:

  • entering a source (XML) node.

  • leaving a source (XML) node.

  • entering a stylesheet (XSL) node.

  • leaving a stylesheet (XSL) 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 stylesheet 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 possiblity to compare the trace results from different debug sessions.

Figure 6.10. The Trace History View

The Trace History View

Table 6.6. Trace History details

Column Description
Depth Starts 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 Node Represents 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).
Attributes Attributes of the node (list of id="value" pairs).
Resource Resource file where the node is located. Complete path to resource file is provided as tooltip.
[Important]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 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 6.11. The Templates view

The Templates view

Table 6.7. Templates details

Column Description
Match Match attribute of the <xsl:template>.
Hits Number of hits for the <xsl:template>. Shows how many times the XSLT processor used this particular template.
Priority Template priority as established by XSLT processor.
Mode Mode attribute of the <xsl:template>.
Name Name attribute of the <xsl:template>.
Resource Resource file where template is located. Complete path of resource file is available as tooltip.
[Important]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 XPath watch view and shows a nodeset value. 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 6.12. The Node Set view

The Node Set view

Table 6.8. Node set details

Column Description
Name Name of source (XML) node.
Attributes/Value Attributes or text content (Value) of the XML node. If attributes exist, these are shown under the form of attributeName ="attributeValue", otherwise the text content of the node is shown.
[Important]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 6.13. The Variables view

The Variables view

Table 6.9. Variables details

Column Description
Name Name of the variable/parameter.
Value Current value for the variable/parameter.
[Important]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)