Chapter 3. Specifying how to convert an XML document to another format Previous topic Parent topic Child topic Next topic

What is a conversion specification?

How to convert an XML document to another format is specified in XML configuration files called xslutil.conversions. Excerpts of xslsrv/addon/config/xhtml/xslutil.conversions (xslsrv/ being the unpacked xslsrv.war):
<conversions xmlns="">  
  <conversion name="xhtmlToPDF"
    description="Convert to PDF using Apache FOP"
    <transform styleSheet="xsl/fo.xsl">
      <parameter name="paper.type">A4</parameter>

      <!-- Needed to convert a remote URL rather than a local file. -->
      <parameter name="img-src-path">%~pi</parameter>

    <processFO processor="FOP">
      <parameter name="renderer">pdf</parameter>
      <parameter name="strict-validation">false</parameter>
A conversion specification is always referred to by its name, which is unique. In the above example, the conversion specification is called "xhtmlToPDF" and allows to convert an XHTML document to PDF using Apache FOP.
The format of xslutil.conversions is not yet documented. Fortunately, XMLmind XSL Utility Opens in new window, a user-friendly desktop application allows to create and edit conversion specifications quickly and easily.

Where does XMLmind XSL Server find all its conversion specifications?

During its initialization, that is, the first time the XMLmind XSL Server WebApp is invoked after its Servlet Container has been started, XMLmind XSL Server searches the following directories
  1. xslsrv/addon/, where xslsrv/ is the unpacked xslsrv.war,
  2. customize_dir/addon/, where customize_dir is the directory pointed to by the customizeDir server parameter, if any.
for files called xslutil.conversions, which contain conversion specifications and also for files whose basename ends with "atalog.xml", which are XML catalogs Opens in new window (1). The conversion specifications collected during these stage are immutable. Moreover their number is fixed, that is, adding or removing xslutil.conversions files to/from any of the two addon/ directories will not be detected by XMLmind XSL Server. We'll call this set the stock conversion specifications.
During its initialization, XMLmind XSL Server also attempts to load customize_dir/xslutil.conversions, which may contain redefinitions of some of the stock conversion specifications and/or custom conversion specifications.

Specifying the customization directory of XMLmind XSL Server

If you carefully read the above section, you'll understand that, unless you properly define the customizeDir server parameter, you'll be limited to using the stock conversion specifications, as is.
  1. Download and install XMLmind XSL Utility Opens in new window.
  2. Specify the customizeDir server parameter in xslsrv/WEB-INF/web.xml (xslsrv/ being the unpacked xslsrv.war) .
    In the following example, we'll suppose that customizeDir points to /opt/xslsrv/. Use a text editor and edit xslsrv/WEB-INF/web.xml. Give a value to the customizeDir init-param.
  3. Open a terminal or a command prompt and start XMLmind XSL Utility as follows:
    $ xslutil -p /opt/xslsrv &
  4. Quit XMLmind XSL Utility by clicking its Quit button. This is sufficient to create and properly initialize /opt/xslsrv/.
    $ ls /opt/xslsrv
Make sure that the user account used to run the Servlet Container (e.g. user: tomcat, group: tomcat) has sufficient privileges to read the contents of the directory pointed to by the customizeDir server parameter.
XMLmind XSL Server can directly use the user preferences directory of XMLmind XSL Utility. In other words, no need to create a special purpose directory (/opt/xslsrv/ in the above examples) for that.
The user preferences directory of XMLmind XSL Utility is:
  • $HOME/.xfc/ on Linux.
  • $HOME/Library/Application Support/XMLmind/FOConverter/ on the Mac.
  • %APPDATA%\XMLmind\FOConverter\ on Windows. Example: C:\Users\joe\AppData\Roaming\XMLmind\FOConverter\.
Example (user: joe on Linux):
XMLmind XSL Server can directly use an existing Apache FOP Opens in new window configuration file.
The location of an existing FOP configuration file may be specified to XSL Server by the means of Java™ system property or environment variable XXE_FOP_CONFIG. The value of this variable is an URL or an absolute file path. Examples: -DXXE_FOP_CONFIG=http://localhost/~john/fop/fop.conf (Java™ system property), set XXE_FOP_CONFIG=C:\Users\john\misc\fop\fop.conf (Windows environment variable).
You'll need to restart your Servlet container after setting system property or environment variable XXE_FOP_CONFIG.

Let's suppose you want to convert an XHTML document to RTF. The XHTML file starts with:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xml:lang="en" xmlns="">
Without an XML catalog, xhtml1-transitional.dtd will be downloaded from in order to be parsed, which will make the conversion really slow.
With the following XML catalog, xslsrv/addon/config/catalog.xml:
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
  <public publicId="-//W3C//DTD XHTML 1.0 Transitional//EN"
It's the local copy of the DTD, xslsrv/addon/config/xhtml/dtd/1.0/xhtml1-strict.dtd, which is going to be parsed.