xsldb:howToUse

home

Prerequisites

xslt 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 Environment

Create 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):

 birds.xml  Transformation input file (see sources)
 birds.xsl  Transformation xslt script (see sources)
 xsldb.jar  xsldb archive. The one and only.
 TransformTest.cmd  Test start script
 xsldbtest.jar  archive for the Transformtest example.

The archive xsldbtest.jar contains the following classes:

  test/testMain.class xslt extension class for demonstration purposes.
  test/TransformTest.class transformation class that uses the trax paradigma.

Lets's have a look at TransformTest.cmd. This is the windows version for a typical jdk1.3 installation:

@SETLOCAL
@set PATH=c:\jdk1.3.1_02\jre\bin
@set CP=.\xsldb.jar
@set CP=%CP%;.\xsldbtest.jar
@set CP=%CP%;d:\dev\xalan-j_2_2_0\bin\xalan.jar
@set CP=%CP%;d:\dev\xalan-j_2_2_0\bin\xerces.jar
@set CP=%CP%;d:\dev\xalan-j_2_2_0\bin\xml-apis.jar
@set CP=%CP%;c:\jdk1.3.1_02\jre\lib\rt.jar
@java -cp %CP% -DXSL="birds.xsl" -DXML="birds.xml" -DOUT="birds.txt" -DLOG="log.txt" test.TransformTest
@ENDLOCAL

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 Test

Start 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.



Execution

Okay, 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:

[CMD:/] h
++Help: (r)run to end, (i)nspect value-of items, (ii) inspect every item, (c)ommand prompt, (q)uit.
: (rnnn)run to line nnn in XSLT-script. Usage: 'r12' runs to line 12.
: (rxpath)run to first occurance of xpath command in XSLT script. Usage: 'rDate:new()' runs to first occurance of this XPath command.

Description of the commands:

 r  Runs the debugger until end of transformation while displaying the generated/transformatted output on the console. Note that pressing return at the first (!) command prompt reaches the same.
 i  Runs the debugger until end of transformation while displaying the most attractive XPATH value-of commands and their content on the console.
 ii  Runs the debugger until end of the transformation while displaying every possible XSLT transformation and XPATH command output on the console.
 c  Prompt for commands while parsing the xslt transformation process step by step. You can use every one of the other command to leave this steping. Note: Pressing return does not force xsldb to run until end of transformation as before (at the first prompt) but stepping over to the next xslt or XPATH step and prompting for another command.
 rNNN  Run to line NNN of the xslt script and prompt for further user commands.
 rCOMMAND  Run to the first occurance of COMMAND in the xslt script. This is for serious copy and paste afficionados.
 h  Displays a short help description.
 q  Stops execution of the transformation process at once.



run 1

Start the command file and press „r“ (followed by return). The console shows the generated transformation output:

[CMD:/] r
++Run to End
generated [STARTDOCUMENT] --------------------------------
generated [CHARACTERS] ACME Communications ltd.
generated [CHARACTERS] Wed Aug 07 22:53:58 CEST 2002
generated [CHARACTERS]
Great Tin
generated [CHARACTERS] amou.
Highland Tinam
generated [CHARACTERS] ou.
Little Tinamou.

generated [CHARACTERS] Thicket Tinamou.

generated [CHARACTERS] Slaty-breasted Tinamou.
Choco Tinamou.

generated [ENDDOCUMENT] --------------------------------

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 example

The 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.

TransformerFactory tFactory = TransformerFactory.newInstance();
Transformer transformer = tFactory.newTransformer(new StreamSource(xslFile));

if (transformer instanceof TransformerImpl) {

try {

TransformerImpl transformerImpl = (TransformerImpl)transformer;
TraceManager trMgr = transformerImpl.getTraceManager();

if(trMgr.hasTraceListeners()) {

System.out.println("-- strange...");

}

Xsldb xsldb = new Xsldb();
trMgr.addTraceListener(xsldb);

transformer.transform(new StreamSource(xmlFile), new StreamResult(new FileOutputStream(outFile)));

} catch (Exception ex) {

System.out.println("--- Exception: " + ex.getMessage());

}

} else {

System.out.println("--- configuration error.");

}

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 2

The 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:

[CMD:/] r$today
++BreakString: $today
generated [STARTDOCUMENT] --------------------------------
generated [CHARACTERS] ACME Communications ltd.
trace [VALUEOF 18, 32] value-of $today
[CMD:/]

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 3

Start 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 4

Start 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
++Inspect value-of only
selected [XPathselect 17, 57]: main:getString(string('huhu!')) => [#STRING] ACME Communications ltd.
generated [STARTDOCUMENT] --------------------------------
generated [CHARACTERS] ACME Communications ltd.
selected [XPathselect 18, 32]: $today => [#UNKNOWN (java.util.Date)] Sun Aug 11 21:27:04 CEST 2002
generated [CHARACTERS] Sun Aug 11 21:27:04 CEST 2002
selected [XPathselect 20, 34]: $family => [#NODESET] Nodeset contains one single Node:

Great Tinamou.
Highland Tinamou.
Little Tinamou.
Thicket Tinamou.
Slaty-breasted Tinamou.
Choco Tinamou.

generated [CHARACTERS]

Great Tin

generated [CHARACTERS] amou.

Highland Tinam

generated [CHARACTERS] ou.

Little Tinamou.

generated [CHARACTERS] Thicket Tinamou.

generated [CHARACTERS] Slaty-breasted Tinamou.

Choco Tinamou.

generated [ENDDOCUMENT] --------------------------------

 

Also notice the strange output formatting behavior (see 'run1' annotations).



run 5

Start 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
++Inspect every Item
trace [TEMPLATE 10, 25] template match='/'
trace [VARIABLE 12, 49] variable today = Date:new()
selected [XPathselect 12, 49]: Date:new() => [#UNKNOWN (java.util.Date)] Mon Aug 12 20:43:22 CEST 2002
trace [VARIABLE 12, 92] variable class = Class
selected [XPathselect 12, 92]: Class => [#NODESET] Nodeset contains one single Node:

Great Tinamou.
Highland Tinamou.
Little Tinamou.
Thicket Tinamou.
Slaty-breasted Tinamou.
Choco Tinamou.

Red-throated Loon.
Arctic Loon.
Pacific Loon.
Common Loon.
Yellow-billed Loon.

Least Grebe.
Pied-billed Grebe.
Atitlan Grebe.
Horned Grebe.
Red-necked Grebe.
Eared Grebe.
Western Grebe.
Clark's Grebe.

Yellow-nosed Albatross. (A)
Shy Albatross. (A)
Black-browed Albatross. (A)
Light-mantled Albatross. (A)
Wandering Albatross. (A)
Laysan Albatross.
Black-footed Albatross.
Short-tailed Albatross. (N)

Northern Fulmar.
Kermadec Petrel. (A)
Herald Petrel. (A)
Murphy's Petrel. (N)
Mottled Petrel. (A)
Bermuda Petrel.
Black-capped Petrel.
Juan Fernandez Petrel. (N)
Dark-rumped Petrel.
White-necked Petrel. (H)
Bonin Petrel. (H)
Black-winged Petrel. (H, A)
Cook's Petrel. (N)
Stejneger's Petrel. (A)
Bulwer's Petrel. (H)
Jouanin's Petrel. (H, A)
Parkinson's Petrel. (N)
Streaked Shearwater. (A)
Cory's Shearwater. (N)
Pink-footed Shearwater. (N)
Flesh-footed Shearwater. (N)
Greater Shearwater. (N)
Wedge-tailed Shearwater.
Buller's Shearwater. (N)
Sooty Shearwater. (N)
Short-tailed Shearwater. (N)
Christmas Shearwater. (H)
Manx Shearwater.
Townsend's Shearwater.
Black-vented Shearwater.
Audubon's Shearwater.
Little Shearwater. (A)

Wilson's Storm-Petrel. (N)
White-faced Storm-Petrel. (A)
European Storm-Petrel. (A)
Fork-tailed Storm-Petrel.
Leach's Storm-Petrel.
Ashy Storm-Petrel.
Band-rumped Storm-Petrel. (N)
Wedge-rumped Storm-Petrel. (N)
Black Storm-Petrel.
Guadalupe Storm-Petrel.
Markham's Storm-Petrel. (A)
Tristram's Storm-Petrel. (H)
Least Storm-Petrel.

White-tailed Tropicbird.
Red-billed Tropicbird.
Red-tailed Tropicbird.

Masked Booby.
Blue-footed Booby.
Peruvian Booby. (A)
Brown Booby.
Red-footed Booby.
Northern Gannet.

American White Pelican.
Brown Pelican.

Brandt's Cormorant.
Neotropic Cormorant.
Double-crested Cormorant.
Great Cormorant.
Red-faced Cormorant.
Pelagic Cormorant.

Anhinga.

Magnificent Frigatebird.
Great Frigatebird.
Lesser Frigatebird. (A)

trace [VARIABLE 13, 54] variable order = $class/Order[1]
selected [XPathselect 13, 54]: $class/Order[1] => [#NODESET] Nodeset contains one single Node:

Great Tinamou.
Highland Tinamou.
Little Tinamou.
Thicket Tinamou.
Slaty-breasted Tinamou.
Choco Tinamou.

trace [VARIABLE 14, 56] variable totalorder = $class/Order
selected [XPathselect 14, 56]: $class/Order => [#NODESET] Nodeset contains 5 nodes. No Output for this complex structure available
trace [VARIABLE 15, 72] variable family = $order/Family[@Name='TINAMIDAE']
selected [XPathselect 15, 72]: $order/Family[@Name='TINAMIDAE'] => [#NODESET] Nodeset contains one single Node:

Great Tinamou.
Highland Tinamou.
Little Tinamou.
Thicket Tinamou.
Slaty-breasted Tinamou.
Choco Tinamou.

trace [VALUEOF 17, 57] value-of main:getString(string('huhu!'))
selected [XPathselect 17, 57]: main:getString(string('huhu!')) => [#STRING] ACME Communications ltd.
generated [STARTDOCUMENT] --------------------------------
generated [CHARACTERS] ACME Communications ltd.
trace [VALUEOF 18, 32] value-of $today
selected [XPathselect 18, 32]: $today => [#UNKNOWN (java.util.Date)] Mon Aug 12 20:43:22 CEST 2002
generated [CHARACTERS] Mon Aug 12 20:43:22 CEST 2002
trace [DEFAULT 19, 30] if
selected [XPathtest 19, 30]: main:isTrue() => [#BOOLEAN] true
trace [VALUEOF 20, 34] value-of $family
selected [XPathselect 20, 34]: $family => [#NODESET] Nodeset contains one single Node:

Great Tinamou.
Highland Tinamou.
Little Tinamou.
Thicket Tinamou.
Slaty-breasted Tinamou.
Choco Tinamou.

generated [CHARACTERS]

Great Tin

generated [CHARACTERS] amou.

Highland Tinam

generated [CHARACTERS] ou.

Little Tinamou.

generated [CHARACTERS] Thicket Tinamou.

generated [CHARACTERS] Slaty-breasted Tinamou.

Choco Tinamou.

trace [DEFAULT 23, 45] for-each
selected [XPathselect 23, 45]: null => [#NODESET] Empty NodeSet
generated [ENDDOCUMENT] --------------------------------

 

Also notice the strange behavior around the 'generated' literals.



Output Patterns

The 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:

 trace  command: ii, c  'Trace' output is written to the console when the xslt transformation engine reads in a new xslt commands but before that command is executed. The output normally reflects the command string.
 selected  commands: ii, i, c  'Selected' output is written to the console after execution of an xslt command string. Exceptions in JAVA-extensions usually will result in abortion of the transformation process.
 generated  commands: ii, i, r  'Generated' output is written to console before the transformation output is written to file. Transformation output usually is some kind of 'selected' result.

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()
selected [XPathselect 12, 49]: Date:new() => [#UNKNOWN (java.util.Date)] Mon Aug 12 20:43:22 CEST 2002

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
selected [XPathselect 12, 92]: Class => [#NODESET] Nodeset contains one single Node:

Great Tinamou.
Highland Tinamou.
Little Tinamou.
Thicket Tinamou.
Slaty-breasted Tinamou.
Choco Tinamou.
...



run 6

Start 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
++Do prompt for command
[CMD:/]
trace [TEMPLATE 10, 25] template match='/'
[CMD:/]
trace [VARIABLE 12, 49] variable today = Date:new()
[CMD:/]
selected [XPathselect 12, 49]: Date:new() => [#UNKNOWN (java.util.Date)] Mon Aug 12 21:33:51 CEST 2002
[CMD:/]
trace [VARIABLE 12, 92] variable class = Class
[CMD:/]
selected [XPathselect 12, 92]: Class => [#NODESET] Nodeset contains one single Node:

Great Tinamou.
Highland Tinamou.
Little Tinamou.
Thicket Tinamou.
Slaty-breasted Tinamou.
Choco Tinamou.
...

 

You can leave the command mode by entering 'r' (for 'run to end') or 'q' (for quitting).