Download the latest release from
https://sourceforge.net/projects/servingxml/.
This includes the source code and build files as well as a number of third party jar files. Be sure to read the
release-notes.txt file carefully if you are upgrading from a previous version.
ServingXML versions 0.8.x require Java SE 5 or later (they will not work with earlier versions.)
Set the JAVA_HOME environmental variable to point to the JDK base directory:
Apache ANT must be installed before building ServingXML.
Download a recent binary release and unzip the download file to a directory in your system. Set the ANT_HOME
environmental variable to point to the ANT base directory:
From the command line, in the root directory of the servingxml download, build the distribution:
The build command will create two subdirectories
under the target directory target:
The servingxml subdirectory is a binary
distribution, it contains all of the files required for running
ServingXML applications, and you can move it to
any location on your computer. Under it, you will find the following
file and directories.
servingxml.jar - jar file that contains the main program
config - directory of configuration files
lib - all jar files required by the servingxml framework and included extensions
resources/META-INF/components - directory of components.xml files (not used by console app.)
classes - your custom java .class files for SAX filters, dynamic content handlers, etc.
testsuite - tests written in the ServingXML markup language
To install, first build the distribution, then copy the target/servingxml directory to a convenient location
on your system.
Set the JAVA_HOME environmental variable to point to the Java base directory (if not already set):
Add ServingXML's location to the PATH environmental variable:
;c:\path\to\servingxml to the system variable called PATH
You can run the ServingXML console application by executing the batch file
servingxml.bat (Windows) or the shell script servingxml
(Unix/Linux). The syntax for running the console application is
servingxml [-options] service [param=value...]
The options are as follows.
Identifies the resources script.
Identifies the default input file (if not specified it defaults to the "standard" input stream.)
Identifies the default output file (if not specified it defaults to the "standard" output stream.)
Identifies an optional configuration file.
If this option is not specified, ServingXML looks for a configuration
file called servingxml.xml in the
classpath. If none is found, default values are used.
Show exception stack trace.
Print help.
Print the version.
Go to the samples/flat2xml directory. From the command line, try running the
books-to-XML conversion,
servingxml -r resources-books.xml -i data/books.txt -o output/books.xml books
Have a look at the output in the output/books.xml file.
Now, have a look at the resources script, the resources-books.xml file.
By default, ServingXML supports JDK 1.4 logging. The default logger is named
com.servingxml.util.system.DefaultLogger. You can
configure it by editing your <JRE Home>/lib/logging.properties
file, and changing the property values for the handler you want to deliver the
log record.
If you want the application to write log messages using a different logger, perhaps log4j, you will need to
MyLogger that implements
com.servingxml.util.system.Logger.
classes directory.
com.servingxml.util.system.Logger=com.servingxml.util.system.MyLogger(System properties may be set in the optional
config/servingxml.properties file.)
Configuration options may be set in the servingxml.xml configuration
file, either during the build step, in the file located in servingxml-framework/config, or in the target,
in the file located in servingxml/config.
The sx:xsltConfiguration section may be of interest.
<sx:xsltConfiguration version="2.0">
<sx:systemProperty name="javax.xml.transform.TransformerFactory"
value="net.sf.saxon.TransformerFactoryImpl"/>
<!-- sx:systemProperty name="jaxp.debug" value="true"/ -->
<sx:outputProperty name="indent" value="no"/>
<sx:outputProperty name="{http://icl.com/saxon}omit-meta-tag" value="yes"/>
</sx:xsltConfiguration>
Here, you can set default values for output properties for all XML serializers. For example, you can change the default for "indent" from "no" to "yes" to have XML output formatted in indented style, unless overriden in a stylesheet or an emitter.
The system property jaxp.debug allows you to verify that the transformer actually being used
is the one you want.
The default XSLT transformer supplied with ServingXML is
Saxon-B 9, an XSLT 2.0 conforming transformer. You may wish to use a different
2.0 transformer, or revert to a 1.0 transformer, such as Saxon 6.5.5. The steps
for reverting to Saxon 6.5.5 are as follows:
lib/endorsed directory.
lib/endorsed directory.
servingxml.xml,
changing the version attribute in the sx:xsltConfiguration element to "1.0",
and setting the "javax.xml.transform.TransformerFactory" system property to "com.icl.saxon.TransformerFactoryImpl".
<sx:xsltConfiguration version="1.0">
<sx:systemProperty name="javax.xml.transform.TransformerFactory"
value="com.icl.saxon.TransformerFactoryImpl"/>
<sx:outputProperty name="indent" value="no"/>
<sx:outputProperty name="{http://icl.com/saxon}omit-meta-tag" value="yes"/>
</sx:xsltConfiguration>
Rebuild the ServingXML project
Instead of packaging the XSLT transformer with ServingXML, you can if you wish pick up all the jar files implementing the JAXP transformer APIs
from the standard endorsed locations. In this case you will need to you will need to copy the jar files for your preferred JAXP transformer to the
endorsed directory
lib/endorsed directory.
endorsed directory,
%JAVA_HOME%\jre\lib\endorsed(you will need to create the endorsed subdirectory if it does not already exist.)
ServingXML 1.0.0 has been tested with Saxon-B 9.1 (requires saxon9.jar and saxon9-dom.jar).
Other versions have been tested with
Saxon 6.5.5 (requires saxon.jar), and Xalan 1.2.6 (requires xalan.jar.)
You may also want to download new versions of the Xerces jar files, including
xercesImpl.jar, xml-apis.jar and xmlParserAPIs.jar, and copy them to the
endorsed directory as well.
Individual records in files may be validated with an XML schema, using an msv:recordValidator
element. The schema validates against the canonical XML representation of the record.
If validation fails, the record will be discarded. If an sx:discardFilter element
appears after the msv:recordValidator element in the record pipeline, the discarded record will be handled,
and processing will continue. The content of the sx:discardHandler element may optionally contain a record pipeline
for writing all discarded records to a file or a database table. Refer to the example "Converting a CSV file to XML with Record Validation"
in the on-line examples.
Custom record filters written in Java, incorporated with an sx:customRecordFilter element,
provide another way of error checking. Within a record filter, you can perform
checks on the current record, decide whether to pass the record down or
alternatively throw an exception. If you throw a
ServingXmlException and your filter is followed by a
sx:discardHandler later in the pipeline, the record will be discarded but processing will continue;
otherwise processing will be stopped. Refer to the "hot 1" example for an example of a custom record filter.
XML events in XML pipelines may be validated with an XML schema, using an msv:schemaValidator element. By default, if validation fails, a message will be written to the log, and processing will stop. Again, refer to the example "Converting a CSV file to XML with Record Validation" in the on-line examples.
Since ServingXML provides a streaming API, some output may be written before an error is detected and processing stopped.
If you want to check the entire file for errors before writing any output, you can do so by setting up two tasks inside an
sx:service element and processing the file twice, first with no output, then with output.
By default, an exception occuring in the first task will result in all processing being stopped.
See the "mail message" example for an example with two tasks within a service.