![]() |
xsldb:howToUse |
|
Prerequisitesxslt transformation is done best with the apache xalan distribution or Sun's implementation of the xslt transformation classes (f.e. in JDK/JRE 1.4). xsldb is fully supported by both of these two implementations. For using xsldb make sure you have added xsldb.jar to your classpath. I recommend starting with the TransformTest example first. That's what this page is about. JRE/JDK < v1.4 You need the apache xalan distribution >= v2.0. Make sure to add the following archives to your classpath: xalan.jar, xerces.jar and xml-apis.jar. At this time the predecessor versions of xalan are not supported (that'll be fxed asap in the late summer). JRE/JDK = v1.4 You do not need any additional archives to start the demos and to use the xsldb debugging features. |
|
Files and EnvironmentCreate a directory. Let's call it sandbox. Copy the files TransformTest.zip and xsldb.jar into the sandbox directory. Unzip TransformTest.zip. There have to be the following files (look inside the sources):
The archive xsldbtest.jar contains the following classes:
Lets's have a look at TransformTest.cmd. This is the windows version for a typical jdk1.3 installation:
Edit the file to match your current local installation of the jdk and the XALAN distribution. Notice the 4 system parameters that'll be read in during execution ot the example. UNIX users know what to do... Notice that with jdk1.4 you don't need any jars from the XALAN distribution any more. Just drop the 3 lines. |
|
A First TestStart the command file TransformTest.cmd. If everything works fine, the example shows the debuggers prompt „[CMD:/]“. If there are JAVA Errors or Exceptions make sure the command file is correct. If everything works fine until now, type „r“ and press enter. The transformation process will start and some output is written to the console. If you encounter JAVA Exceptions after the first command prompt it is likely that there's a problem within your classpath or within the xsldbtest.jar file. Go back to bolt 1) and return for another test. |
|
ExecutionOkay, every thing works fine. Let's have a look on the debuggers instruction set. Start the command file and wait for the prompt. Type „h“ and press enter. A complete list of xsldb's command are shown:
Description of the commands:
|
|
run 1Start the command file and press „r“ (followed by return). The console shows the generated transformation output:
The literal „generated“ in the first output column means that the transformation output is being put out to the output file which has the name birds.txt. Just have a look in your directory. Notice the strange output formatting and compare it to the correct transformation output file. This is not a bug (and not really a feature) but I will fix it in one of the next releases. Okay, your classpaths are set. The TransformTest program seems to work fine. Let's have a closer look to the TransformTest implementation and the xsldb debugger's behavior. |
|
Inside the TransformTest exampleThe following code snipplet is a short description on how to use the xsldb debugging features inside a TRAX transformation implementation. See file TransformTest.java for more details and additional source code comments.
xsldb integration is done through the red colored lines. That's all. Just get yourself a TraceManager and give it an instance of the Xsldb class.
|
|
run 2The paragraph run1 shows the 'run through' output of xsldb (command: 'r'). The following examples will take a closer look on the other commands and the interpretation of xsldb's output. Start the command file once more. At the first command enter 'r$today'. Xsldb will run until row 18. This is the console output:
As you can see xsldb is waiting for another command input. Just press return a few times to step over some more times or press „r“ to run till end of transformation. |
|
run 3Start the command file and enter 'r18'. Xsldb will now run to line 18. The output should be the same as in the 'run 2' section. |
|
run 4Start the command file and enter 'i'. This time xsldb print out a standard transformation report. Every xslt 'value-of' command line and the detailled execution path (f.e. XPath commands) is printed out to the console. Have a look at the following printout: [CMD:/] i
generated [CHARACTERS]
generated [CHARACTERS] amou.
generated [CHARACTERS] ou.
generated [CHARACTERS] Thicket Tinamou. generated [CHARACTERS] Slaty-breasted Tinamou.
generated [ENDDOCUMENT] --------------------------------
Also notice the strange output formatting behavior (see 'run1' annotations). |
|
run 5Start the command file and enter 'ii'. This forces xsldb to print out an extended standard transformation report. Every xslt script command line and the fully detailled execution path (f.e. XPath commands) is printed out to the console. Have a look at the following printout: [CMD:/] ii
trace [VARIABLE 13, 54] variable order = $class/Order[1]
trace [VARIABLE 14, 56] variable totalorder = $class/Order
trace [VALUEOF 17, 57] value-of main:getString(string('huhu!'))
generated [CHARACTERS]
generated [CHARACTERS] amou.
generated [CHARACTERS] ou.
generated [CHARACTERS] Thicket Tinamou. generated [CHARACTERS] Slaty-breasted Tinamou.
trace [DEFAULT 23, 45] for-each
Also notice the strange behavior around the 'generated' literals. |
|
Output PatternsThe standard transformation reports (commands 'r', 'i' and 'ii') throw a lot of xslt tranformation information onto the console. xsldb differentiates between three base output types that can occur on different xsldb commands:
Sounds ugly? Just try it out! Let's have a look at some cases. case 1: This output has been taken from the example 'run 5' above. The 'trace' output shows the read-in xslt command, in this case a call to the extension constructor of java.util.Date. The 'selected' output usually repeats the XPATH portion of the xslt command, Date:new(), and prints the result (this is Date.new().toString()), 'Mon Aug 12 20:43:22 CEST 2002'. trace [VARIABLE 12, 49] variable today = Date:new() case 2: This case shows the 'selected' output of a NodeList. Notice that currently only NodeLists content with one single Node is being printed out to the console. This limitation will be changed in the near future. trace [VARIABLE 12, 92] variable class = Class
|
|
run 6Start the command file and enter 'c'. Xsldb will now switch to command mode. Press 'return' to jump to the next 'trace' ore 'selected' point for executing or printing commands like mentioned above. [CMD:/] c
You can leave the command mode by entering 'r' (for 'run to end') or 'q' (for quitting). |