## FAQ

## ServingXML Basics

1. | Which platforms are supported?
| `ServingXML` should run on any platform with a Java Virtual Machine version 1.5 or higher. Users have reported running various versions of the software on Windows NT/2000/XP, Linux, and Solaris.
2. | Can I use the software in a commercial product?
| Yes, `ServingXML` is Apache 2 licensed, which permits free commercial use of the software.
3. | Can `ServingXML` handle COBOL packed-decimal fields?
| Yes, `ServingXML` can read COBOL packed-decimal values and render them as numeric strings, and read numeric strings and render them as packed-decimal values.
4. | Can `ServingXML` handle binary fields?
| Yes, `ServingXML` can read binary fields and render them as hexadecimal strings, and read hexadecimal strings and render them as binary values.
5. | Can `ServingXML` handle repeating groups?
| Yes, `ServingXML` can read Repeating groups separated by repeat delimiters, and terminated by a segment delimiter or end of record. Repeating groups of elements of fixed count. Repeating groups of elements of variable count, where the count is read from a field in the record.
6. | Can `ServingXML` process large files?
| Yes. Flat-to-XML mappings are done one record at a time, and XML-to-flat mappings take a streaming approach to minimize the amount of data held in memory at any one time. Current users are processing flat files with hundreds of thousands of records without a problem.
7. | Is XPATH 2/XSLT 2.0 supported?
| Yes. All XPATH expressions and XSLT stylesheets referred to in `ServingXML` pipelines are evaluated using the configured JAXP XSLT transformer. By default, the `ServingXML` console application uses `Saxon-B 9`, which implements XSLT 2.0 It is possible to configure `ServingXML` to use a different transformer, even an older XSLT 1.0 tranformer such as `Saxon 6.5`.

## ServingXML Console App

1. | How can I pass a multi-valued parameter, say `price` with three values, from the command line?
      java -jar servingxml.jar -i input.csv -o output.xml -r resources.xml myService price=3.0 price=2.0 price=4.0

## ServingXML Markup

1. | If I have a `ServingXML` resources script that defines a pipeline containing an XSLT stylesheet, and I have XML content defined in the resources script, can I refer to that content inside the document function of the stylesheet?
| Yes. Use a URI obtained by concatenating the namespace URI and the local name of the content defined in the resources script. If the `ServingXML` content requires parameters, append the "?" character to the `URI`, followed by `name=value` entries separated by a ";" or an escaped ampersand character (&amp;).
2. | My XML output is one long line. How can I tell the serializer to indent it for readability?
| Change the default default `indent` output property in the `servingxml.xml` configuration file.
    <sx:xsltConfiguration version="1.0" ...

      <sx:outputProperty name="indent" value="yes"/>
Or, use the `sx:outputProperty` element inside a `sx:xsltSerializer` to override the default `indent` output property of the `XSLT` serializer.
      <sx:serialize ...

        <sx:xsltSerializer>
          <sx:outputProperty name="indent" value="yes"/>
        </sx:xsltSerializer>
3. | How can I change the encoding charset of output xml?
| Use the `sx:outputProperty` element inside a `sx:xsltSerializer` to set the `encoding` output property of the `XSLT` serializer, e.g.
      <sx:serialize ...

        <sx:xsltSerializer>
          <sx:outputProperty name="encoding" value="ISO-8859-1"/>
        </sx:xsltSerializer>
4. | How can I set the the "cdata-section-elements" XSLT output property, with a qualified name in the value?
| Give the value as a two-part string, the namespace URI enclosed in curly braces ({}), followed by the local name.
      <sx:serialize ...

        <sx:xsltSerializer>
          <sx:outputProperty name="cdata-section-elements" value="{namespaceUrl}tag"/>
        </sx:xsltSerializer>
5. | How do I set `xsi:nil` ="true" for elements with empty values?
| Use `sx:choose` in the record mapping section.
    <sx:recordMapping id="countriesToXmlMapping">
      <countries xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <sx:onRecord>
          <country>
            <sx:choose>
              <sx:when test="code = ''">
                <countryCode xsi:nil="true"/>
              </sx:when>
              <sx:otherwise>
                <sx:fieldElementMap field="code" element="countryCode"/>
              </sx:otherwise>
            </sx:choose>

## ServingXML Embedding

1. | What is the minimal number of jar files required in a `ServingXML` distribution?
| `ServingXML` versions 0.8.x, which minimally require Java 5, need `servingxml.jar` and a conforming XSLT implementation (the versions of Xalan currently shipping with Java 5.x and 6.x will not work, because of bugs in these versions.) Earlier `ServingXML` versions, which minimally require Java 1.4, need additional jar files, including `concurrent.jar`, `xml-apis.jar`, and `xercesImpl.jar`. Extensions such as Fop need more jar files.
2. | Using `ServingXML` within a Spring framework, how do I pass a Spring ApplicationContext object down to a custom record filter?
| Pass it through the parameters. In the application code, add it to the parameters before executing a service.
      ApplicationContext appContext ...

      ParameterBuilder paramBuilder = new ParameterBuilder();
      Name contextName = new QualifiedName("appContext");
      paramBuilder.setObject(contextName, appContext);
      Record parameters = paramBuilder.toRecord();

      Flow flow = new FlowImpl(parameters, defaultStreamSource, defaultStreamSink);

      service.execute(context, flow);
In the custom record filter, access the ApplicationContext object from the parameters.
    public class MyRecordFilter extends AbstractRecordFilter
    implements RecordFilter  {
      private static final Name contextName = new QualifiedName("appContext");
      private ApplicationContext  appContext;

      public void startRecordStream(ServiceContext context, Flow flow) {
        super.startRecordStream(context, flow);
        this.appContext = (ApplicationContext)parameters.getObject(contextName);
      }
3. | When creating the `Flow`, what can I use as a default (empty) `StreamSource`?
| `StreamSource.NULL`
4. | Is it possible to pass the input file as a String?
| Yes, by passing a StringStreamSource when creating a Flow,
      import com.servingxml.io.streamsource.StreamSource;
      import com.servingxml.io.streamsource.StringStreamSource;

      ..

      StreamSource streamSource = new StringStreamSource(str);

      Flow flow = new FlowImpl(parameters, streamSource, streamSink);
5. | Is it possible to pass the resource file as an InputStream?
| Yes, using the `createIocContainer` method that takes an InputStream,
     IocContainerFactory iocContainerFactory = new IocContainerFactory();
     iocContainerFactory.loadComponentDefinitions();

     InputStream is;
     //Initialize input stream

     IocContainer resources =
        iocContainerFactory.createIocContainer(is, parameters);
6. | Is it possible to pass the resource file as a String?
| Yes, using the `createIocContainer` method that takes a Reader,
      import java.io.Reader;
      import java.io.StringReader;

      IocContainerFactory iocContainerFactory = new IocContainerFactory();
      iocContainerFactory.loadComponentDefinitions();

      Reader reader = new StringReader(str);

      IocContainer resources =
        iocContainerFactory.createIocContainer(reader, parameters);
7. | How do I get the ouput XML as a string?
| Use a `StringStreamSink`,
    import com.servingxml.io.streamsink.StringStreamSink;

    ...

    StreamSink streamSink = new StringStreamSink();
    Flow flow =  new FlowImpl(parameters, streamSource, streamSink);

     ...

    String s = streamSink.toString();

## Troubleshooting

1. | When I try to build ServingXML, I get the following error message:
    [javac]servingxml-0.8.0.1a\build\java\com\servingxml\util\ChildDictionary.java:32: '{' expected
    [javac] public class ChildDictionary<K,V> implements MutableDictionary<K,V> {
| This error message means that your version of the Java Development Kit (JDK) does not support generics, which were introduced in Java 1.5. ServingXML versions beginning with 0.8.0 require a JDK version 1.5 or later. See the Getting Started guide for instructions on installing a recent JDK. If you've followed the instructions, and you type
    echo %JAVA_HOME%
you should see something like
    C:\Program Files\Java\jdk1.5.0_11
Later versions are fine.
2. | When I try to run the command for ServingXML below:
    java -jar c:\servingxml\servingxml.jar -r resources-APFile.xml -i LoadPayable.xml -o output\APFile.txt AP
I get the following error message: Exception in thread "main" java.lang.NoClassDefFoundError: java/lang/CharSequence at com.servingxml.app.consoleapp.ConsoleApp.main(ConsoleApp.java:58)
| `CharSequence` was new to Java 1.4, so it looks like your Java Runtime Environment (JRE) predates 1.4. ServingXML versions before 0.8.0 require Java runtime 1.4 or later; subsequent versions require Java runtime 1.5 or later. See the Getting Started guide for instructions on installing a recent JRE. If you've followed the instructions, and you type
    java -version
you should see something like
    java version "1.5.0_11"
Later versions are fine.