Latest revision as of 22:06, 24 October 2009

Draft Content
This page is currently under construction. Community members are encouraged to maintain the page, and make sure the information is accurate.

XSL Tools adds support for XSL Launch and Debugging configurations. These allow you to setup XSL configurations for various jobs, and to also debug xsl stylsheet transformations.

XSL Launching

In the Project Explorer, simply select the input XML file and the stylesheet(s) to transform it, and then right-click and select Run As > XSL Transformation .

XSLT Run/Debug

Selecting only the XSL Stylesheet
If only the XSL Stylesheet is selected then a dialog box will prompt you for the input file to use.

Launch can also be done through the Launch Configurations pages that are used for both debugging and normal transformations. These configurations can be accessed through Run->Run Configurations menu bar option.

Launch Configuration

Currently, XSL Tools only supports the launching of java based processors through the Run and Debug framework. To this point, it leverages and extends some of the support provided by the Java launch configurations. XSL Tools does add it's own specific features for launching.

Java XSLT Launch Configuration

The tabs Main, Output, and Processor control specifics for the XSLT processor and files to be run through the transformation.

XSLT Extensions
If the transformation needs or makes use of extension functions then those jar files should be added to the Classpath tab so that they are picked up during the transformation. Otherwise the transformation will fail.

Main Tab

As shown in Java XSLT Launch Configuration, the Main Tab is where the input XML file is specified. If a particular XML file is not shown in the available list when browsing the Workspace, make sure that it is added to under the XML Content Type in the General preference page. Standard eclipse launching variables can be used to specify the location of the input file.

A run configuration can also use a simple pipeline transformation. Meaning that the output from one stylesheet is used as input to the next stylesheet. The Stylesheet input box can have one to many stylesheets specified. At least one stylesheet is required for a transformation.

The last optional items are parameters. Stylesheets can have parameters passed into them to setup configuration information. An example would be the numerous parameters that can be set for a DocBook stylesheet transformation. If the parameters are not specified the defaults that are defined in the stylesheet will take precedence.

Output Tab

The Output Tab allows the specification of where the transformation should store the information.

This can be relative to the workspace or a physical location outside the workspace.

Java XSLT Launch Configuration

Processor Tab

The particular XSLT processor that will be used can be choosen from this tab. The default is to use the system default processor or what ever processor you have set as the default processor in the preference pages.

Java XSLT Launch Configuration

XSLT Debugging
If you are setting up a launch configuration for debugging, do not choose the JRE Default processor, you should choose either Xalan or another adopters processor that supports debugging.

In addition, every processor has their own configuration options that can be specified. This controls such items as indentation, handling of white space, etc. Refer to your processors documentation for the specific options available.

XSLT Debugging

XSL Tools provides a framework for XSLT processors to provide debugging support. The support provided is highly dependent on the processors. XSL Tools comes with built in support for the Xalan 2.7.1 processor. Debugging is only available for those processors that support the feature and plug into the extension point. The XSL Tools debugger leverages the existing eclipse platform Debug View

XSLT Debugging

How the debugger acts will depend on the processor being used. Not all XSLT processors pass the same type of information to the debugger. These differences will be noted in the XSLT Processor Specific Support section.

Starting a Debug Session

Debugging is started the same way as launching an XSL Tranformation is done. Except that the debug configuration is used instead of the normal launch configuration. If a debugging session is started on a processor that does not support debugging, a dialog will ask if you want to switch to one of the supported debuggers.

Default JRE
The default JRE does not have built in support for debugging, even though it is based on Apache Xalan. It is recommended to use Xalan or another processor provided by an adopter to do your transformations. The default processor is known to have some issues that Xalan and other processors do not have.

Common Debugging Operations

XSLT debugging is handled by the eclipse platforms debugging framework support as outlined in the "Program Debug and Launch Support". Common operations like stepping into (F5), stepping over (F6), pausing, running to a breakpoint, and relaunching are supported. In addition to the standard Variable and Breakpoint views provided by the platform, there are some XSLT specific views and functionality as well. All of these are common regardless of the particular XSLT debugger being used.

Introduction to Eclipse Debugging
Basic Debugging in Eclipse contains a good general introduction to the basic features provided by the Eclipse Debug view. XSL Tools leverages many of these features and the same concepts apply to the XSL Tools debugger.

In addition to the standard features and functionality, the XSL Tools debugging support adds the following additional items:

• Result View
• XSLT specific Variables
• XSLT Processor Specific Functionality

Result View

The XSLT Debugger has a result view. This will show the output that the stylesheet has generated to the current break point or since the last step command was issued.

Insert Result View Image Here

The result view is updated throughout the debugging process, and is useful to help see what output is generated at specific points during a transformation.

Variables View

The variables view will show all the local and global variables and params that are currently in scope. There are two types of variables that can be views.

Insert Variables View here

• String - These contain text values. This could be strings of text, numbers, or other characters.
• Nodesets- Nodesets are represented in the variables view as expandable variables. They contain sequences of nodes. The type of nodes are represented by icons for elements, attributes, text, comments or processing instructions.

Can I change the value of variables?
Currently the XSLT Debugger does not support changing the values or contents of a variable. All XSLT variables are read only.

XSLT Processor Specific Support

Various XSLT processors provide various levels of debugging support. Many do not provide support for debugging of stylesheets, and thus can't be used for debugging. XSL Tools provides basic support for Xalan, and can be used as a guide for adopters on how to implement their own specific debugging support for other processors.

XSL Debugging with Xalan

Xalan provides general stylesheet execution and evalation functionality. However there are a few things that Xalan does not suppor that other processors do.

Xalan Debugging Issues

• Breakpoints - Xalan does not support stopping at Global Variables or Parameters when a debugging session is started. It will automatically start at the first template. Break points must be placed in templates to be honored. The reason for this is that Xalan lazily initializes the variables only when they are first used.
• XSLT Text elements - Xalan does not send notifications of xsl:text elements. These are skipped over when debugging.
• Built In Templates - Xalan does provide notification when the built in templates are called, but currently the debugger does not support or display stepping into these templates.