Getting Started


Download ServingXML
Building ServingXML
Set Up Your Environment
Run the Build Script
Installing ServingXML
Running ServingXML
First Example
Configuring ServingXML
Configure logging
Setting options in the configuration file
Changing XSLT transformers
Using the Java endorsed directory
Add or drop extensions
Error Processing

Download ServingXML

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.

Building ServingXML

Set Up Your Environment

Java Development Environment

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:

  • Windows XP: Go to Start -> Control Panel -> System -> Advanced -> Environment Variables and set the environment variable JAVA_HOME to c:\path\to\java
  • Linux/Unix/Mac: export JAVA_HOME=/path/to/java/

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:

  • Windows XP: Go to Start -> Control Panel -> System -> Advanced -> Environment Variables and set the environment variable ANT_HOME to c:\path\to\ant
  • Linux/Unix/Mac: export ANT_HOME=/path/to/ant/

Run the Build Script

From the command line, in the root directory of the servingxml download, build the distribution:

  • [win32] build
  • [unix] ./build.sh

The build command will create two subdirectories under the target directory target:

  • servingxml
  • samples

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

Installing ServingXML

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:

  • Windows XP: Go to Start -> Control Panel -> System -> Advanced -> Environment Variables and append ;c:\path\to\servingxml to the system variable called PATH
  • Linux/Unix/Mac: export PATH=$PATH:/path/to/servingxml/

Running ServingXML

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.

-r

Identifies the resources script.

-i

Identifies the default input file (if not specified it defaults to the "standard" input stream.)

-o

Identifies the default output file (if not specified it defaults to the "standard" output stream.)

-c

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.

-T

Show exception stack trace.

-help

Print help.

-version

Print the version.

First Example

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.

Configuring ServingXML

Configure logging

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

  • Write an adaptor class MyLogger that implements com.servingxml.util.system.Logger.
  • Compile the class and add it to the classes directory.
  • Set the system property
    com.servingxml.util.system.Logger=com.servingxml.util.system.MyLogger
    
    (System properties may be set in the optional config/servingxml.properties file.)

Setting options in the configuration 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.

Changing XSLT transformers

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:

  • Remove the Saxon-B 9 jar files from the lib/endorsed directory.
  • Download the Saxon 6.5.5 jar file and copy to the lib/endorsed directory.
  • Update the ServingXML configuration file 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

Using the Java endorsed directory

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

  • Remove the jar files in the ServingXML lib/endorsed directory.
  • In addition, you will need to copy the jar files for your preferred JAXP transformer to the Java 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.

Add or drop extensions

ServingXML consists of a framework and a number of extensions. You can edit the root-level build-extensions.xml file to remove extensions you do not need, if you want to create a smaller deployment package.

Error Processing

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