# Getting Started

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