Part II, Chapter 3. Specifying how to convert an XML document to another format

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="http://www.xmlmind.com/xslutil/schema/conversion">  
  <conversion name="xhtmlToPDF"
    description="Convert to PDF using Apache FOP"
    icon="icon:acroread"
    category="XHTML"
    categoryIcon="icon:xhtml_file"
    outputExtension="pdf">
    <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>
    </transform>

    <processFO processor="FOP">
      <parameter name="renderer">pdf</parameter>
      <parameter name="strict-validation">false</parameter>
    </processFO>
  </conversion>
</conversions>

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

, 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

xslsrv/addon/, where xslsrv/ is the unpacked xslsrv.war,
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

⁽¹⁾. 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.

Procedure:

Download and install XMLmind XSL Utility .
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.
```
<init-param>
<param-name>customizeDir</param-name><param-value>/opt/xslsrv</param-value>
</init-param>
```
Open a terminal or a command prompt and start XMLmind XSL Utility as follows:
```
$ xslutil -p /opt/xslsrv &
```
Quit XMLmind XSL Utility by clicking its Quit button. This is sufficient to create and properly initialize /opt/xslsrv/.
```
$ ls /opt/xslsrv
addon
xslutil.conversions
xslutil.properties
```

Important

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.

Tip

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

<init-param>
<param-name>customizeDir</param-name><param-value>/home/joe/.xfc</param-value>
</init-param>

Tip

XMLmind XSL Server can directly use an existing Apache FOP

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.