[ You are here:
XTF ->
Tips and Tricks -> Setting up External Tools ]
Setting up External Tools
There are hundreds of software packages for working on XML or Java, and we have not tried even a small fraction of them. Still, if you're looking for a place to start, this section covers a few tools we have found to be very useful. Which one you choose depends on how you're using XTF. If you're deploying XTF and debugging stylesheets,
**<oXygen/>** can be invaluable, and is inexpensive for academic users. If you're modifying the Java code, or integrating it into a larger Java framework, the
**Eclipse** IDE is free and powerful. And if you're delving into the Lucene indexes created by XTF,
**Luke** is a wonderful free tool for examining and querying them.
Note that each of these tools is feature-rich and powerful; consequently this guide cannot cover their full functionality. Rather, we concentrate specifically on how they can be used to aid XTF development.
Using <oXygen/> with XTF
<oXygen/> is a powerful XML editor and XSLT debugger (in addition to many other features.) In the context of XTF, it's especially useful in creating and debugging stylesheets used for the various transformations in the XTF data flow, such as request parsers and result formatters.
Here are the steps to set up a new project in Oxygen. In this example, we will be transforming a TEI document using a
dynaXML Document Formatter stylesheet.
- Create a new project in <oXygen/>, and save it (select Save Project As... from the Project menu.)
- Right-click on the project in the Project pane, and select Add Files. Add the stylesheet you want to run; in our example, select xtf-home/style/dynaXML/docFormatter/tei/teiDocFormatter.xsl
- Open the formatter by double-clicking it in the Project pane. Then click the Configure Transformation Scenario button, or select Document -> XML Document -> Configure Transformation Scenario.
- Click New to create a new Transformation Scenario, and give this scenario a name: xtf-tei for this example.

- In the XML URL box, select the XML file you want to transform. For this example, click the little open button and select xtf-home/data/tei/ft958009/ft958009.xml
- Select Saxon9B as the Transformer.
- To validate XTF extension functions, click Extensions, and add the XTF jar file. In the default XTF installation, this can be found here: xtf-home/WEB-INF/lib/xtf.jar
- The Transformation Scenario is complete. Click OK.
- Now select the Debug Scenario button, or select Document -> XML Document -> Debug Scenario.
- <oXygen/> will now switch to Debug perspective. You can now set breakpoints and examine variables as the stylesheet runs. If you need to get back to Edit perspective, select Perspective -> Edit.
- If you need to simulate URL parameters, simply edit the Transformation Scenario you created above, and click the Parameters button to add one or more, named exactly as they would be in a URL, and with normal -- not URL encoded -- values.
The example above is for a single stylesheet — a
dynaXML document formatter — but of course there are many other transformations in XTF. How do you obtain the proper input documents for these? Consult the table in the section on
running Saxon from the command line.
This should get you started using <oXygen/> to boost your productivity with XTF. Of course we've just scratched the surface, so if you have corrections to this procedure, or suggestions for other tips, we'd love to hear from you.
Building XTF from the Source Code
There are many reasons you might wish to rebuild XTF from the source code, instead of using the
xtf.jar provided with the distribution. You might wish to simply examine the source code to help debug problem, or you might want to integrate XTF into a larger Java Framework, or perhaps you want to modify or expand XTF.
The XTF distribution always comes with the complete source code (as all open-source projects should.) It might not be immediately obvious though, because the source code is compressed in the archive
src.zip, stored in the
WEB-INF folder. So the first step is to unzip the source. Either a graphical Zip tool the command-line:
$ cd $XTF_HOME/WEB-INF
$ unzip src.zip
If you're going to use XTF in an IDE such as
Eclipse, you need go no further. However, to build XTF from the command-line, keep reading.
Make sure you have the
ant tool installed. This tool is used to build Java projects. You can easily check if it's available from the command-line like this:
$ ant -version
Apache Ant version 1.7.0 compiled on December 13 2006
If you get a complaint about "command not found", you'll need to obtain and install
ant, but don't worry as it's free. You can get it [
http://ant.apache.org/|from Apache].
Now you can build XTF. From the WEB-INF directory, simply run
ant like this:
$ cd $XTF_HOME/WEB-INF
$ ant
Buildfile: build.xml
init:
[mkdir] Created dir: /Applications/Tomcat/webapps/xtf/WEB-INF/classes
compile:
[javac] Compiling 354 source files to /Applications/Tomcat/webapps/xtf/WEB-INF/classes
BUILD SUCCESSFUL
There's no need to remove the
xtf.jar file in your installation; servlet containers and the XTF command-line scripts will automatically prefer the
.class files you generated when compiling above to the contents of
xtf.jar, so you can confidently make changes to the XTF code, recompile, and see the results immediately.
Using Eclipse with XTF
Eclipse is a free Integrated Development Environment (IDE) for Java, and provides such a wealth of coding and debugging help that all XTF development was done using it. If you are interested in stepping through XTF code, adding features, or integrating XTF into a larger Java project, Eclipse is an excellent choice to help you on your way. Eclipse is available for just about any computer platform, and you can download it
from eclipse.org. In particular, you want the "Eclipse SDK".
Once you've installed Eclipse, there are a few tricks to getting the XTF servlets to run under it. You'll still need a servlet container just as Resin or Tomcat. The instructions below assume you're using Tomcat. It should be noted that this isn't the only way to run XTF within Eclipse. An entirely different method used successfully by an XTF user is documented
here
Instructions for creating an XTF project in Eclipse
- Create a new Java project, by selecting File -> New -> Project..., and selecting Java Project.
- Select Create project from existing source, and select the directory of your XTF installation (e.g. /Applications/Tomcat/webapps/xtf), and give the project a name (e.g. my_xtf). Then click Next.
- Eclipse scans the directory and populates the Source and Libraries tabs. However, we need to modify the Libraries to look for the servlet container, so click that tab.
- Remove xtf.jar from the list of Libraries. We don't want the former because we're going to replace it with a library from Tomcat, and we don't want the latter because we're building directly from the XTF source code.
- Add the following two libraries: tomcat-dir/bin/bootstrap.jar and tomcat-dir/common/lib/servlet-api.jar. You should end up with a list something like this:

- Click Finish, then select Project -> Build Project. It should build with no errors, though there may be warnings depending on your Eclipse version, Java version, and Eclipse settings related to warnings. These warnings are okay.
Now that your XTF project is in Eclipse and the XTF code is built, you can browse the source code, make changes, rebuild, and run it in the debugger. A few additional steps are needed to run XTF under Tomcat in the debugger.
Instructions for debugging XTF servlets within Eclipse
- We need to create a new Debug Configuration in Eclipse. Select Run -> Debug.... Then click on Java Application and hit the little New button up in the corner.
- Now we need to work on the various tabs. First is the Main tab. Specify your project name, then for Main Class select: org.apache.catalina.startup.Bootstrap
- Next select the Arguments tab. Under Program Arguments enter:
-outfile ./logs/catalina.out -errfile ./logs/catalina.err start
and under VM Arguments enter:
-Djava.endorsed.dirs=./common/endorsed -ea -Xms50m -Xmx700m
Finally, under Working Directory, enter the directory of your Tomcat installation (e.g. /Applications/Tomcat).
- Hit the Debug button, and you're debugging!
Of course this only covers the very basics of working with XTF in Eclipse, but hopefully it will help you get started. Feedback (or corrections for recent Eclipse / Tomcat versions) is very welcome.
Using Luke with XTF
If you are interested in exploring the contents of the Lucene indexes that XTF creates and searches, Luke is a free graphical tool that you can browse any Lucene index with, including indexes created by XTF. You can download Luke
here.
Note that when using Luke you will be exposed to some of the internal workings of XTF, such as document chunking, special fields, and markers for field start and end. Depending on your point of view, that's part of the fun of exploring the XTF indexes with Luke.