The XSLT-Debugger plugin allows to debug XSLT stylesheets in IntelliJ IDEA with various useful features a debugger should have, including breakpoints, watch expressions, variables display, etc. It is tightly integrated with IDEA which allows it to be efficiently used without much need to familiarize first.
The plugin requires at least version 3 of the "XPathView + XSLT-Support" plugin. If this isn't installed yet, IDEA will automatically download and install it when installing the XSLT-Debugger plugin. If an earlier version is already installed, please upgrade the plugin manually. |
The following sections contain a list of the major features that are provided by the XSLT-Debugger that help to develop and debug XSLT stylesheets in IntelliJ IDEA with pleasure.
Breakpoints are the major feature of any debugger, and so they are for the XSLT-Debugger. Breakpoints can be set in any XSLT file with the same keyboard shortcut to set breakpoints in Java classes, by clicking on the left editor gutter, or by invoking the action "Toggle Line Breakpoint" from the "Run" menu.
Breakpoints in XSLT files are decorated with a little "gear" icon and behave pretty much the same as breakpoints for Java classes or other languages (e.g. Groovy) that can be debugged in IDEA: They can be enabled and disabled, and it's also possible to configure various properties that control the behavior of a breakpoint.
Properties of XSLT breakpoints can be configured by either right-clicking the breakpoint-icon in the left editor gutter or by opening the breakpoints dialog via Run | View Breakpoints from the main menu. This allows to manage the following properties.
Breakpoints can have a condition expression which is evaluated each time the breakpoint is hit. The result of this evaluation determines whether the breakpoint's action is executed, i.e. for a "simple" breakpoint, this would be simply to suspend the execution.
For more advanced debugging, it is also possible to specify either a log- or trace expression that is evaluated when the breakpoint is hit (and the condition, if present, evaluates to true).
The result of a log-breakpoint will simply be written into the output console of the debugged process. This can be useful to output the value of a certain variable or maybe the name of the current context node without having to stop the debugger each time the breakpoint is visited.
If no expression is entered, a standard message like "[text.xsl:12]: <no message>" will be displayed which includes the name of the XSLT file and the line number in brackets.
An even more advanced debugging tool are trace-breakpoint. They are evaluated just like log-breakpoints, but their result isn't printed into the console. Instead, for each evaluated trace-expression, a special node in the "Structure" tree will be inserted. The contains the evaluation result and indicates the position during the execution of the stylesheet when the breakpoint was triggered.
If no expression is entered, a Tracepoint node will be generated that just the line number of the breakpoint that triggered it.
|
When paused, the XSLT-Debugger displays the complete call-stack for the current location. The "Frames" tab shows the stack of XSLT-instructions, while the "Source" tab shows the positions in the transformed source document, i.e. the stack of the context nodes.
When selecting a different frame in the "Frames" tab, the debugger will open the corresponding XSLT file and highlight the selected frame's position in that file. It will also update the "Variables" tab to show the visible variables and their values. Any expressions in the "Watches" tab will be recomputed for the changed context.
The source frames are displayed as a unique XPath location path together with the containing file's name and the line number. Navigating to these frames is possible as well, either by double-clicking an element or by pressing the "Navigate to Source" keyboard shortcut (usually F4). The debugger will then open the corresponding XML file and position the cursor at the selected node's position.
The XSLT-Debugger provides the usual ways to control the execution of a debugged stylesheet, such as "Step Into", "Step Over", "Run to Cursor".
Steps over the current XSLT instruction until the next instruction on the same or a higher level is reached. For example, if the current instruction is an xsl:call-template, the called template will be executed and the debugger will stop at the next instruction after the call.
Note that any XML element, including literal result elements, is an instruction in this case. That means, that if stepping over a literal result element, the execution is resumed until the element has been completely generated. Use "Step Into" to step through the generation of literal result elements. |
Steps into the current XSLT instruction.
Resumes execution of the debugged process until the current line is reached. This can be used as a kind of temporary breakpoint that is cleared once it is reached.
If there are breakpoints set on any lines that will be executed before the specified line is reached, the debugger will pause at the first breakpoint. |
Resumes the execution of the debugged process until another breakpoint is reached or the stylesheet is finished.
Tries to pause the debugged stylesheet at the next XSLT instruction.
When the debugged process is suspended at a breakpoint, the "Variables" tab will show all variables visible in the current scope. Global variables, local variables and parameters are distinguished by different icons.
The value of each variable is shown together with its runtime-type. If a variable holds a value of the type nodeset, the value can be expanded to show all the nodes contained in the set. Such nodes are displayed with an XPath location-path that uniquely identifies each node, together with the textual value of the node, i.e. the evaluated value of string(.).
It's also possible to navigate to a variable's declaration, either from the variable node's context menu or by the keyboard shortcut for "Navigate to source". The same is possible for each node in a nodeset which navigates to the source of the selected node in the containing XML file. If for some reason the location of a node cannot be determined, the Navigate to Source action is disabled.
To copy the string-value of a variable or node into the clipboard, press Ctrl-C or invoke the "Copy Value" action from the context menu.
Watches can be used to automatically compute the value of certain expressions each time the debugger is paused. They will be evaluated in the context of the current stack frame and may reference the current context node as as any variables that are visible when the watch expression is evaluated. If the expression contains an error and cannot be evaluated, an error message will be displayed instead of the result.
The evaluated result of an expression is displayed just like the value of a variable. If the expression cannot be evaluated due to a syntax error or a reference to an undefined variable, this will be displayed with an error message.
On the toolbar of the "Variables" tab there's an action that opens a dialog which allows to evaluate arbitrary expression. The evaluation works just like the evaluation of a watch expression.
The output that is generated by the transformation is displayed in two different ways: First, there's simple textual console window that displays the output (almost) as soon as it is generated. There may be some delay due to the buffering that is used to reduce the performance impact.
When the debugged process is finished, the output can be opened in an IDEA editor by clicking the "Open in Editor" action in the toolbar of the output console.
The second way is much more advanced and allows to track the generation of each XML node as it is produced by the XSLT processor. The generated nodes are displayed in a tree that reflects the XML structure. For each node, its kind (element, attribute, text, etc.), name and value (if applicable for the node type) are displayed.
The tree is updated each time the debugger is paused. Nodes that have been generated since the last time the debugger was suspended are marked with a blue "*" to indicate that it's a new node. Element nodes that aren't closed yet contain a node at the end with the text "..." to indicate that more content is expected.
To find out which XSLT instruction generated a specific node, right click the node and select "Navigate to source". This will open the XSLT file at the position that produced the node.
The toolbar of the "Structure" tab contains the following actions: The "Hide Whitespace Nodes" action will make the tree hide all text-nodes that only consist of whitespace. This can be useful to see only the really relevant nodes. The actions "Expand All" and "Collapse All" allow quickly expand and collapse the whole tree.
Using the debugger is fairly simple. Just follow these few simple steps to create a run configuration and start debugging XSLT stylesheets:
|
|
|
|
|
|
|
|
|
The plugin is available for IntelliJ IDEA 7.0 and 8.1 via the built-in plugin manager and at the IntelliJ Plugin Repository.
The XSLT-Debugger requires version 3 or later of the XPathView + XSLT-Support plugin. If it's not installed yet, IDEA will usually automatically download and install it. If an older version is already installed, please upgrade the plugin manually. |
The "Mute Breakpoints" action currently doesn't work for XSLT-breakpoints. This action does not affect XSLT Breakpoints, i.e. they will stay active. |
The debugger engine currently uses the SAXON 6.5.5 XSLT processor, which might cause the debugged stylesheets to work different or even incorrectly when they're designed for a another processor (e.g. Xalan), especially when extension functions are involved. Debugging with Xalan is possible as well if either a compatible version of Xalan is found in the classpath or the VM argument " To switch back to SAXON even if Xalan is present, use " |
The plugin has so far only been tested on Windows. Although there's nothing that generally prevents using it on other platforms, the breakpoint matching logic depends on file-URLs which may look differently on Linux/Mac. Even though some effort has been put into normalizing the URLs, I don't know if it actually works everywhere. Please let me know if there are any problems - on any platform. |
