# ServingXML Element Reference

### Daniel Parker

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at Apache License, Version 2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

# Configuration Elements

## Name

sx:cacheSettings — Cache settings

## Attributes

None.

## Content

Optionally, any number of sx:property elements.

## Name

sx:escapeSubstitutions — Define escape rules for special characters in evaluations of SubstitutionExpr

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
escape | No | true|false | `true` if a character should be escaped, `false` otherwise. Defaults to `true`
character | No | Character | The character to optionally enclose field values. Defaults to the double quotation mark.
escapeCharacter | No | Character | The escape character used to escape the quote symbol, e.g. the backslash ('\') or the quote symbol itself.
escapeSequence | No | String | The character sequence used to replace the special character, e.g. '\"' or '""' to escape a double quote.

## Content

None.

## Description

You can use this instruction to define an escape character to escape quote characters appearing in variable values, when evaluated as strings.

This element is a configuration element, meaning it can appear anywhere in a resources script, and will be visible to all elements belonging to its scope. Currently, sx:toString, sx:sqlQuery, and sx:sqlUpdate support the new `sx:escapeSubstitutions` element.

## Examples

Example 1. A double quote character with a backslash escape character.

      <sx:escapeSubstitutions character='"' escapeCharacter="\"/>

Example 2. A single quote character escaped with """.

      <sx:escapeSubstitutions character="'" escapeSequence="&quot;"/>

## See also

- sx:toString
- sx:sqlQuery
- sx:sqlUpdate

## Name

sx:escapeVariables — Deprecated in 1.0, replaced by sx:escapeSubstitutions

## Name

sx:expiryOptions — Expiry options

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
revalidate | No | string | A list of revalidation codes with possible values "synch" or "asynch" (or both), or "full" or "none".

## Content

None.

## Name

sx:patternMatcher — Regular expression pattern matcher

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
class | Yes | Java class | An implementation of the com.servingxml.components.regex.PatternMatcher interface.

## Content

None.

## Name

sx:xsltConfiguration — XSLT configuration

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
version | No | XSLT version | The value of the XSLT version attribute appearing in generated stylesheets. Defaults to "1.0"

## Content

Optionally, any number of sx:outputProperty elements.

Optionally, any number of sx:systemProperty elements.

# Common Elements

## Name

id ref attributes — Common id ref attributes for referencing top level elements

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
id | No | QName | An identifier of an element instance. This id is the target for references by `ref` attributes.
ref | No | QName | This attribute is used to reference an id.

The resources defined in a resources script may be given ids and referred to by reference, as shown below.

Figure 1. SAX pipeline with references

    <sx:resources xmlns:sx="http://www.servingxml.com/core">
      <sx:service id="myPipeline">
        <sx:serialize>
          <sx:transform>
            <sx:content ref="myPreFilter"/>
            <sx:content ref="myFilter"/>
            <sx:content ref="myPostFilter"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

      <sx:saxFilter id="myPreFilter" class="PreFilter"/>
      <sx:xslt id="myFilter">
        <sx:urlSource url="filter.xsl"/>
      </sx:xslt>
      <sx:saxFilter id="myPostFilter" class="PostFilter"/>
    </sx:resources>

Note that we could have written `<sx:saxFilter ref="myPreFilter"/>`, but instead we wrote `<sx:content ref="myPreFilter"/>`, substituting the abstract component sx:content for the derived sx:saxFilter. Identifiers given to components must be unique up to the abstract component level, for instance, a service and a filter may both be named "myPipeline", but a sx:saxFilter and a sx:xslt must be identified differently.

## Name

sx:defaultValue — Defines a default value for a parameter or field

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
value | No | SubstitutionExpr | A string value that may contain a parameter inside curly braces, e.g. "{$my-param}.xml".
select | No | XPath expression | An XPath expression evaluated against the default XML document.

## Content

- Optionally, if there is a `select` attribute, an sx:content element. If supplied, the select expression will be evaluated against this content, otherwise it will be evaluated against the default content.

- Optionally, if there is no `field`, `value` or `select` attribute, any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

## Description

The `sx:defaultValue` element is used in a sx:parameter element to define a default value for a parameter.

The default value may be specified either by a `value` attribute or by the content. This value is only a default value, and if a run-time parameter is passed with the same name, the run-time value will be used in place of the default value.

## See also

- sx:parameter

## Examples

Example 3. Example of initializing a parameter to a constant.

      <sx:parameter name="validate"><sx:defaultValue>yes</sx:defaultValue></sx:parameter>

## Name

sx:parameter — Parameter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | Yes | QName | The name of the parameter.
value | No | SubstitutionExpr | A string value that may reference a parameter or field name inside curly braces, e.g. "{$my-param}.xml".
select | No | XPath expression | An XPath expression evaluated against the default XML document.
type | No | XML Schema types | The parameter value type. Defaults to `xs:string` The input parameter values will be converted to this type if required.

## Content

- Optionally, a sx:defaultValue element.

- Optionally, if there is a `select` attribute, an sx:content element. If supplied, the select expression will be evaluated against this content, otherwise it will be evaluated against the default content.

- Optionally, if there is no `field`, `value` or `select` attribute, any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

## Description

The `sx:parameter` element is used to define a parameter as a QName-value pair, for example,

      <sx:parameter name="validate">no</sx:parameter>

The value of the parameter may be specified either by a `value` attribute or by the content.

A parameter defined inside an element is visible to all siblings and all their descendents. It is not visible to ancestors. If the parameter has the same QName as a parameter in an ancestor, a new parameter value replaces the old one within the scope of siblings and descendents, but not in the scope of ancestors, the old value is still visible to ancestors. It is not possible to change the parameter value of an ancestor, changes are visible to siblings and descendents only. This is to avoid side effects.

The application processing the resources script may pass additional parameters to the script. For example, the console app may pass the parameter `validate` like this:

    java -jar dir/servingxml.jar -r resources.xml myPipeline validate=yes
        < input.xml > output.xml

If you want to define a default value for the parameter, you must do so with a `sx:defaultValue` element as follows.

      <sx:parameter name="validate"><sx:defaultValue>no</sx:defaultValue></sx:parameter>

A passed parameter cannot override a parameter defined in a resources script unless the script's value is a default value, enclosed by a `sx:defaultValue` element. More generally, a parameter in an ancestor cannot override a parameter in a descendent unless the descendant's value is a default value.

## Examples

Example 4. Example of initializing a parameter to a constant.

      <sx:parameter name="validate">yes</sx:parameter>

Example 5. Example of initializing a parameter with the output of a transformation.

      <sx:parameter name="myParam">
        <sx:serialize>
          <sx:transform>
            <sx:xslt>
              <sx:urlSource url="styles/transform1.xsl"/>
            </sx:xslt>
            <sx:content ref="flat1"/>
          </sx:transform>
        </sx:serialize>
      </sx:parameter>

Example 6. Example of initializing a parameter using regular expression substitution on a record field called "name"

      <sx:parameter name="output-file-name">
        <sx:findAndReplace searchFor="(books.*)[.]txt" replaceWith ="$1-new.txt"><sx:toString value="{name}"/></sx:findAndReplace>
      </sx:parameter>

## See also

- sx:defaultValue

## Name

sx:property — Property

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
key | Yes | String | Deprecated, use `name` instead.
name | Yes | String | The custom property name.
value | Yes | String | The custom property value.

## Content

None.

## Name

sx:systemProperty — System property

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
key | Yes | String | Deprecated, use `name` instead.
name | Yes | String | The system property name.
value | Yes | String | The value of a system property.

## Content

None.

## Name

sx:validator — Abstract element standing for a validator

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference an id.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any `sx:validator` specialization, such as sx:recordValidator, sx:fieldValidator, or msv:schemaValidator.

## Examples

## See also

- sx:recordValidator
- sx:fieldValidator
- msv:schemaValidator

## Name

sx:removeEmptyElementFilter — Deprecated, aliased to sx:removeEmptyElements

└ sx:content

## Name

sx:withParameters — Declare the parameters that need to be passed to an XSLT processor

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
parameters | Yes | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all parameters." A namespace prefix followed by a colon followed by the value '*' means all parameters belonging to the namespace.
exceptParameters | No | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all parameters." A namespace prefix followed by a colon followed by the value '*' means all parameters belonging to the namespace.

## Content

None.

## Description

The sx:withParameters declares the parameters that need to be passed to an XSLT processor The `parameters` attribute is mandatory and identifies the parameters that need to be passed. The value '*' may be used to mean "all parameters", exceptions may be identified with the `exceptParameters` attribute.

## See also

- sx:removeEmptyAttributes

# Resources, Service and Task Elements

## Name

sx:choose — Choose from alternatives with XPATH test conditions

└ sx:task, sx:content, sx:recordFilter, sx:mapXml, sx:stringable

## Attributes

None.

## Content

- Optionally, any number of sx:parameter elements.
- One or more sx:when elements.
- Optionally, a sx:otherwise element.

## Description

An `sx:choose` element may be used in any context where any of the following abstract elements are allowed:

- sx:task
- sx:content
- sx:recordFilter
- sx:mapXml
- sx:stringable

The `sx:choose` element evaluates the test conditions of its sx:when child elements, selecting the first alternative that evaluates to `true`, or if none do, then the sx:otherwise child element, if present. The children of the selected alternative are then expanded in place of the `sx:choose` element.

## Examples

Example 7. Choosing content in an XML pipeline.

      <sx:document id="odd-element-document">
        <document>
          <title>Title</title>
          <para>First paragraph.</para>
        </document>
      </sx:document>

      <sx:transform id="test-choose-odd">
        <sx:document ref="odd-element-document"/>
        <sx:choose>
          <sx:when test="count(//*) mod 2 = 0">
            <sx:document>
              <result>even</result>
            </sx:document>
          </sx:when>
          <sx:otherwise>
            <sx:document>
              <result>odd</result>
            </sx:document>
          </sx:otherwise>
        </sx:choose>
        <sx:assert test="text()='odd'">Expected odd number of elements.
        </sx:assert>
      </sx:transform>

The output of this `sx:choose` element is the document

      <result>odd</result>

Example 8. Choosing XML output in a record mapping section.

      <!-- Define a choose expression with embedded parameter
        "term", term values having the format <number><D|M|Y>,
        and expanding to

          <periodMultiplier>number</periodMultiplier>
          <period>D|M|Y</period>
      -->

      <sx:choose id="fpml-period-from-term">
        <sx:when test="fn:ends-with($term,'D')">
          <sx:fieldElementMap element="periodMultiplier">
            <sx:toString select="fn:substring-before($term,'D')"/>
          </sx:fieldElementMap>
          <period>D</period>
        </sx:when>
        <sx:when test="fn:ends-with($term,'M')">
          <sx:fieldElementMap element="periodMultiplier">
            <sx:toString select="fn:substring-before($term,'M')"/>
          </sx:fieldElementMap>
          <period>M</period>
        </sx:when>
        <sx:when test="fn:ends-with($term,'Y')">
          <sx:fieldElementMap element="periodMultiplier">
            <sx:toString select="fn:substring-before($term,'Y')"/>
          </sx:fieldElementMap>
          <period>Y</period>
        </sx:when>
      </sx:choose>

      <!-- Expand the "fpml-period-from-term" sx:choose element
        someplace in an sx:recordMapping block where literal
        content is allowed

      <calculationPeriodFrequency>
        <sx:parameter name="term" value="{calculation_period}"/>
        <sx:choose ref="fpml-period-from-term"/>
      </calculationPeriodFrequency>

The output of this `sx:choose` element depends on the value of the field `calculation_period`. If for a particular record the value of the field is "6M", the element expands to

          <periodMultiplier>6</periodMultiplier>
          <period>M</period>

## Name

sx:when — When condition of an sx:choose

### Attributes

Name | Required | Value | Description
--- | --- | --- | ---
test | Yes | XPath Boolean Expression | The boolean expression to evaluate.

### Content

An `sx:when` element may contain elements that are substitutable for any of the following abstract elements:

- sx:task
- sx:content
- sx:recordFilter
- sx:mapXml
- sx:stringable

## Name

sx:otherwise — Otherwise condition of sx:choose

### Attributes

None.

### Content

An `sx:when` element may contain elements that are substitutable for any of the following abstract elements:

- sx:task
- sx:content
- sx:recordFilter
- sx:mapXml
- sx:stringable

## Name

sx:include — Include another resources script

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
href | Yes | URI | A URI identifying a resources script.

## Content

None.

## Name

sx:onError — Catches an exception raised by a sx:task element, to be revisited

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

One or more action elements from the following list.

- sx:serialize

## Examples

Example 9. Apply a stylesheet to a fault raised in the book-order document handler.

      <sx:service id="post-book-order">
        <sx:serialize>
          <sx:transform>
             <sx:content ref="myns:book-order"/>
             <sx:xslt ref="myns:confirm-order"/>
          </sx:transform>
          <sx:onError>
            <sx:transform>
              <sx:xslt ref="myns:book-order"/>
            </sx:transform>
          </sx:onError>
        </sx:serialize>
      </sx:service>

## Name

sx:raiseError — Raises an exception inside an sx:onError, to be revisited

└ sx:task, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- A specialized sx:stringable element, for example, a sx:toString element, or a literal value.

## Description

A `sx:raiseError` element results in an exception being thrown. It is used inside an sx:onError element.

## See also

- sx:onError

## Name

sx:resources — The root element of a resources script

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ns | No | URI | The default namespace for the pages, documents, styles and serializers defined in this resources script.

## Content

The list of elements that may be defined with a qualified name at the top level of the resources script includes all the elements that are defined in the sx:instructions refsection of the servingxml.xml configuration file. These include

- Any number of sx:include elements
- Any number of elements derived from sx:content, including sx:document, sx:dynamicContent, and sx:recordContent elements.
- Any number of sx:service elements.
- Any number of sx:xslt elements
- Any number of sx:saxSink based elements.
- Any number of sx:recordMapping elements."/>.
- Any number of sx:inverseRecordMapping elements."/>.
- Any number of sx:flatFile elements."/>.

## Name

sx:runService — Runs another service from within a resources script

└ sx:task, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
service | Yes | SubstitutionExpr | An expression that evaluates to a QName identifying a service.

## Content

- Optionally, any number of sx:parameter elements.
- A sx:service element (Deprecated, use the service attribute instead)
- Optionally, a specialized sx:streamSource element, for example, a sx:fileSource element.
- Optionally, a specialized sx:streamSink element, for example, a sx:fileSink element.

## Description

A `sx:runService` element is a task that invokes a service.

## See also

- sx:transform

## Name

sx:service — Service

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- One or more sx:task elements, including sx:serialize, sx:recordStream or jm:sendMail elements.

## Examples

Example 10. Books page.

      <sx:service id="books">
        <sx:serialize>
          <sx:transform>
            <sx:content ref="myns:books"/>
            <sx:xslt ref="myns:books"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

## See also

- sx:expiryOptions
- sx:onError

## Name

sx:task — Abstract element standing for a task

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference the id of a task.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:task`, such as sx:transform.

## Examples

## See also

- sx:serialize
- sx:transform
- sx:recordStream
- sx:runService
- jm:sendMail

# String Elements

## Name

sx:concat — Common attributes for elements

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
separator | No | char | A separator to separate each string value in the content.
quoteSymbol | No | char | A symbol to surround each string value.

## Content

Any number of sx:stringable elements.

## Description

## Name

sx:convertDate — Convert date

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
fromFormat | Yes | String | The format of the input string, which must must follow the syntax specified for the JDK SimpleDateFormat class.
toFormat | No | String | The format of the output string, which must must follow the syntax specified for the JDK SimpleDateFormat class. Defaults to the date format for the default locale.

## Content

An input string in the `fromFormat`, or a sx:stringable element that evaluates to an input string in the `fromFormat`. If the input string is empty, an empty (null) value is produced.

## Description

## Name

sx:convertToDateTime — Convert to datetime

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
format | Yes | String | The format of the input string, which must must follow the syntax specified for the JDK SimpleDateFormat class.
inputTimezone | No | String | The time zone for the input date. Defaults to the Java default time zone.
outputTimezone | No | String | The time zone for the output date. Defaults to the Java default time zone.

## Content

Lexical representation of one the eight XML Schema date/time datatypes, or an sx:stringable element that evaluates to a lexical representation. If the input string is empty, an empty (null) value is produced.

## Description

## Name

sx:currentDate — Current date

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

None.

## Description

The current date is output as a string with a lexical representation as defined for xs:date of XML Schema Part 2: Datatypes.

## Name

sx:currentDateTime — Current datetime

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

None.

## Description

The current date is output as a string with a lexical representation as defined for xs:dateTime of XML Schema Part 2: Datatypes.

## Name

sx:currentTime — Current time

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

None.

## Description

The current time is output as a string with a lexical representation as defined for xs:time of XML Schema Part 2: Datatypes.

## Name

sx:date — Deprecated, replaced by sx:currentDateTime and sx:formatDateTime

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
format | No | String | The format of the output string, which must must follow the syntax specified for the JDK SimpleDateFormat class. Defaults to the date format for the default locale.

## Content

None.

## Description

## Name

sx:escapeMarkup — Evaluate children as a string, escaping XML tags

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

Literal text

## Description

The `sx:escapeMarkup` element results in its content being output as a string. The main reason for enclosing text within an `sx:escapeMarkup` element is to allow XML element tags to appear escaped in the text.

## Name

sx:findAndReplace — Find and replace in a string using regular expressions

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
searchFor | Yes | Regex | Match sub-sequences of the input string against this pattern.
replaceWith | Yes | String | Replace all matches with this expression. Dollar signs ($) may be used as references to captured subsequences in the match regular expression, and backslashes (\) may be used to escape literal characters.
caseSensitive | No | true | false | Defaults to `true` .
useRegex | No | true | false | Defaults to `true`.

## Content

Any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

## Description

The `sx:findAndReplace` element applies a regular expression to its content, and replaces matched content with a replacement string. The value of the regular expression is defined by the `searchFor` attribute, which searches for all subsequences in the content that match the pattern

## Examples

Example 11. Fix date.

In this example, you have an input record with a field `service_from_date`, which has the value

    2005-06-28 00:00:00

You want to change it to

    20050628

You can make the replacement with the `sx:findAndReplace` element as follows.

      <sx:findAndReplace searchFor="([0-9]{4})-([0-9]{2})-([0-9]{2})(.*)" replaceWith="$1$2$3">
        <sx:toString value="{service_from_date}"/>
      </sx:findAndReplace>

Example 12. Remove commas from amount.

In this example, you have an input record with a field `PLAN_IT_COST`, which has the value

    2,500,300.00

You want to change it to

    2500300.00

You can make the replacement with the `sx:findAndReplace` element as follows.

      <sx:findAndReplace searchFor="," replaceWith ="">
        <sx:toString value="{PLAN_IT_COST}"/>
      </sx:findAndReplace>

Example 13. Literal find and replace.

      <sx:positionalField name="price2" width="10" justify="right" label="Price">
        <sx:defaultValue>
          <sx:findAndReplace searchFor ="." replaceWith="," useRegex="false">
            <sx:toString value="{price}"/>
          </sx:findAndReplace>
        </sx:defaultValue>
      </sx:positionalField>

## Name

sx:formatDateTime — Format datetime

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
format | No | String | The format of the output string, which must must follow the syntax specified for the JDK SimpleDateFormat class. Defaults to the date format for the default locale.

## Content

Lexical representation of one the eight XML Schema date/time datatypes, or an sx:stringable element that evaluates to a lexical representation.

## Description

## Name

sx:lineNumber — Output current line number

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

None.

## Description

Evaluates to the current line number of the input.

## Name

sx:preserveMarkup — Evaluate children as a string, preserving XML tags without escaping them

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

Literal text

## Description

The `sx:preserveMarkup` element results in its content being output as a string. The main reason for enclosing text within an `sx:preserveMarkup` element is to allow XML element tags to appear unescaped in the text.

## Name

sx:replace — Deprecated, replaced in 0.9.2 by sx:findAndReplace

└ sx:string, sx:stringable

## Name

sx:string — Abstract element standing for any string element, e.g. sx:toString

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference the id of a string.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:stringable`, such as sx:toString.

## See also

- sx:date
- sx:convertDate
- sx:findAndReplace
- sx:toString
- sx:escapeMarkup
- sx:preserveMarkup

## Name

sx:stringable — Abstract element standing for any element that can render itself as a string, e.g. sx:transform

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference the id of a string.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:stringable`, such as sx:toString.

## See also

- sx:date
- sx:convertDate
- sx:findAndReplace
- sx:toString
- sx:escapeMarkup
- sx:preserveMarkup

## Name

sx:toString — Ouput a string

└ sx:string, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
select | No | XPath expression | Apply an XPath expression to the collection of elements in the XML representation of a record that satisfy the conditon of the `match` pattern. The expression is evaluated as a string.
value | No | SubstitutionExpr | A string value that may contain one or more parameters enclosed in curly braces, e.g. "{$my-param}.xml".
separator | No | char | A separator to separate the pieces if the expression resolves to multiple values.
quoteSymbol | No | char | A symbol to surround the pieces. Deprecated, use a sx:quoteSymbol child element instead.

## Content

- Optionally, a sx:quoteSymbol element, to specify a quote symbol to surround the pieces making up the string.

- Optionally, if there is a `select` attribute, an sx:content element. If supplied, the select expression will be evaluated against this content, otherwise it will be evaluated against the default content.

- Optionally, if there is no `value` or `select` attribute, any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

Optionally, a sx:quoteSymbol element, to specify a quote symbol to surround the pieces making up the string.

## Description

# Stream Source and Sink Elements

## Name

sx:command — Command

## Attributes

None

## Content

Any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

## See also

- sx:commandSink
- sx:commandSource

## Name

sx:commandArg — Command argument

## Attributes

None

## Content

Any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

## See also

- sx:commandSink
- sx:commandSource

## Name

sx:commandSink — Command sink

└ sx:streamSink

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
directory | No | SubstitutionExpr | Optionally, the current working directory.
encoding | No | String | A `charset` name. Defaults to the platform's default `charset`.

## Content

- One sx:command element.

- Optionally, any number of sx:commandArg elements

- Optionally, any number of sx:envVariable elements

## Description

The `sx:commandSink` element is a stream sink that allows a flat file writer or an XML serializer to send its output to the standard input of a shell command. The `sx:commandSink` element executes the command from the sx:command instruction with the arguments passed in the sx:commandArg elements.

## Examples

Example 14. Example of a command sink.

## See also

- sx:streamSink

## Name

sx:commandSource — Command source

└ sx:streamSource

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
directory | No | SubstitutionExpr | Optionally, the current working directory.
encoding | No | String | A `charset` name. Defaults to the platform's default `charset`.

## Content

- One sx:command element.

- Optionally, any number of sx:commandArg elements

- Optionally, any number of sx:envVariable elements

## Description

The `sx:commandSource` element is a stream source that allows a flat file reader or an XML reader to obtain its input from the standard output of a shell command. The `sx:commandSource` element executes the command from the sx:command instruction with the arguments passed in the sx:commandArg elements.

## Examples

Example 15. Example of processing the XML output of a shell command.

The example below executes the shell command `request.exe -request request.xml`, reads its standard output, and writes it to an XML file.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="request">
        <sx:serialize>
          <sx:parameter name="request" value="trade-query.xml"/>
          <sx:xsltSerializer>
              <sx:outputProperty name="indent" value="yes" />
          </sx:xsltSerializer>
          <sx:document>
            <sx:commandSource directory="/WorkingDirectory">
              <sx:envVariable name="ENV_VAR" value="value1"/>
              <sx:command>request.exe</sx:command>
              <sx:commandArg>-request</sx:commandArg>
              <sx:commandArg><sx:toString value="$request"/></sx:commandArg>
            </sx:commandSource>
          </sx:document>
        </sx:serialize>
      </sx:service>

    </sx:resources>

## See also

- sx:streamSource

## Name

sx:defaultStreamSink — Default stream sink

└ sx:streamSink

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
encoding | No | String | A `charset` name. If a `charset` is not supplied, the default will be the `charset` of the default sink, e.g., the platform's default charset if the default sink is a flat file supplied to the command line app with the -o option.

## Content

None.

## See also

- sx:streamSink

## Name

sx:defaultStreamSource — Default stream source

└ sx:streamSource

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
encoding | No | String | A `charset` name. If an `charset` is not supplied, the default will be the `charset` of the default source, e.g., the platform's default charset if the default source is a flat file supplied to the command line app with the -i option.

## Content

None.

## See also

- sx:streamSource

## Name

sx:envVariable — Environment variable

## Attributes

None

## Content

In-line text, or alternatively, any number of sx:stringable elements.

## See also

- sx:commandSink
- sx:commandSource

## Name

sx:fileSink — File sink

└ sx:streamSink

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
directory | No | SubstitutionExpr | An optional directory name.
file | Yes | SubstitutionExpr | The name of the output file, may contain parameters in the form {$myParam}.
encoding | No | String | A `charset` name. If the output is XML, and a `charset` is not supplied, the XML serializer will use the last encoding encountered in the output properties of the transformation pipeline. If the output is a flat file, and a `charset` is not supplied, the default will be the platform's default charset.

## Content

None.

## Examples

Example 16. Example of file sink.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="books">
        <sx:serialize>
          <sx:xsltSerializer>
            <sx:fileSink file="books.xml"/>
          </sx:xsltSerializer>
          <sx:transform>
            <sx:content ref="books"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

      <sx:document id="books">
        <sx:urlSource url="documents/books.xml"/>
      </sx:document>

    </sx:resources>

## See also

- sx:streamSink

## Name

sx:fileSource — File source

└ sx:streamSource

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
directory | No | SubstitutionExpr | An optional directory name.
file | Yes | SubstitutionExpr | The name of the input file, may contain parameters in the form {$myParam}.
encoding | No | String | A `charset` name. If the input is XML, and a `charset` is not supplied, the XML parser will use the encoding specified by the XML declaration. If the input is a flat file, and a `charset` is not supplied, the default will be the platform's default charset.

## Content

None.

## Examples

Example 17. Example of file source.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="books">
        <sx:serialize>
          <sx:transform>
            <sx:document>
              <sx:fileSource file="books.xml"/>
            </sx:document>
          </sx:transform>
        </sx:serialize>
      </sx:service>

    </sx:resources>

## See also

- sx:streamSource

## Name

sx:inlineSource — Inline source

└ sx:streamSource

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

None.

## Examples

Example 18. Example of inline source.

      <sx:flatFileReader id="csv-file-reader">
        <sx:inlineSource>field1,field2
          value1,value2
          value1,value2</sx:inlineSource>
        <sx:fieldDelimiter value=","/>
      </sx:flatFileReader>

## See also

- sx:streamSource

## Name

sx:streamSink — Abstract element standing for a stream sink

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference the id of a stream sink.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:streamSink`, sx:fileSink.

## Examples

## See also

- sx:commandSink
- edt:ftpSink
- sx:fileSink
- sx:defaultStreamSink

## Name

sx:streamSource — Abstract element standing for a stream source

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | No | QName | This attribute is used to reference the id of a stream source.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:streamSource`, such as sx:fileSource.

## Examples

## See also

- sx:commandSource
- edt:ftpSource
- sx:fileSource
- sx:urlSource
- sx:defaultStreamSource

## Name

sx:stringSource — String source

└ sx:streamSource

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

None.

## See also

- sx:streamSource
- sx:inlineSource

## Name

sx:urlSource — URL source

└ sx:streamSource

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
url | Yes | SubstitutionExpr | The name of the input url, may contain parameters in the form {$myParam}.
encoding | No | String | A `charset` name. If the input is XML, and a `charset` is not supplied, the XML parser will use the encoding specified by the XML declaration. If the input is a flat file, and a `charset` is not supplied, the default will be the platform's default charset.

## Content

None.

## Examples

Example 19. Example of url source.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="books">
        <sx:serialize>
          <sx:transform>
            <sx:document>
              <sx:urlSource url="books.xml"/>
            </sx:document>
          </sx:transform>
        </sx:serialize>
      </sx:service>

    </sx:resources>

## See also

- sx:streamSource

# XML Content Producing and Transforming Elements

## Name

sx:assert — Assert

└ sx:content, sx:validator

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
test | Yes | XPath Boolean Expression | An XPath boolean expression applied to the context document.

## Content

- Any number of sx:parameter elements.
- Any combination of string literals and inlined sx:stringable substitutable elements. If the assertion fails, the string expressions will be evaluated in place, forming a message. Leading and trailing whitespace will be trimmed.

## Description

An `sx:assert` instruction allows an XPATH boolean expression to be applied to a subtree of the input XML.

## Examples

Example 20. XPath Boolean assertion about subtree.

      <sx:transform>
        <sx:document ref="t:transaction"/>
        <sx:subtreeFilter path="/transaction/R04">
          <sx:assert test="count(//*) mod 2 = 0">Expected even number of elements.
          </sx:assert>
        </sx:subtreeFilter>
      </sx:transform>

## Name

sx:attribute — Add an attribute to wrapping elements inside a sx:wrap element

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
attribute | Yes | SubstitutionExpr | The name of an attribute to insert into a parent element. The attribute name may contain a field name within curly braces, which will evaluate to the value of the field. The result must evaluate to a QName.
select | No | XPath expression | Apply an XPath expression to the elements in the XML representation of a record that satisfy the conditon of the `match` pattern. The expression is evaluated as a string.
value | No | SubstitutionExpr | Express the attribute value as a literal value, which may contain parameter names and field names enclosed in curly braces. The result must evaluate to a QName.

## Content

- Optionally, if there is a `select` attribute, an sx:content element. If supplied, the select expression will be evaluated against this content, otherwise it will be evaluated against the default content.

- Optionally, if there is no `value` or `select` attribute, any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

## See also

- sx:wrap

## Name

sx:batchedSerializer — Batched serializer

└ sx:saxSink

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
path | Yes | SAXPath | A SAXPath expression, which identifies subtrees.
batchSize | Yes | Integer | The number of subtrees in a batch.
maxFiles | No | Integer | The maximum number of batch files.

## Content

- One sx:saxSink based element, such as an sx:xsltSerializer element.

## Examples

Example 21. Writing out countries XML with a maximum of 50 countries to a batch.

        <sx:serialize>
          <sx:transform>
            <sx:content ref="countries"/>
          </sx:transform>
          <sx:batchedSerializer path="country" batchSize="50">
            <sx:xsltSerializer>
              <sx:fileSink file="output/countries-{$sx:batchSequenceNumber}.xml"/>
            </sx:xsltSerializer>
          </sx:batchedSerializer>
        </sx:serialize>

## Name

sx:cachedContent — Cached content

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- A sx:content specialization, such as a sx:document, sx:recordContent or sx:transform element.

## Description

This element permits caching of XML content.

## See also

- sx:content
- sx:expiryOptions

## Name

sx:content — Abstract element standing for XML content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:content`, such as sx:document, sx:transform or sx:xslt.

## Examples

Example 22. Using a `sx:content` element to refer to dynamic content.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="books">
        <sx:serialize>
          <sx:transform>
            <sx:content ref="books"/>
            <sx:xslt ref="books"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

      <sx:dynamicContent name="books" class="samples.books.BookCatalog">
        <sx:key>
          <sx:keyField name="category"/>
        </sx:key>
      </sx:dynamicContent>

    </sx:resources>

## See also

- sx:cachedContent
- sx:document
- sx:dynamicContent
- sx:recordContent
- saxon:xquery

## Name

sx:customEmitter — Deprecated, aliased to sx:customSerializer

└ sx:saxSink

## Name

sx:customSerializer — Custom serializer

└ sx:saxSink

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
class | Yes | Java Class | The name of a Java class that implements `com.servingxml.io.saxsink.SaxSink`.

## Content

- Optionally, any number of sx:property elements.

## Examples

Example 23. Defining an Apache fop emitter.

      <sx:customSerializer id="fop-serializer"
                        class="com.servingxml.extensions.fop.xmlpipeline.FopEmitter">
      </sx:customSerializer>

Example 24. Serializing an xsl-fo XML tree with an Apache fop serializer to produce pdf.

      <sx:service id="pulp">
        <sx:serialize>
          <sx:saxSink ref="myns:fop-serializer"/>
          <sx:transform>
            <sx:content ref="myns:pulp"/>
            <sx:xslt ref="myns:novel-fo"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

## Name

sx:document — XML document

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, a sx:streamSource element, or a sx:saxSource element, or an in-line XML document. Defaults to the default stream source, e.g. a file passed with the -i option on the command line.
- Optionally, any number of sx:parameter elements.

## Examples

Example 25. Defining a document with reference to an XML file.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:document id="countries">
        <sx:urlSource url="documents/countries.xml"/>
      </sx:document>

    </sx:resources>

## See also

- sx:expiryOptions

## Name

sx:documentSequence — Document sequence

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
wrapWith | No | SubstitutionExpr | Wrap all documents in the sequence with this root element.

## Content

- Optionally, any number of sx:parameter elements.

Either

- Any number of sx:content elements.

or

- One element that is substitutable for a sx:recordReader, for example, an sx:directoryReader element, and
- One element that is substitutable for a sx:content, for example, an sx:document element.

## Description

This instruction allows you to read a collection of XML documents on a file system as a sequence of documents wrapped with a root element. The results are streamed so that an arbitrarily large number of files may be processed.

## Examples

Example 26. Defining a sequence of XML documents wrapped with the default root element "documents".

This example uses an sx:directoryReader element to read the names of the files in a directory called "data", and an sx:document element to load each of the files.

    <sx:documentSequence wrapWith="documents">
      <sx:directoryReader directory="data"/>
      <sx:document>
          <sx:fileSource directory="{parentDirectory}" file="{name}"/>
      </sx:document>
    </sx:documentSequence>

Example 27. Defining a sequence of XML documents wrapped with the root element "documents".

Note that an sx:recordStream element is also subtitutable for a sx:recordReader, which allows additional filtering on the contents of the file system. An sx:transform element is likewise subtitutable for a sx:content, which allows additional transformation and validation of the individual documents.

    <sx:documentSequence wrapWith="documents">
      <sx:recordStream>
        <sx:directoryReader directory="data"/>
        <sx:restrictRecordFilter>
          <sx:fieldRestriction field="name" pattern="countries.*[.]xml"/>
        </sx:restrictRecordFilter>
      </sx:recordStream>
      <sx:transform>
        <sx:document>
          <sx:fileSource directory="{parentDirectory}" file="{name}"/>
        </sx:document>
        <msv:schemaValidator>
          <sx:urlSource url="data/countries.xsd"/>
        </msv:schemaValidator>
      </sx:transform>
    </sx:documentSequence>

## See also

- sx:document

## Name

sx:dynamicContent — Dynamic content

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
class | Yes | Java Class | The name of a Java class that implements com.servingxml.components.content.dynamic.RequestHandler and, optionally, com.servingxml.components.content.dynamic.Cacheable.

## Content

- Optionally, a sx:key element.
- Optionally, any number of sx:parameter elements.

## Examples

Example 28. Defining a document with reference to a Java class that simulates a SAX parser.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:dynamicContent name="books" class="samples.books.BookCatalog">
        <sx:key>
          <sx:keyField name="category"/>
        </sx:key>
      </sx:dynamicContent>

    </sx:resources>

## See also

- sx:content
- sx:expiryOptions

## Name

sx:saxSink — Abstract element standing for a sink of SAX events

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference an id.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:saxSink` e.g. sx:xsltSerializer.

## See also

- sx:xsltSerializer
- sx:customSerializer
- fop:foSerializer

## Name

sx:emptyDocument — Empty XML document

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

None.

## Examples

## Name

sx:filter — Deprecated in 1.0.0, use sx:content instead

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:content`, such as sx:xslt.

## Examples

## Name

sx:key — Key for XML content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- One or more sx:keyField elements.

## Examples

See sx:dynamicContent.

## Name

sx:keyField — Key field

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | No | Name | Reference to the name of a parameter. On a request, the field value will be set to that parameter value.

## Content

None.

## Examples

See sx:dynamicContent.

## See also

- sx:key
- sx:dynamicContent

## Name

sx:outputProperty — Output property for XML serializer

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | Yes | String | The output property name.
value | Yes | SubstitutionExpr | The output property value.

## Content

None.

## Description

For an XSLT serializer, the value of a single `xsl:output` property.

## Examples

Example 29. Parameter substitution in sx:outputProperty

    <sx:xsltSerializer>
      <sx:outputProperty name="encoding" value="{$encodingParam}"/>
      <sx:outputProperty name="indent" value="{$indentModeParam}"/>
    </sx:xsltSerializer>

## Name

sx:processSubtree — Perform tasks on subtrees of an XML document

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
path | Yes | SAXPath | A SAXPath expression.

## Content

- Any number of sx:parameter elements.
- Any number of sx:task elements.

## Description

A `sx:processSubtree` instruction processes a matched subtree of an XML document, executing one or more tasks applied to the subtree.

Note that any elements that may appear as children of sx:service may also appear as child elements of `sx:processSubtree`, the only difference being that for the subservice, the default XML content is the fragment identified by the `path` attribute.

## Examples

Example 30. Serializing individual document fragments to separate files.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="invoices">
        <sx:transform>
          <!-- Here we extract a document fragment from the SAX stream -->
          <sx:processSubtree path="/invoices/invoice">
             <sx:serialize>
                <!-- We initialize a parameter with an XPATH expression
                     applied to the document fragment -->
                <sx:parameter name="invoice-name" select="@id"/>
                <sx:xsltSerializer>
                  <sx:fileSink file="output/invoice{$invoice-name}.html"/>
                </sx:xsltSerializer>
                <sx:transform>
                  <sx:xslt><sx:urlSource url="styles/invoice2html.xsl"/></sx:xslt>
                </sx:transform>
             </sx:serialize>
          </sx:processSubtree>
        </sx:transform>
      </sx:service>

    </sx:resources>

## Name

sx:recordContent — XML content from records

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | No | QName | The name of the content, used as the document element in default record mappings, defaults to "document".

## Content

- Optionally, a sx:recordReader element.
- Optionally, a sx:recordMapping element. If the record mapping element is omitted, the mapping is performed according to default rules that map fields to elements of the same name.
- Optionally, any number of sx:parameter elements.

## Examples

Example 31. Example of Comma Separated Value (csv) file content.

      <sx:recordContent id="countries">
        <sx:flatFileReader>
          <sx:urlSource url="books/countries.csv"/>
          <sx:flatFile>
            <sx:flatFileBody>
              <sx:flatRecordType name="country">
                <sx:fieldDelimiter value=","/>
                <sx:delimitedField name="countryCode"/>
                <sx:delimitedField name="countryName"/>
              </sx:flatRecordType>
            </sx:flatFileBody>
          </sx:flatFile>
        </sx:recordReader>

        <sx:recordMapping>
          <countries>
            <sx:onRecord>
              <country>
                <sx:fieldAttributeMap attribute="countryCode" attribute="countryCode"/>
                <sx:fieldElementMap element="countryName" element="countryName"/>
              </country>
            </sx:onRecord>
          </countries>
        </sx:recordMapping>

      </sx:recordContent>

## See also

- sx:content
- sx:flatFileReader
- sx:sqlReader
- sx:recordMapping

## Name

sx:removeEmptyAttributes — Remove empty attributes from XML elements

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
elements | Yes | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all elements." A namespace prefix followed by a colon followed by the value '*' means all elements belonging to the namespace.
exceptElements | No | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all elements." A namespace prefix followed by a colon followed by the value '*' means all elements belonging to the namespace.
attributes | Yes | NameTest list | A space-separated list of element QNames, or wildcards, to include. The value '*' means "all attributes." A namespace prefix followed by a colon followed by the value '*' means all attributes belonging to the namespace.
exceptAttributes | No | NameTest list | A space-separated list of attribute QNames, or wildcards, to exclude. The value '*' means "all attributes." A namespace prefix followed by a colon followed by the value '*' means all attributes belonging to the namespace.

## Content

None.

## Description

The sx:removeEmptyAttributes instruction checks for attributes of elements that have empty values and removes them from the SAX event stream. The `elements` and `attributes` attributes are mandatory and identify the elements that should be examined for empty attributes. The value '*' may be used to mean "all elements" or "all attributes".

## Examples

Example 32. Strip all empty attributes except fileNumber from all elements.

    <sx:transform>
      <sx:document/>
      <sx:removeEmptyAttributes elements="*" attributes="*" exceptAttributes="fileNumber"/>
    </sx:transform>

## See also

- sx:removeEmptyElements

## Name

sx:removeEmptyElementFilter — Deprecated, aliased to sx:removeEmptyElements

└ sx:content

## Name

sx:removeEmptyElements — Remove empty elements from XML content

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
elements | Yes | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all elements." A namespace prefix followed by a colon followed by the value '*' means all elements belonging to the namespace.
except | No | NameTest list | Deprecated, use `exceptElements` instead.
exceptElements | No | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all elements." A namespace prefix followed by a colon followed by the value '*' means all elements belonging to the namespace.

## Content

None.

## Description

The sx:removeEmptyElements instruction checks for elements that have no attributes or content and removes them from the SAX event stream. The `elements` attribute is mandatory and identifies the elements that should be suppressed if found to be empty. The value '*' may be used to mean "all elements", in which case exceptions may be indicated with the `exceptElements` attribute.

## Examples

Example 33. Strip elements date1 and date2 from document if empty.

    <sx:transform>
      <sx:document/>
      <sx:removeEmptyElements elements="date1 date2"/>
    </sx:transform>

## See also

- sx:removeEmptyAttributes

## Name

sx:saxFilter — SAX filter

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
class | Yes | Java Class | The name of a Java class that implements org.xml.sax.XMLFilter.

## Content

- Optionally, any number of sx:property elements.

## Examples

Example 34. Constructing a SAX pipeline.

The example below shows a resources script that implements a SAX pipeline. `PreFilter` and `PostFilter` are the names of Java classes that implement the `org.xml.sax.XMLFilter` interface.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="myService">
        <sx:serialize>
          <sx:transform>
            <sx:document>
              <sx:urlSource url="documents/mixed-up.xml"/>
            </sx:document>
            <sx:saxFilter class="PreFilter"/>
            <sx:xslt>
              <sx:urlSource url="styles/filter.xsl"/>
            </sx:xslt>
            <sx:saxFilter class="PostFilter"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

    </sx:resources>

## See also

- sx:content
- sx:transform

## Name

sx:saxReader — SAX reader

└ sx:saxSource

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
class | Yes | Java Class | The name of a Java class that implements org.xml.sax.XMLReader.
systemId | No | SubstitutionExpr | The system id passed to the `parse` method of the reader. Defaults to an empty string.

## Content

- Optionally, any number of sx:property elements.

## Examples

Example 35. Implementing a pipeline with SAX events generated by a custom parser.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="pipeline">
        <sx:serialize>
          <sx:transform>
            <sx:document>
              <sx:saxReader class="MySaxReader"/>
            </sx:document>
            <sx:saxFilter class="PreFilter"/>
            <sx:xslt><sx:urlSource url="styles/filter.xsl"/></sx:xslt>
            <sx:saxFilter class="PostFilter"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

    </sx:resources>

The class `MySaxReader` could look something like this.

    public class MySaxReader implements XMLReader ...

      private static final AttributesImpl NO_ATTRIBUTES = new AttributesImpl();

      public void parse(String systemId)
      throws IOException, SAXException {
        if (contentHandler != null) {
          contentHandler.startDocument();
          contentHandler.startElement("","xxx","",NO_ATTRIBUTES);
          ...
          contentHandler.endElement("","xxx","");
          contentHandler.endDocument();
        }
      }

## Name

sx:saxSource — Abstract element standing for a source of SAX events

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:saxSource`, such as sx:saxReader.

## See also

- sx:saxReader

## Name

sx:serialize — Serialize XML content

└ sx:task, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- Optionally, a sx:saxSink element
- Any number of sx:content specializations, such as sx:document, sx:xslt, sx:processSubtree, or sx:choose elements. These will be applied in document order.
- Optionally, a sx:saxSink element.
- A sx:onError element.

## Description

A sx:serialize instruction encloses a sequence of content generation, transformation and serialization steps that result in serialized output of some MIME type.

Usually, the first element in the sequence of sx:content elements is a content producer, such as a sx:document or sx:recordContent element. An empty sx:document element defaults to reading from the default stream source, e.g. a file passed with the -i option of the console application. If the first element is not itself a content producer, the initial content is the default stream of SAX events.

## See also

- sx:transform

## Name

sx:style — Deprecated, aliased to sx:xslt

└ sx:content

## Name

sx:tagTee — Splits the stream of SAX events

└ sx:content, sx:task, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- Optionally, a sx:saxSink element.
- Any number of sx:content elements, such as sx:saxFilter, sx:choose, and sx:xslt elements. These will be applied in document order.

## See also

## Name

sx:subtreeFilter — Apply XML filters to subtrees of XML

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
path | Yes | SAXPath | A SAXPath expression.

## Content

- Any number of sx:parameter elements.
- Any number of sx:content elements, for example, any number of sx:xslt, sx:removeEmptyElements or sx:transform elements.

## Description

An `sx:subtreeFilter` instruction allows a sequence of XML filters to be applied to a subtree of an XML document.

## Examples

## Name

sx:transform — Transform XML content

└ sx:content, sx:task, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:content specializations, such as sx:document, sx:xslt, sx:processSubtree, or sx:choose elements. These will be applied in document order.

## Description

A `sx:transform` instruction encloses a sequence of content production and transformation steps that result in transformed content.

Usually, the first element in the sequence of sx:content elements is a content producer, such as a sx:document or sx:recordContent element. An empty sx:document element defaults to reading from the default stream source, e.g. a file passed with the -i option of the console application. If the first element is not itself a content producer, the initial content is the default stream of SAX events.

## Examples

Example 36. Transforming the books XML document with the books XSLT stylesheet.

      <sx:service id="books">
        <sx:serialize>
          <sx:transform>
            <sx:content ref="myns:books"/>
            <sx:xslt ref="myns:books"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

## See also

- sx:serialize

## Name

sx:wrap — Wrap XML content with surrounding elements

└ sx:content, sx:task, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- Literal content, which in turn may contain
  - Any number of sx:content specialization, such as sx:xslt, sx:processSubtree, or sx:choose elements. These will be applied in document order.
- Optionally, a sx:saxSink element. Defaults to the default SAX sink. Use an empty sx:xsltSerializer element to serialize to the default stream sink.

## Description

The `sx:wrap` instruction wraps the content that its children write to the default XML sink with containing elements.

## Examples

Example 37. Extracting subtrees and wrapping them in containing tags

      <sx:wrap>
        <sx:xsltSerializer/>
        <envelope>
          <header>
            <sx:attribute name="mode" value="xml"/>
            <creationDate>
              <sx:currentDateTime/>
            </creationDate>
          </header>
          <body>
            <myns:books xmlns:myns="http://mycompany.com/mynames/"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xsi:schemaLocation="url2">
              <!-- Content to be wrapped -->
              <sx:transform>
                <sx:document/>
                <sx:processSubtree path="/myns:books/myns:book">
                  <sx:choose>
                    <sx:when test="@categoryCode='F'">
                      <sx:transform/>
                    </sx:when>
                  </sx:choose>
                </sx:processSubtree>
              </sx:transform>
            </myns:books>
          </body>
          <trailer>This is a trailer element</trailer>
        </envelope>
      </sx:wrap>

## See also

- sx:transform

## Name

sx:xmlEmitter — Deprecated, aliased to sx:xsltSerializer

└ sx:saxSink

## Name

sx:xslt — XSLT stylesheet

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
documentBase | No | SubstitutionExpr | This attribute is used to explicitly set the base for document URI resolution. The base can be relative, in which case it is resolved relative to the location of the resources script.

## Content

- Optionally, any number of sx:parameter elements.
- Optionally, a sx:withParameters element to identify the parameters that need to be passed to the stylesheet.
- The XSLT stylesheet, as a sx:streamSource or sx:saxSource instance, or appearing in-line.

## Description

The `sx:xslt` instruction applies an `XSLT` stylesheet to the `XML` content on the pipeline and produces transformed `XML` content. All sx:parameter elements appearing in the body of the instruction are passed to the `XSLT` processor.

If the stylesheet specifies output properties with an `xsl:output` element, the `ServingXML` implementation will capture them, and these become the default output properties for the next stage of the pipeline processing. For example, if an `xsl:output` element specifies that method="text", and if that property is not later overriden in downstream processing, an XSLT serializer on the final stage will output only the text nodes.

If an XSLT stylesheet uses the `document` function to reference a URI, the `ServingXML` implementation will first attempt to resolve that URI against XML content appearing in the `ServingXML` resources script. The `URI` will be resolved if it matches the `URI` obtained by concatenating the namespace URI and the local name of an sx:content instance. If there is no match, URI resolution reverts to the default URI resolution of the `XSLT` processor.

The `ServingXML` implementation will recognize query parameters such as ?directory=input in the URI passed to the `document()` function. These parameters may be used by a resolved sx:content instance.

## Examples

Example 38. Defining a style with reference to an XSLT file.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:xslt id="books">
        <sx:urlSource url="books/books.xsl"/>
      </sx:xslt>

    </sx:resources>

Example 39. A stylesheet that that takes a parameter named "category".

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="books">
        <sx:serialize>
          <sx:transform>
            <sx:content ref="books"/>
            <sx:xslt ref="books"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

      <sx:document id="books">
        <sx:urlSource url="documents/books.xml"/>
      </sx:document>

      <sx:xslt id="books">
        <!--sx:parameter name="category"><sx:defaultValue>F</sx:defaultValue></sx:parameter-->
        <sx:withParameters parameters="category"/>
        <sx:urlSource url="styles/books.xsl"/>
      </sx:xslt>

    </sx:resources>

## See also

- sx:content
- sx:parameter

## Name

sx:xsltSerializer — XML serializer of XSLT processor

└ sx:saxSink

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:outputProperty elements.
- Optionally, a specialized sx:streamSink element, for example, a sx:fileSink or a edt:ftpSink element.

## Examples

Example 40. Transforming content and serializing it to XML.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="myPipeline">
        <sx:serialize>
          <sx:transform>
            <sx:document><sx:fileSource file="input.xml"/></document>
            <sx:xslt><sx:urlSource url="filter.xsl"/></sx:xslt>
          </sx:transform>
          <sx:xsltSerializer>
            <sx:fileSink file="output.xml"/>
            <sx:outputProperty name="indent" value="yes"/>
          </sx:xsltSerializer>
        </sx:serialize>
      </sx:service>

    </sx:resources>

# Record Readers, Writers and Filters

## Name

sx:aggregateRecords — Deprecated, replaced by sx:composeRecord

## Name

sx:and — And operator

└ sx:restriction

## Attributes

None

## Content

Any number of sx:restriction elements.

## Description

This instruction allows record criteria to be grouped in an "and" relationship.

## Examples

Example 41. (a or b)

    <sx:restrictRecordFilter>
      <sx:and>
        <sx:recordRestriction recordType="claim_detail"/>
        <sx:fieldRestriction field="valid" pattern="y"/>
      </sx:and>
    </sx:restrictRecordFilter>

## See also

- sx:restrictRecordFilter
- sx:or

## Name

sx:batchRecords — Batch records

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
batchSize | Yes | Number | The batch size.
recordType | No | NameTest | Count records whose record types match the record type name test.

## Content

None

## Description

This instruction allows a sequential stream of records to be broken up into batches. As each batch is begun, the parameter `sx:batchSequenceNumber` is set, just before the record writer initializes its ouput stream.

## Examples

Example 42. Breaking up a sequential stream of records into batches.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="countries">
        <sx:recordStream>
          <sx:flatFileReader>
            <sx:fileSource file="data/countries.csv"/>
            <sx:flatFile ref="countriesFile"/>
          </sx:flatFileReader>
          <sx:batchRecords batchSize="50"/>
          <sx:flatFileWriter>
            <sx:fileSink file="output/countries-{$sx:batchSequenceNumber}.csv"/>
            <sx:flatFile ref="countriesFile"/>
          </sx:flatFileWriter>
        </sx:recordStream>
      </sx:service>

      <sx:flatFile id="countriesFile">
        <sx:commentStarter value="#"/>
        <sx:flatFileBody>
          <sx:flatRecordType name="country">
            <sx:fieldDelimiter value=","/>
            <sx:delimitedField name="code"/>
            <sx:delimitedField name="name" trimLeading="true"/>
          </sx:flatRecordType>
        </sx:flatFileBody>
      </sx:flatFile>

    </sx:resources>

## Name

sx:batchedRecordWriter — Write records in batches

└ sx:recordWriter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
batchSize | Yes | Number | The batch size.
recordType | No | NameTest | Count records whose record types match the record type name test.

## Content

None

## Description

This instruction allows a sequential stream of records to be broken up into batches. As each batch is begun, the parameter `sx:batchSequenceNumber` is set, just before the record writer initializes its ouput stream.

## Examples

Example 43. Breaking up a sequential stream of records into batches.

      <sx:service id="countries">
        <sx:recordStream>
          <sx:flatFileReader>
            <sx:fileSource file="data/{$rootName}.csv"/>
            <sx:flatFile ref="my-input-file-layout"/>
          </sx:flatFileReader>
          <sx:batchedRecordWriter batchSize="50">
            <sx:flatFileWriter>
              <sx:fileSink file="output/{$rootName}-{$sx:batchSequenceNumber}.csv"/>
              <sx:flatFile ref="my-output-file-layout"/>
            </sx:flatFileWriter>
          </sx:batchedRecordWriter>
        </sx:recordStream>
      </sx:service>

## Name

sx:composeRecord — Compose a composite record

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | Yes | SubstitutionExpr | The name of the composite record type.
repeatingGroup | Yes | QName | The name of the field containing a list of records.
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to `true`
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to `startTest`.
compositeRecordType | No | QName | Deprecated in version 0.9.5 - replaced by recordType attribute.
repeatingGroupField | No | QName | Deprecated in version 0.9.5 - replaced by repeatingGroup attribute.

## Content

- Optionally, any number of sx:parameter elements.

- Any number of sx:newField elements.

## Description

This instruction allows you to compose a composite record from a group of adjacent records.

Grouping begins when processing a record and the `startTest` expression evaluates as `true`. Grouping ends on a succeeding record when the `endTest` expression evaluates as `true`, or when a parent group to which this group belongs ends. The test for the end of a group is exclusive, that is, if `endTest` evaluates as `true` when processing a record, that record is excluded from the group.

The test expressions are XPATH expressions evaluated against the XML representations of the current (sx:current) and previous (sx:previous) records.

## Examples

Example 44. Grouping records into a composite record.

The input is three records of record type "orderRemarks",

REMTEI | REM
--- | ---
REM | AAAA
REM | BBB
REM | CCC

The XML representation of the "orderRemarks" records is

    <orderRemarks><REMTEI>REM</REMTEI><REM>AAAA</REM></orderRemarks>
    <orderRemarks><REMTEI>REM</REMTEI><REM>BBBB</REM></orderRemarks>
    <orderRemarks><REMTEI>REM</REMTEI><REM>CCCC</REM></orderRemarks>

The `sx:composeRecord` element below composes the three input records into a composite record with record type "composite", and with a repeating group field "detail" that contains the three original records. It creates a new field "remarks" whose value is calculated from the original records.

        <sx:composeRecord recordType="composite" repeatingGroup="detail"
                    startTest="sx:current/orderRemarks"
                    endTest="not(sx:current/orderRemarks)">
          <sx:newField name="remarks" select="detail/orderRemarks/REM"/>
        </sx:composeRecord>

The output is the composite record.

    <composite>
      <detail>
        <orderRemarks><REMTEI>REM</REMTEI><REM>AAAA</REM></orderRemarks>
        <orderRemarks><REMTEI>REM</REMTEI><REM>BBBB</REM></orderRemarks>
        <orderRemarks><REMTEI>REM</REMTEI><REM>CCCC</REM></orderRemarks>
      </detail>
      <remarks>AAAA BBBB CCCC</remarks>
    </composite>

## See also

- sx:decomposeRecord

## Name

sx:customRecordFilter — Custom record filter

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
class | Yes | Java Class | The name of a Java class that implements com.servingxml.components.recordio.RecordFilter

## Content

- Optionally, any number of sx:property elements.

## Examples

Example 45. Writing a custom record filter.

The example below shows a fragment of a resources script that uses a record filter. `HotRecordFilter` is the names of a Java class that extends the `com.servingxml.components.recordio.AbstractRecordFilter` class, which provides a default implementation of the `com.servingxml.components.recordio.RecordFilter` interface.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:recordContent id="hot">
        <sx:flatFileReader>
          <sx:flatFile ref="hotFlatFile"/>
          <sx:customRecordFilter class="HotRecordFilter"/>
        </sx:flatFileReader> ...

      </sx:recordContent>

      <sx:flatFile id="hotFlatFile">
        <sx:flatFileBody>
          <sx:flatRecordTypeChoice>
            <sx:positionalField name="record-type" width="5"/>
            <sx:when  test="record-type='BKP84'">
              <sx:flatRecordType name="bkp84">
                <sx:positionalField name="record-type-prefix"  width="3"/>
                <sx:positionalField name="record-type"  start="1" width="5"/>
                <sx:positionalField name="value" width="7"/>
                <sx:positionalField name="amount" width="2"/>
                <sx:positionalField name="currency" width="3"/>
                <sx:positionalField name="precision" width="1"/>
              </sx:flatRecordType>
            </sx:when>
            <sx:when test="record-type='BKT06'"> ...

          </sx:flatRecordTypeChoice>
        </sx:flatFileBody>
      </sx:flatFile> ...

    </sx:resources>

The `HotRecordFilter` class is implemented as shown below. The class needs to be compiled and put in the classpath where the framework can find it, for example, by adding it to the `target\servingxml\classes` directory.

    import com.servingxml.app.Flow;
    import com.servingxml.app.ServiceContext;
    import com.servingxml.components.recordio.AbstractRecordFilter;
    import com.servingxml.util.Name;
    import com.servingxml.util.QualifiedName;
    import com.servingxml.util.record.Record;
    import com.servingxml.util.record.RecordBuilder;
    import com.servingxml.util.ServingXmlException;

    public class HotRecordFilter extends AbstractRecordFilter {
      private static final Name BKP84_RECORD_TYPE = new QualifiedName("bkp84");
      private static final Name AMOUNT_NAME = new QualifiedName("amount");
      private static final Name PRECISION_NAME = new QualifiedName("precision");
      private static final Name CALCULATED_AMOUNT_NAME = new QualifiedName("calculatedAmount");

      public void writeRecord(ServiceContext context, Flow flow)
       {

        Record record = flow.getRecord();
        Flow newFlow = flow;
        if (record.getRecordType().getName().equals(BKP84_RECORD_TYPE)) {
          RecordBuilder recordBuilder = new RecordBuilder(record);
          String amountString = record.getString(AMOUNT_NAME);
          if (amountString == null) {
            throw new ServingXmlException("amount is NULL");
          }
          String precisionString = record.getString(PRECISION_NAME);
          if (precisionString == null) {
            throw new ServingXmlException("precision is NULL");
          }
          int amount = Integer.parseInt(amountString,16);
          int precision = Integer.parseInt(precisionString);
          double calculatedAmount = (double)amount/Math.pow(10.0,(double)precision);
          recordBuilder.setDouble(CALCULATED_AMOUNT_NAME,calculatedAmount);
          record = recordBuilder.toRecord();
          newFlow = flow.replaceRecord(context, record);
        }

        super.writeRecord(context, newFlow);
      }
    }

## See also

- sx:customRecordReader

## Name

sx:customRecordReader — Custom record reader

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
class | Yes | Java Class | The name of a Java class that implements com.servingxml.components.recordio.RecordFilter

## Content

- Optionally, any number of sx:property elements.

## Examples

Example 46. Writing a custom record reader.

The example below shows a resources script that uses a record reader. `TradeRecordFilter` is the names of a Java class that extends the `com.servingxml.components.recordio.AbstractRecordReader` class, which provides a default implementation of the `com.servingxml.components.recordio.RecordReader` interface.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="trades">
        <sx:serialize>
          <sx:transform>
            <sx:content ref="trades"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

      <sx:recordContent id="trades">
        <sx:customRecordReader class="TradeRecordReader"/>
        <sx:recordMapping ...
      </sx:recordContent>

    </sx:resources>

The `TradeRecordReader` class is implemented as shown below. The class needs to be compiled and put in the classpath where the framework can find it, for example, by adding it to the `target\servingxml\classes` directory.

    import com.servingxml.app.ServiceContext;
    import com.servingxml.components.recordio.AbstractRecordReader;
    import com.servingxml.app.Flow;
    import com.servingxml.util.Name;
    import com.servingxml.util.QualifiedName;
    import com.servingxml.util.ServingXmlException;
    import com.servingxml.util.record.Record;
    import com.servingxml.util.record.RecordBuilder;

    public class TradeRecordReader extends AbstractRecordReader {
      private static final Name TRADE_RECORD_TYPE = new QualifiedName("trade");
      private static final Name TRANSACTION_RECORD_TYPE = new QualifiedName("transaction");
      private static final Name RECORD_TYPE_NAME = new QualifiedName("record_type");
      private static final Name ID_NAME = new QualifiedName("id");
      private static final Name TRADE_DATE_NAME = new QualifiedName("trade_date");
      private static final Name TRADE_TIME_NAME = new QualifiedName("trade_time");
      private static final Name DESCRIPTION_NAME = new QualifiedName("description");
      private static final Name REFERENCE_NAME = new QualifiedName("reference");

      public void readRecords(ServiceContext context, Flow flow)
       {

        //  Start the record stream
        startRecordStream(context, flow);

        RecordBuilder trRecordBuilder = new RecordBuilder(TRADE_RECORD_TYPE);
        RecordBuilder tnRecordBuilder = new RecordBuilder(TRANSACTION_RECORD_TYPE);

        Record record;

        trRecordBuilder.setString(RECORD_TYPE_NAME,"TR");
        trRecordBuilder.setString(ID_NAME,"0001");
        trRecordBuilder.setString(TRADE_DATE_NAME,"03/25/2005");
        trRecordBuilder.setString(TRADE_TIME_NAME,"01:50:00");
        trRecordBuilder.setString(DESCRIPTION_NAME,"This is a trade record");
        record = trRecordBuilder.toRecord();
        trRecordBuilder.clear();

        //  Write the "trade" record
        writeRecord(context, flow, record);

        tnRecordBuilder.setString(RECORD_TYPE_NAME,"TN");
        tnRecordBuilder.setString(ID_NAME,"0002");
        tnRecordBuilder.setString(REFERENCE_NAME,"X1234");
        tnRecordBuilder.setString(DESCRIPTION_NAME,"A child transaction");
        record = tnRecordBuilder.toRecord();
        tnRecordBuilder.clear();

        //  Write the first "transaction" record
        writeRecord(context, flow, record);

        tnRecordBuilder.setString(RECORD_TYPE_NAME,"TN");
        tnRecordBuilder.setString(ID_NAME,"0003");
        tnRecordBuilder.setString(REFERENCE_NAME,"X1235");
        tnRecordBuilder.setString(DESCRIPTION_NAME,"Another child transaction");
        record = tnRecordBuilder.toRecord();
        tnRecordBuilder.clear();

        //  Write the second "transaction" record
        writeRecord(context, flow, record);

        //  End the record stream
        endRecordStream(context, flow);
      }
    }

## See also

- sx:customRecordFilter

## Name

sx:decomposeRecord — Decompose a composite record into its constituent subrecords

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | Yes | QName | Decompose records of this type.
repeatingGroup | Yes | QName | Decompose records of the specified type on this repeating group field.
subrecordType | No | SubstitutionExpr | The type of the decomposed records. Defaults to the record type of the subrecords in the repeating group.
compositeRecordType | No | QName | Deprecated in version 0.9.5 - replaced by recordType attribute.
repeatingGroupField | No | QName | Deprecated in version 0.9.5 - replaced by repeatingGroup attribute.
ofRecordType | No | QName | Deprecated - use `recordType` instead.
onField | No | QName | Deprecated - use `repeatingGroup` instead.

## Content

- Optionally, any number of sx:parameter elements.

## Description

This instruction allows you to decompose a composite record into multiple records, one for each record in a repeating group.

## See also

- sx:composeRecord

## Name

sx:directoryReader — Read a directory

└ sx:recordReader

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recurse | No | true|false | Set to "true" to recurse through a directory tree, "false" otherwise. Defaults to "false." (For backwards compatability, yes/no is also supported.)
maxItems | No | Number | The maximum number of directory items to read.
directory | Yes | SubstitutionExpr | The root directory.

## Content

- Optionally, any number of sx:parameter elements.

- Optionally, a sx:fileFilter element.

## Description

Each record will have type

- directory - if the entry is a directory
- file - if the entry is a file.

Each record will contain the following fields:

- parentDir - the parent directory, if any (deprecated, use parentDirectory instead)
- parentDirectory - the parent directory, if any
- pathname - the pathname of the file or directory.
- name - the name of the file or directory.
- lastModified - the time the file was last modified, with a lexical representation as defined for xs:dateTime of XML Schema Part 2: Datatypes.
- size - the file size, in bytes

## Name

sx:discard — Discard a record

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- A message explaining the reason for discarding the record.

  .

## Description

This instruction results in the current record being discarded. One place it can be used is in the sx:unmatchedRecord section of a sx:restrictRecordFilter element.

## See also

- sx:restrictRecordFilter

## Name

sx:discardFilter — Deprecated, replaced by sx:discardHandler

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | Apply discard handling to records of this type. Defaults to records of any type.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:recordReader and sx:recordFilter elements, followed by
- Optionally, one sx:recordWriter element.

## Description

This instruction allows you to write discarded records to file or database.

### Examples

Example 47. No discard filter.

    <sx:recordContent id="countries">
      <sx:recordStream>
        <sx:flatFileReader>
          <sx:urlSource url="data/countries.csv"/>
          <sx:flatFile ref="countries-file"/>
        </sx:flatFileReader>
        <msv:recordValidator>
          <sx:urlSource url="data/country-record.xsd"/>
        </msv:recordValidator>
      <sx:recordStream>
      <sx:recordMapping ref="countries-xml-mapping"/>
    </sx:recordContent>

In this example, if the record validator throws an exception, the `ServingXML` implementation logs an error message and aborts.

Example 48. An empty discard filter.

    <sx:recordContent id="countries">
      <sx:recordStream>
        <sx:flatFileReader>
          <sx:urlSource url="data/countries.csv"/>
          <sx:flatFile ref="countries-file"/>
        </sx:flatFileReader>
        <sx:discardFilter/>
        <msv:recordValidator>
          <sx:urlSource url="data/country-record.xsd"/>
        </msv:recordValidator>
      </sx:recordStream>
      <sx:recordMapping ref="countries-xml-mapping"/>
    </sx:recordContent>

In this example, the record flows through the discard filter before reaching the record validator. If the record validator throws an exception, the exception is caught in the discard handler. The discard filter logs the error and discards the bad record. The next record is then read.

Example 49. A discard filter that writes the bad record with a message to a discard file.

    <sx:recordContent id="countries">
      <sx:recordStream>
        <sx:flatFileReader>
          <sx:urlSource url="data/countries.csv"/>
          <sx:flatFile ref="countriesFile"/>
        </sx:flatFileReader>
        <sx:discardFilter>
          <sx:modifyRecord>
            <sx:newField name="message" value="{$sx:message}"/>
          </sx:modifyRecord>
          <sx:flatFileWriter>
            <sx:fileSink file="output/countryDiscards.csv"/>
            <sx:flatFile ref="discardFile"/>
          </sx:flatFileWriter>
        </sx:discardFilter>
        <msv:recordValidator>
          <sx:urlSource url="data/country-record.xsd"/>
        </msv:recordValidator>
      </sx:recordStream>
      <sx:recordMapping ref="countriesToXmlMapping"/>
    </sx:recordContent>

    <sx:flatRecordType id="country" name="country">
      <sx:fieldDelimiter value=","/>
      <sx:delimitedField name="code"/>
      <sx:delimitedField name="name"/>
    </sx:flatRecordType>

    <sx:flatFile id="discardFile">
      <sx:flatFileBody>
        <sx:flatRecordType name="countryDiscard">
          <sx:fieldDelimiter value=","/>
          <sx:delimitedField name="message"/>
          <sx:flatRecordType ref="country"/>
        </sx:flatRecordType>
      </sx:flatFileBody>
    </sx:flatFile>

In this example, the record flows through the discard filter before reaching the record validator. If the record validator throws an exception, the exception is caught in the discard handler. The discard filter logs the error and writes the bad record along with the error message to a discard file. The next record is then read.

## Name

sx:discardHandler — Discard record handler

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | Apply discard handling to records of this type. Defaults to records of any type.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:recordReader and sx:recordFilter elements, followed by
- Optionally, one sx:recordWriter element.

## Description

This instruction allows you to write discarded records to file or database.

### Examples

Example 50. No discard handler.

    <sx:recordContent id="countries">
      <sx:flatFileReader>
        <sx:urlSource url="data/countries.csv"/>
        <sx:flatFile ref="countries-file"/>
        <msv:recordValidator>
          <sx:urlSource url="data/country-record.xsd"/>
        </msv:recordValidator>
      </sx:flatFileReader>
      <sx:recordMapping ref="countries-xml-mapping"/>
    </sx:recordContent>

In this example, if the record validator discards a record, the record reaches the default handler, which logs an error message and aborts.

Example 51. A logging discard handler.

    <sx:recordContent id="countries">
      <sx:recordStream>
        <sx:flatFileReader>
          <sx:urlSource url="data/countries.csv"/>
          <sx:flatFile ref="countries-file"/>
        </sx:flatFileReader>
        <msv:recordValidator>
          <sx:urlSource url="data/country-record.xsd"/>
        </msv:recordValidator>
        <sx:discardHandler>
          <sx:log message="{$sx:message}"/>
        </sx:discardHandler>
      </sx:recordStream>
      <sx:recordMapping ref="countries-xml-mapping"/>
    </sx:recordContent>

If the record validator discards the record, the record is passed down the pipeline to the discard handler. The discard handler logs the error and throws the discarded record away. The next record is then read.

Example 52. A discard handler that writes the discarded record with a message to a discard file.

      <sx:recordContent id="countries">
        <sx:recordStream>
          <sx:flatFileReader>
            <sx:urlSource url="data/countriesWithDiscards.csv"/>
            <sx:flatFile ref="countriesFile"/>
          </sx:flatFileReader>
          <msv:recordValidator>
            <sx:urlSource url="data/country-record.xsd"/>
          </msv:recordValidator>
          <sx:discardHandler>
            <sx:log message="{$sx:message}"/>
            <sx:modifyRecord>
              <sx:newField name="message" value="{$sx:message}"/>
            </sx:modifyRecord>
            <sx:flatFileWriter>
              <sx:fileSink file="output/countryDiscards.csv"/>
              <sx:flatFile ref="discardFile"/>
            </sx:flatFileWriter>
          </sx:discardHandler>
        </sx:recordStream>
        <sx:recordMapping ref="countriesToXmlMapping"/>
      </sx:recordContent>

      <sx:flatRecordType id="countryRecord" name="country">
        <sx:fieldDelimiter value=","/>
        <sx:delimitedField name="code"/>
        <sx:delimitedField name="name"/>
      </sx:flatRecordType>

      <sx:flatFile id="countriesFile">
        <sx:commentStarter value="#"/>
        <sx:flatFileBody>
          <sx:flatRecordType ref="country"/>
        </sx:flatFileBody>
      </sx:flatFile>

      <sx:flatFile id="discardFile">
        <sx:flatFileBody>
          <sx:flatRecordType name="countryDiscard">
            <sx:fieldDelimiter value=","/>
            <sx:delimitedField name="message"/>
            <sx:flatRecordType ref="countryRecord"/>
          </sx:flatRecordType>
        </sx:flatFileBody>
      </sx:flatFile>

If the record validator discards the record, the record is passed down the pipeline to the discard handler. The discard handler logs the error and writes the discarded record along with the error message to a discard file. The next record is then read.

## Name

sx:fieldRestriction — Restrict field

└ sx:restriction

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
field | Yes | QName | The name of the field.
pattern | Yes | Regex | The regular expression to be tested against the value of the field.
negate | No | true/false | Reverses the restriction.

## Content

None.

## Description

This instruction allows records to be filtered by applying a regular expression to the value of a field.

The `negate` attribute reverses the restriction. By setting the `negate` attribute to `true`, the restriction applies only if the records don't match the condition.

## Name

sx:fieldValidator — Field validator

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
fieldName | Yes | QName | The name of the field to validate.
message | Yes | SubstitutionExpr | A message indicating the error if validation fails.

## Content

- Any number of sx:valueRestriction elements.

- Any number of sx:validator elements (in particular, sx:recordValidator elements for validating subrecords)

## Description

## See also

- sx:recordValidator

## Name

sx:fileFilter — File filter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
pattern | Yes | Regex | The regular expression to be tested against the file name.
negate | No | true/false | Reverses the restriction.

## Content

None.

## Description

This instruction allows you to filter the files returned by a directory reader, by applying a regular expression to each file name.

The `negate` attribute reverses the restriction. By setting the `negate` attribute to `true`, the restriction applies only if the filename does not match the condition.

## See also

- sx:directoryReader

## Name

sx:log — Log

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
message | No | SubstitutionExpr | A string value that may contain parameters inside curly braces, e.g. "{$message}".
level | No | error/warning/notice/trace | Defaults to "error".

## Content

Optionally, if there is no `message` attribute, any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

## Description

The `sx:log` element is used in a record stream to write a message to the log.

The message may be specified either by a `message` attribute or by the content.

## Examples

Example 53. Example of logging a message in a discard handler.

      <sx:recordStream>
        <sx:flatFileReader>
          <sx:urlSource url="data/countriesWithDiscards.csv"/>
          <sx:flatFile ref="countriesFile"/>
        </sx:flatFileReader>
        <msv:recordValidator>
          <sx:urlSource url="data/country-record.xsd"/>
        </msv:recordValidator>
        <sx:discardHandler>
          <sx:log message="{$sx:message}"/>
          <sx:modifyRecord>
            <sx:newField name="message" value="{$sx:message}"/>
          </sx:modifyRecord>
          <sx:flatFileWriter>
            <sx:fileSink file="output/countryDiscards.csv"/>
            <sx:flatFile ref="discardFile"/>
          </sx:flatFileWriter>
        </sx:discardHandler>
      </sx:recordStream>

## See also

- sx:recordStream

## Name

sx:modifyRecord — Modify a record

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
newRecordType | No | QName | The record type name of the modified record. Defaults to the record type name of the original record.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:newField elements.

## Description

This instruction modifies the current record in a record stream. Each sx:newField child element adds a new field if none currently exists with the same name, or else replaces the existing field.

## Examples

See Example 52, “A discard handler that writes the discarded record with a message to a discard file.”

## Name

sx:newField — Add a field to a record

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | Yes | QName | The name of the field.
value | No | SubstitutionExpr | A string value that may reference a parameter or field inside curly braces, e.g. "{$my-param}.xml".
select | No | XPath expression | An XPath expression evaluated against the XML representation of the record.
match | Yes | Regex | The regular expression to be tested against the value of the field.

## Content

- Optionally, if there is a `select` attribute, an sx:content element. If supplied, the select expression will be evaluated against this content, otherwise it will be evaluated against the XML representation of the record.

- Optionally, if there is no `value` or `select` attribute, any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

## Description

This instruction allows a new field to be added to a record.

## See also

- sx:modifyRecord
- sx:newRecord

## Name

sx:newRecord — Create a new record

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | The type of the new record. Defaults to the type of the original record.
fields | No | NameTest list | A space-separated list of names of fields to be copied to the new record. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to "*".
except | No | QName list | (deprecated, use exceptFields instead)
exceptFields | No | QName list | A space-separated list of names of fields not to be copied to the new record. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to the empty string.

## Content

- Any number of sx:newField elements.

## Description

This instruction allows records to be changed in a record stream.

## See also

- sx:replaceRecord

## Name

sx:or — Or condition

└ sx:restriction

## Attributes

None

## Content

Any number of sx:restriction elements.

## Description

This instruction allows record criteria to be grouped in an "or" relationship.

## Examples

Example 54. (a or b) and c

    <sx:restrictRecordFilter>
      <sx:and>
        <sx:or>
          <sx:recordRestriction recordType="claim_detail"/>
          <sx:recordRestriction recordType="expense_detail"/>
        </sx:or>
        <sx:fieldRestriction field="valid" match="y"/>
      </sx:and>
    </sx:restrictRecordFilter>

## See also

- sx:restrictRecordFilter
- sx:and

## Name

sx:parameterReader — Read parameters as record

└ sx:recordReader

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | The name of the record type given to the parameters.

## Content

None.

## Description

Reads a single record of parameter values.

## Examples

Example 55. Updating a database record with passed parameter values.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="updateEmployee">
        <sx:recordStream>
          <sx:parameterReader recordType="employee"/>
          <sx:sqlWriter>
            <sx:sqlConnectionPool ref="jdbcPool"/>
            <sx:sqlUpdate>
              UPDATE EMP SET JOB = '{$job}' WHERE EMPNO='{$empNo}'
            </sx:sqlUpdate>
          </sx:sqlWriter>
        </sx:recordStream>
      </sx:service>

      <sx:sqlConnectionPool id="jdbcPool"
                            driver="oracle.jdbc.driver.OracleDriver"
                            databaseUrl="jdbc:oracle:thin:@127.0.0.1:1521:dev"
                            user="scott"
                            password="spring"
                            minConnections="2"
                            testStatement="SELECT * FROM DUAL"/>

    </sx:resources>

## Name

sx:processRecord — Perform tasks on individual record

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | Task records of this type. Defaults to records of any type.

## Content

- Any number of sx:parameter elements.
- Any number of sx:task elements.

## Description

A `sx:processRecord` instruction processes the current record, executing one or more tasks applied to the current record or its XML representation.

Note that any elements that may appear as children of sx:service may also appear as child elements of `sx:processSubtree`, the only difference being that for the subservice, the default XML content is the XML representation of the current record.

## Name

sx:processRecordFilter — Deprecated, replaced by sx:processRecord

## Name

sx:processRecords — Deprecated, aliased to sx:recordStream

## Name

sx:regexFieldCriteria — Deprecated, aliased to sx:fieldRestriction

## Name

sx:quoteSymbol — Quote symbol

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
value | No | Character | Deprecated - replaced by `character` in 0.9.1.
character | No | Character | The character to optionally enclose field values. Defaults to the double quotation mark.
escapedBy | No | Character | Deprecated - replaced by `escapeCharacter` in 0.9.1.
escapeCharacter | No | Character | The escape character used to escape the quote symbol, e.g. the backslash ('\') or the quote symbol itself.
escapeWith | No | String | Deprecated - replaced by `escapeSequence` in 0.9.1.
escapeSequence | No | String | The character sequence used to replace the special character, e.g. '\"' or '""' to escape a double quote.

## Content

None.

## Description

This instruction defines the quote character that is used to enclose field values, and the escape sequence used to escape quote characters in field values.

## Examples

Example 56. A double quote character with a backslash escape character.

      <sx:quoteSymbol character='"' escapeCharacter="\"/>

Example 57. A single quote character escaped with """.

      <sx:quoteSymbol character="'" escapeSequence="&quot;"/>

## See also

- sx:flatRecordType
- sx:delimitedField
- sx:sqlQuery
- sx:sqlUpdate

## Name

sx:recordAggregator — Deprecated, replaced by sx:composeRecord

## Name

sx:recordProjection — Project a subset of fields

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | Produce a subset of fields for records of this type, or for all records if no type specified.
newRecordType | No | QName | The type of the new record. Defaults to the type of the input record.
fields | No | NameTest list | A space-separated list of names of fields to be copied to the new record. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to "*".
exceptFields | No | QName list | A space-separated list of names of fields not to be copied to the new record. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to the empty string.

## Content

- Optionally, any number of sx:parameter elements.

## Description

This instruction produces a new stream of records that contains all the records from the original stream but only a subset of the fields for records of the specified record type, eliminating duplicates in the vertically sliced records (if any.)

## See also

- sx:discard

## Name

sx:recordFilter — Abstract element standing for a record filter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference an id.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any `sx:recordFilter` specialization, such as sx:restrictRecordFilter, sx:discardHandler, or msv:recordValidator. Note that the list includes record readers.

## Examples

## See also

- sx:customRecordFilter
- msv:recordValidator
- sx:restrictRecordFilter
- sx:replaceRecord
- sx:processRecord
- sx:recordStream
- sx:log
- sx:discardHandler

## Name

sx:recordReader — Abstract element standing for a record reader

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference an id.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any `sx:recordReader` specialization, such as sx:flatFileReader or sx:recordStream.

## See also

- sx:sqlReader
- sx:flatFileReader
- sx:recordStream

## Name

sx:recordRestriction — Restriction on a record

└ sx:restriction

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | The name of the record type.
test | No | XPath | An XPath boolean expression evaluated against the XML representation of the record.
negate | No | true/false | Reverses the restriction.

## Content

None.

## Description

This instruction allows records to be filtered by record type or, more generally, an XPath expression evaluated against the XML representation of the record (in which case the record type is the root element.) Either the `recordType` or the `test` attribute, but not both, must be set.

The `negate` attribute reverses the restriction. By setting the `negate` attribute to `true`, the restriction applies only if the records don't match the condition.

## Name

sx:recordWriter — Abstract element standing for a record writer

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference the id of a record writer.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:recordWriter`, such as sx:flatFileWriter.

## See also

- sx:sqlWriter
- sx:flatFileWriter

## Name

sx:recordStream — A record stream

└ sx:recordReader, sx:recordFilter, sx:recordWriter, sx:task, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:recordReader and sx:recordFilter elements, followed by
- Optionally, one sx:recordWriter element.

## Description

If you want to have additional record writers in a `sx:recordStream` element, use one or more sx:recordTee elements.

## Name

sx:recordTee — Split record stream

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:recordReader and sx:recordFilter elements, followed by
- Optionally, one sx:recordWriter element.

## Description

This instruction allows a tee to be inserted in the record stream.

## Name

sx:recordTest — Deprecated, replaced by sx:recordRestriction

## Name

sx:recordValidator — Validate record

└ sx:recordFilter, sx:validator

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | Validate records of this type.
message | No | SubstitutionExpr | A message indicating the error if validation fails.

## Content

- Optionally, any number of sx:parameter elements.

- Any number of sx:validator substitutable elements, such as sx:fieldValidator, sx:assert or msv:schemaValidator, for validating the fields of the record.

## Description

This instruction supports validation of records.

## Examples

Example 58. Validating fields of a record with regular expressions

    <sx:recordStream>
      <sx:flatFileReader>
        <sx:flatFile ref="fra-flat-file"/>
      </sx:flatFileReader>
      <sx:recordValidator message="Error in trade {trade_id}.">
        <sx:fieldValidator field="buy_sell_code"
                          message="Invalid buy_sell_code {buy_sell_code}.">
          <sx:or>
            <sx:valueRestriction pattern="BUY"/>
            <sx:valueRestriction pattern="SELL"/>
          </sx:or>
        </sx:fieldValidator>
        <sx:fieldValidator field="start_date"
                           message="Invalid start_date {start_date}.">
          <sx:valueRestriction pattern="(19|20)\d\d[/](0[1-9]|1[012])[/](0[1-9]|[12][0-9]|3[01])"/>
        </sx:fieldValidator>
        <sx:fieldValidator field="maturity_date"
                           message="Invalid maturity_date {maturity_date}.">
          <sx:valueRestriction pattern="(20|21)\d\d[/](0[1-9]|1[012])[/](0[1-9]|[12][0-9]|3[01])"/>
        </sx:fieldValidator>
      </sx:recordValidator>
      <sx:discardHandler>
        <sx:log message="{$sx:message}"/>
        <sx:modifyRecord>
          <sx:newField name="message" value="{$sx:message}"/>
        </sx:modifyRecord>
        <sx:flatFileWriter>
          <sx:fileSink file="output/fra-error.csv"/>
        </sx:flatFileWriter>
      </sx:discardHandler>
    </sx:recordStream>

Example 59. Validating fields of a record with XPATH boolean expressions

    <sx:recordStream>
      <sx:flatFileReader>
        <sx:flatFile ref="fra-flat-file"/>
      </sx:flatFileReader>
      <sx:recordValidator message="Error in trade {trade_id}.">
        <sx:assert test="buy_sell_code = 'BUY' or buy_sell_code = 'SELL'">
          Invalid buy_sell_code <sx:toString value="{buy_sell_code}"/>.
        </sx:assert>
      </sx:recordValidator>
      <sx:discardHandler>
        <sx:log message="{$sx:message}"/>
        <sx:modifyRecord>
          <sx:newField name="message" value="{$sx:message}"/>
        </sx:modifyRecord>
        <sx:flatFileWriter>
          <sx:fileSink file="output/fra-error.csv"/>
        </sx:flatFileWriter>
      </sx:discardHandler>
    </sx:recordStream>

Example 60. Validating a record with an XML schema

    <sx:recordStream>
      <sx:flatFileReader>
        <sx:flatFile ref="countriesFile"/>
      </sx:flatFileReader>
      <sx:recordValidator>
        <msv:schemaValidator>
          <sx:urlSource url="data/country-record.xsd"/>
        </msv:schemaValidator>
      </sx:recordValidator>
      <sx:discardHandler>
        <sx:log message="{$sx:message}"/>
      </sx:discardHandler>
    </sx:recordStream>

## See also

- sx:fieldValidator
- sx:assert
- msv:schemaValidator

## Name

sx:replaceRecord — Replace record with one or more other records

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | Apply changes to records of this type. Defaults to records of any type.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:newRecord elements.

## Description

This instruction allows records to be changed in a record stream.

Example 61. Splitting a record into multiple records.

This example shows how to split a single record containing both customer and order information into separate customer and order records.

      <sx:recordStream>
        <sx:flatFileReader>
          <sx:flatFile>
            <sx:flatFileBody>
              <sx:flatRecordType name="order">
                <sx:positionalField name="customer-name" width="20"/>
                <sx:positionalField name="customer-id" width="10"/>
                <sx:positionalField name="order-id" width="10"/>
                <sx:positionalField name="op-code" width="7"/>
              </sx:flatRecordType>
            </sx:flatFileBody>
          </sx:flatFile>
        </sx:flatFileReader>
        <sx:replaceRecord recordType="order">
          <sx:newRecord recordType="customer" fields="customer-name customer-id"/>
          <sx:newRecord recordType="order" fields="order-id op-code"/>
        </sx:replaceRecord>

        ...

      </sx:recordStream>

## Name

sx:replaceRecordFilter — Deprecated in version 1.0.2, replaced by sx:replaceRecord

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | Apply changes to records of this type. Defaults to records of any type.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:newRecord elements.

## Description

This instruction allows records to be changed in a record stream.

## Name

sx:restrictRecordType — Deprecated, aliased to sx:recordRestriction

## Name

sx:restriction — Abstract element standing for a restriction

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference an id.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:recordFilter`, such as sx:fieldRestriction.

## Examples

## See also

- sx:recordRestriction
- sx:fieldRestriction

## Name

sx:restrictField — Deprecated, aliased to sx:fieldRestriction

## Name

sx:restrictRecordFilter — Restrict records

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
operator | No | and/or | Deprecated. As of version 0.6.2, replaced by sx:or and sx:and child elements. The boolean operator to apply to the sx:restriction child elements, "and" or "or". Defaults to "or".

## Content

- Optionally, any number of sx:parameter elements.

- Any number of specializations of the abstract element sx:restriction, in particular, any number of sx:recordRestriction and sx:fieldRestriction elements.

- Optionally, an sx:unmatchedRecord element, containing a record pipeline that will be executed if the record does not match the restrictions. This record pipeline may contain any number of sx:recordFilter and sx:recordWriter elements, and in particular may end with an sx:discard element if you wish to discard an unmatched record.

## Description

This instruction allows records to be filtered by applying a regular expression to the value of a field.

## See also

- sx:discard

## Name

sx:unmatchedRecord — A record stream

### Attributes

None

### Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:recordReader and sx:recordFilter elements, followed by
- Optionally, one sx:recordWriter element.

### Description

Handles unmatched records.

## Name

sx:restrictRecordType — Deprecated, aliased to sx:recordRestriction

## Name

sx:subtreeRecordReader — Read subtrees of XML document as records

└ sx:recordReader

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- Optionally, a sx:content specialization, such as a sx:document, sx:recordContent or sx:transform element. If omitted, defaults to the default stream of SAX events.
- An sx:inverseRecordMapping element.

## Description

Adapts XML to a record stream.

## Examples

Example 62. Adapting the "books" XML file to a record stream.

    <sx:resources xmlns:sx="http://www.servingxml.com/core"
                            xmlns:myns="http://mycompany.com/mynames/">

      <sx:service id="books2pos">
        <sx:recordStream>
          <sx:subtreeRecordReader>
            <sx:inverseRecordMapping ref="booksToFileMapping"/>
            <sx:transform>
              <sx:document><sx:urlSource url="data/books.xml"/></document>
            </sx:transform>
          </sx:subtreeRecordReader>
          <sx:flatFileWriter>
            <sx:flatFile ref="booksFile"/>
          </sx:flatFileWriter>
        </sx:recordStream>
      </sx:service>

      <sx:inverseRecordMapping id="booksToFileMapping">
        <sx:onSubtree path="/myns:books/myns:book">
          <sx:flattenSubtree recordType="book">
            <sx:subtreeFieldMap select="myns:title" field="title"/>
            <sx:subtreeFieldMap select="@categoryCode" field="category"/>
            <sx:subtreeFieldMap select="myns:author" field="author"/>
            <sx:subtreeFieldMap select="myns:price" field="price"/>
          </sx:flattenSubtree>
        </sx:onSubtree>
      </sx:inverseRecordMapping>

      <sx:flatFile id="booksFile">
        <sx:flatFileHeader>
          <sx:flatRecordType ref="bookType"/>
          <sx:annotationRecord/>
        </sx:flatFileHeader>
        <sx:flatFileBody>
          <sx:flatRecordType ref="bookType"/>
        </sx:flatFileBody>
        <sx:flatFileTrailer>
          <sx:annotationRecord></sx:annotationRecord>
          <sx:annotationRecord>This is a trailer record</sx:annotationRecord>
        </sx:flatFileTrailer>
      </sx:flatFile>

      <sx:flatRecordType id="bookType" name="bookType">
        <sx:positionalField name="category" label="Category" width="1"/>
        <sx:positionalField name="author" label="Author" width="30"/>
        <sx:positionalField name="title" label="Title" width="30"/>
        <sx:positionalField name="price" label="Price" width="10" justify="right"/>
      </sx:flatRecordType>

    </sx:resources>

## Name

sx:validateField — Deprecated in version 1.0, replaced by sx:fieldValidator

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
fieldName | Yes | QName | The name of the field to validate.
message | Yes | SubstitutionExpr | A message indicating the error if validation fails.

## Content

- Any number of sx:valueRestriction elements.

- Any number of sx:validateRecord elements (for validating subrecords)

## Description

## See also

- sx:recordValidator

## Name

sx:validateRecord — Deprecated in version 1.0, replaced by sx:recordValidator

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | Validate records of this type.
message | No | SubstitutionExpr | A message indicating the error if validation fails.

## Content

- Any number of sx:validateField elements.

## Description

## See also

- sx:recordValidator

## Name

sx:valueRestriction — Restrict value

└ sx:restriction

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
pattern | Yes | Regex | The regular expression to be tested against the value of the field.

## Content

None.

## Description

This instruction allows a field value to be tested with a regular expression.

## See also

- sx:recordValidator

## Name

sx:writeRecords — Deprecated, replaced by sx:recordStream

## Name

sx:xmlRecordReader — Deprecated in version 1.0, replaced by sx:subtreeRecordReader

# Record Mapping Elements

## Name

Grouping Element — Grouping Element

A `grouping element` is an element that has the effect of grouping records. Any sx:mapXml element that contains one or more descendent sx:onRecord elements is a `grouping element`. These include:

- sx:groupBy, sx:innerGroup, sx:outerGroup and sx:groupChoice.
- Any literal element whose content has descendent sx:onRecord elements.
- Any sx:elementMap element whose content has descendent sx:onRecord elements.

Consider the following record mapping:

      <sx:recordMapping id="tasksToXmlMapping">
        <Projects>
          <sx:groupBy fields="project_id">
            <Project>
              <sx:fieldAttributeMap field="project_id" attribute="projectID"/>
              <Tasks>
                <sx:onRecord>
                  <Task>
                    <sx:fieldAttributeMap field="task_name" attribute="name"/>
                    <sx:fieldAttributeMap field="task_start" attribute="start"/>
                    <sx:fieldAttributeMap field="task_finish" attribute="finish"/>
                  </Task>
                </sx:onRecord>
              </Tasks>
            </Project>
          </sx:groupBy>
        </Projects>
      </sx:recordMapping>

The body of this record mapping has a root literal element, `Projects`, which is a `grouping element` because it has a descendent sx:onRecord element. The sx:groupBy element, and the `Project` and `Task` literal elements, are also grouping elements.

A `sx:groupChoice` element processes each child element until it reaches a grouping element that produces a start element but not yet an end element. At that point it stops processing its children.

## Name

Literal Element — Literal Element

A `literal element` is any element appearing in the content of a sx:recordMapping refsection that does not belong to the `ServingXML` vocabulary. Such elements will be mapped directly to XML. A `literal element` may contain other `literal elements` in its content, and in addition it may contain other mapping elements:

- Optionally, any number of sx:fieldAttributeMap elements.
- Optionally, any number of sx:stringable elements.
- Any number of literal elements and sx:mapXml elements.
- Optionally, any number of sx:parameter elements.

## Name

sx:cdata — CDATA output

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

- Any number of literal elements and sx:mapXml elements.

- Optionally, any number of sx:parameter elements.

## Description

The content of a `sx:cdata` element will be enclosed by a CDATA refsection,

    <![CDATA[  ...
      ]]>

## Remarks

- The `sx:cdata` element does not seem to work properly with saxon 6.5.5 or saxonb 8.6.1. It has been tested successively with xalan 2.7.0.

## See also

- sx:recordMapping
- sx:fieldElementMap

## Name

sx:defaultFieldAttributeMap — Default field attribute map

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
fields | Yes | NameTest list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace.
exceptFields | No | QName list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to the empty string.

## Content

- Optionally, any number of sx:parameter elements.

## See also

- sx:defaultFieldElementMap

## Name

sx:defaultFieldElementMap — Default field element map

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
fields | Yes | NameTest list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace.
except | No | QName list | Deprecated, use `exceptFields` instead.
exceptFields | No | QName list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to the empty string.

## Content

- Optionally, any number of sx:parameter elements.

## See also

- sx:defaultFieldAttributeMap

## Name

sx:defaultFieldMapping — Deprecated in version 1.0, aliased to sx:defaultFieldElementMap

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
fields | Yes | NameTest list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace.
except | No | QName list | Deprecated, use `exceptFields` instead.
exceptFields | No | QName list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to the empty string.

## Content

- Optionally, any number of sx:parameter elements.

## See also

- sx:defaultFieldAttributeMap

## Name

sx:documentFragment — Deprecated, replaced by sx:nestedContent

└ sx:mapXml

## Name

sx:elementMap — Element map

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
element | Yes | SubstitutionExpr | The name of an element to insert into the output XML content. The element name may contain a field name within curly braces, which will evaluate to the value of the named field. The result must evaluate to a QName.

## Content

- Optionally, any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

- Any number of literal elements and sx:mapXml elements.

- Optionally, any number of sx:parameter elements.

## See also

- sx:recordMapping
- sx:fieldElementMap

## Name

sx:fieldAttributeMap — Map field to attribute

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
attribute | Yes | SubstitutionExpr | The name of an attribute to insert into a parent element. The attribute name may contain a field name within curly braces, which will evaluate to the value of the field. The result must evaluate to a QName.
field | No | QName | Map this field's value to the attribute value.
select | No | XPath expression | Apply an XPath expression to the elements in the XML representation of a record that satisfy the conditon of the `match` pattern. The expression is evaluated as a string.
value | No | SubstitutionExpr | Express the attribute value as a literal value, which may contain parameter names and field names enclosed in curly braces. The result must evaluate to a QName.

## Content

Optionally, if there is no `field`, `value` or `select` attribute, any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

## See also

- sx:recordMapping
- sx:fieldElementMap

## Name

sx:fieldElementMap — Map field to element

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
element | Yes | SubstitutionExpr | The name of an element to insert into the output XML content. The element name may contain a field name within curly braces, which will evaluate to the value of the named field. The result must evaluate to a QName.
match | No | XSLT pattern | Define a condition that an element in the XML representation of a record must satisfy in order to be selected by an XPath expression. Defaults to "/*"
select | No | XPath expression | Apply an XPath expression to the collection of elements in the XML representation of a record that satisfy the conditon of the `match` pattern. The expression is evaluated as a string.
value | No | SubstitutionExpr | Express the element value as a literal value, which may contain parameter names and field names enclosed in curly braces.
field | No | QName | Map this field's value to the element value.

## Content

- Optionally, any number of sx:fieldAttributeMap elements.

- Optionally, if there is no `field`, `value` or `select` attribute, any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

- Optionally, any number of sx:parameter elements.

## Description

This element maps a field value to a single element in the output.

## See also

- sx:fieldElementSequenceMap
- sx:defaultFieldElementMap

## Name

sx:fieldElementSequenceMap — Map field to element sequence

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
element | Yes | SubstitutionExpr | The name of an element to insert into the output XML content. The element name may contain a field name within curly braces, which will evaluate to the value of the named field. The result must evaluate to a QName.
match | No | XSLT pattern | Define a condition that an element in the XML representation of a record must satisfy in order to be selected by an XPath expression. Defaults to "/*"
select | No | XPath expression | Apply an XPath expression to the collection of elements in the XML representation of a record that satisfy the conditon of the `match` pattern. The expression is evaluated as a string.
value | No | SubstitutionExpr | Express the element value as a literal value, which may contain parameter names and field names enclosed in curly braces.
field | No | QName | Map this field's value to the element value.

## Content

Optionally, if there is no `field`, `value` or `select` attribute, any combination of string literals and inlined sx:stringable substitutable elements. The string expressions will be evaluated in place, forming one string. Leading and trailing whitespace will be trimmed.

- Optionally, any number of sx:fieldAttributeMap elements.

- Optionally, any number of sx:parameter elements.

## Description

This element maps a multi-valued field to a sequence of elements.

## Examples

Example 63. Mapping a multi-valued field to a sequence of elements

The pipe delimited file below contains three fields, the third of which is multi-valued, with subfields delimited by a semi-colon.

    father_name|mother_name|children
    Matthew|Sarah|
    Scott||Damian;Janet;Paul

Suppose you want to map it as follows.

    <?xml version="1.0" encoding="UTF-8"?>
    <eg:families xmlns:eg="http://examples.com/">
      <eg:family>
        <eg:father-name>Matthew</eg:father-name>
        <eg:mother-name>Sarah</eg:mother-name>
        <eg:children/>
      </eg:family>
      <eg:family>
        <eg:father-name>Scott</eg:father-name>
        <eg:mother-name/>
        <eg:children>
          <eg:child>Damian</eg:child>
          <eg:child>Janet</eg:child>
          <eg:child>Paul</eg:child>
        </eg:children>
      </eg:family>
    </eg:families>

The record mapping refsection below produces the desired output.

      <sx:recordMapping id="families-to-xml-mapping">
        <eg:families xmlns:eg="http://examples.com/">
          <sx:onRecord>
            <eg:family>
              <sx:fieldElementMap field="father_name" element="eg:father-name"/>
              <sx:fieldElementMap field="mother_name" element="eg:mother-name"/>
              <eg:children>
                <sx:fieldElementSequenceMap field="children" element="eg:child"/>
              </eg:children>
            </eg:family>
          </sx:onRecord>
        </eg:families>
      </sx:recordMapping>

## See also

- sx:fieldElementMap

## Name

sx:groupBy — Group by fields

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | Group applies to fields of this record type.
fields | Yes | QName | A space separated list of fields to group by.

## Content

- Any number of literal elements and sx:mapXml elements.
- Optionally, any number of sx:parameter elements.
- Any number of specializations of sx:sort, including sx:reorderRecords.

## Examples

Example 64. Multiple groups

This example shows how to group the rows in a flat file into two distinct groupings. The table below shows a list of person data and addresses.

    PersonId Name       FirstName       Street              Postcode    CityTown
    1        Jones      Joe             215 Walmer Rd       M5R3P7      Toronto
    1        Jones      Joe             180 Redwood ST      94102-3280  San Francisco
    2        Davis      Ken             212 Harbord St      M5S1H6      Toronto
    3        Morris     Jane            1100 Danforth Ave   M4J1N2      Toronto
    3        Morris     Jane            6 Green St          94111-1402  San Francisco

Now suppose you want to group the person data and addresses separately.

    <?xml version="1.0" encoding="utf-8"?>
    <Persons-Addresses>
      <Persons>
        <Person>
          <PersonId>1</PersonId>
          <Name>Jones</Name>
          <FirstName>Joe</FirstName>
        </Person>
        <Person ...
        <Person ...
      </Persons>
      <Addresses>
        <Address>
          <PersonId>1</PersonId>
          <Street>215 Walmer Rd</Street>
          <PostCode>M5R3P7</PostCode>
          <CityTown>Toronto</CityTown>
        </Address>
        <Address ...
        <Address ...
        <Address ...
        <Address ...
      </Addresses>
    </Persons-Addresses>

This can be done with a record mapping refsection with two `sx:groupBy` sections. The implementation will buffer the records in memory until the first group is finished, and only then do the second.

      <sx:recordMapping id="personsAddressesMapping">
        <Persons-Addresses>
          <Persons>
            <sx:groupBy fields="PersonId">
              <Person>
                <sx:fieldElementMap field="PersonId" element="PersonId"/>
                <sx:fieldElementMap field="Name" element="Name"/>
                <sx:fieldElementMap field="FirstName" element="FirstName"/>
                <sx:onRecord/>
              </Person>
            </sx:groupBy>
          </Persons>
          <Addresses>
            <sx:onRecord>
              <Address>
                <sx:fieldElementMap field="PersonId" element="PersonId"/>
                <sx:fieldElementMap field="Street" element="Street"/>
                <sx:fieldElementMap field="PostCode" element="PostCode"/>
                <sx:fieldElementMap field="CityTown" element="CityTown"/>
              </Address>
            </sx:onRecord>
          </Addresses>
        </Persons-Addresses>
      </sx:recordMapping>

## See also

- sx:onRecord
- sx:fieldAttributeMap
- sx:fieldElementMap

## Name

sx:groupChoice — Choose one of another of alternative groupings

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Any number of literal elements and sx:mapXml elements.
- Optionally, any number of sx:parameter elements.

## Description

A `sx:groupChoice` element can have any number of child grouping elements. A `sx:groupChoice` element processes each child element until it reaches a grouping element that produces a "start" element but not yet an "end" element. At that point it stops processing its children.

Consider the following fragment of a record mapping (from the "hot" example):

      <sx:groupChoice>
        <sx:innerGroup startTest="sx:current//record-type='BKT06'"
                                   endTest="sx:previous//record-type='BKP84'">
          <sx:elementMap element="{type}">
            <sx:onRecord recordType="bkt06">
              <sx:elementMap element="{record-type}">
                <sx:fieldAttributeMap field="value" attribute="attr1"/>
              </sx:elementMap>
            </sx:onRecord>
            <sx:onRecord recordType="bkp84">
              <sx:elementMap element="{record-type}">
                <sx:fieldAttributeMap field="value" attribute="attr1"/>
                <sx:fieldAttributeMap select="integer:valueOf(amount,16) div math:pow(10,precision)"  attribute="amount"/>
                <sx:fieldAttributeMap field="currency" attribute="currency"/>
              </sx:elementMap>
            </sx:onRecord>
          </sx:elementMap>
        </sx:innerGroup>
        <sx:innerGroup startTest="sx:current//record-type-prefix='BOT'"
                                   endTest="sx:previous//record-type-prefix='BOT'">
          <sx:elementMap element="{record-type}s">
            <sx:onRecord>
              <sx:elementMap element="{record-type}">
                <sx:fieldAttributeMap field="value" attribute="attr1"/>
              </sx:elementMap>
            </sx:onRecord>
          </sx:elementMap>
        </sx:innerGroup>
      </sx:groupChoice>

The sx:groupChoice element in this example contains two sx:innerGroup child grouping elements. These elements contain tests that indicate when the group should start (with the output of a "start" element) and when it should end (with the output of an "end" element.) If the first group has started but not yet ended, the second group will not be processed (if it were, the XML tags would be scrambled and the result illegal.).

## Name

sx:innerGroup — Output inner grouping elements

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to `true`
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to `startTest`.

## Content

- Any number of literal elements and sx:mapXml elements.
- Any number of specializations of sx:sort, including sx:reorderRecords.
- Optionally, any number of sx:parameter elements.

## Description

Grouping begins when processing a record and the `startTest` expression evaluates as `true`. Grouping ends on a succeeding record when the `endTest` expression evaluates as `true`, or when a parent group to which this group belongs ends. The test for the end of a group is exclusive, that is, if `endTest` evaluates as `true` when processing a record, that record is excluded from the group.

The test expressions are XPATH expressions evaluated against the XML representations of the current (sx:current) and previous (sx:previous) records.

## Examples

Example 65. Multiple record types to single XML element

This example shows how to map map multiple record types into a single XML element.

The input file contains records of type `A` (owners) and `K` (vehicles).

    ABill Smith 123 Main St  New York      NY10101
    K2001Ford Explorer  5000.00
    AKen  Jones 75 Apple Way San Francisco CA94509
    K2005BMW  750 Il   67235.00

The expected output is as follows.

    <cases>
      <case>
        <first-name>Bill</first-name>
        <last-name>Smith</last-name>
        <address>123 Main St</address>
        <city>New York</city>
        <state>NY</state>
        <zip>10101</zip>
        <year>2001</year>
        <make>Ford</make>
        <model>Explorer</model>
        <value>5000.00</value>
      </case>
      <case>
        <first-name>Ken</first-name>
        <last-name>Jones</last-name>
        <address>75 Apple Way</address>
        <city>San Francisco</city>
        <state>CA</state>
        <zip>94509</zip>
        <year>2005</year>
        <make>BMW</make>
        <model>750 Il</model>
        <value>67235.00</value>
      </case>
    </cases>

The flat file refsection defines separate flat record types for the `A` and `K` records.

      <sx:flatRecordTypeChoice id="caseType" name="caseType">
        <sx:positionalField name="tag" width="1"/>
        <sx:when test="tag='A'">
          <sx:flatRecordType name="A">
            <sx:positionalField name="tag" width="1"/>
            <sx:positionalField name="first-name" width="5"/>
            <sx:positionalField name="last-name" width="6"/>
            <sx:positionalField name="address" width="13"/>
            <sx:positionalField name="city" width="14"/>
            <sx:positionalField name="state" width="2"/>
            <sx:positionalField name="zip" width="5"/>
          </sx:flatRecordType>
        </sx:when>
        <sx:when test="tag='K'">
          <sx:flatRecordType name="K">
            <sx:positionalField name="tag" width="1"/>
            <sx:positionalField name="year" width="4"/>
            <sx:positionalField name="make" width="5"/>
            <sx:positionalField name="model" width="9"/>
            <sx:positionalField name="value" width="8"/>
          </sx:flatRecordType>
        </sx:when>
      </sx:flatRecordTypeChoice>

The record mapping refsection maps the fields from the `A` and `K` records into the same grouping element.

      <sx:recordMapping id="casesToXmlMapping">
        <cases>
          <sx:innerGroup startTest="sx:current/A">
            <case>
              <sx:fieldElementMap field="first-name" element="first-name"/>
              <sx:fieldElementMap field="last-name" element="last-name"/>
              <sx:fieldElementMap field="address" element="address"/>
              <sx:fieldElementMap field="city" element="city"/>
              <sx:fieldElementMap field="state" element="state"/>
              <sx:fieldElementMap field="zip" element="zip"/>
              <sx:innerGroup startTest="sx:current/K">
                <sx:fieldElementMap field="year" element="year"/>
                <sx:fieldElementMap field="make" element="make"/>
                <sx:fieldElementMap field="model" element="model"/>
                <sx:fieldElementMap field="value" element="value"/>
                <sx:onRecord/>
              </sx:innerGroup>
            </case>
          </sx:innerGroup>
        </cases>
      </sx:recordMapping>

In this example, all the output happens inside the grouping instructions, and `sx:onRecord` is empty.

Note that the instructions

      <sx:innerGroup startTest="sx:current/A"> ...
      <sx:innerGroup startTest="sx:current/K"> ...

could also have been written as

      <sx:innerGroup startTest="sx:current//tag='A'"> ...
      <sx:innerGroup startTest="sx:current//tag='K'"> ...

Example 66. Second grouping immediately following first

This example illustrates two groupings of elements where the last record in the first grouping becomes the first record in the second grouping.

The input file contains records of type `E` and `S`.

    E1001FIELD0
    S1001FIELD1FIELD2
    E1002FIELDA
    S1002FIELDBFIELDC

The expected output is as follows.

    <ytds>
      <record fileno="1001">
        <group1>
          <a>FIELD0</a>
          <b>FIELD2</b>
        </group1>
        <group2>
          <c>FIELD1</c>
        </group2>
      </record>
      <record fileno="1002">
        <group1>
          <a>FIELDA</a>
          <b>FIELDC</b>
        </group1>
        <group2>
          <c>FIELDB</c>
        </group2>
      </record>
    </ytds>

The flat file refsection defines separate flat record types for the `E` and `S` records.

      <sx:flatFile id="ytdsFlatFile">
        <sx:flatFileBody>
          <sx:flatRecordTypeChoice>
            <sx:positionalField name="record_type" width="1"/>
            <sx:when test="record_type='E'">
              <sx:flatRecordType name="ERecord">
                <sx:positionalField name="record_type" width="1"/>
                <sx:positionalField name="file_number" width="4"/>
                <sx:positionalField name="efield1" width="6"/>
              </sx:flatRecordType>
            </sx:when>
            <sx:when test="record_type='S'">
              <sx:flatRecordType name="SRecord">
                <sx:positionalField name="record_type" width="1"/>
                <sx:positionalField name="file_number" width="4"/>
                <sx:positionalField name="sfield1" width="6"/>
                <sx:positionalField name="sfield2" width="6"/>
              </sx:flatRecordType>
            </sx:when>
          </sx:flatRecordTypeChoice>
        </sx:flatFileBody>
      </sx:flatFile>

The record mapping refsection puts one field from the `E` record and one field from the `S` record into group 1, and one field from the `S` record into group 2.

      <sx:recordMapping id="ytdsToXmlMapping">
        <ytds>
          <sx:groupBy fields="file_number">
            <record>
              <sx:fieldAttributeMap field="file_number" attribute="fileno"/>
              <sx:innerGroup startTest="sx:current/ERecord">
                <group1>
                  <sx:onRecord recordType="ERecord">
                    <sx:fieldElementMap field="efield1" element="a"/>
                  </sx:onRecord>
                  <sx:onRecord recordType="SRecord">
                    <sx:fieldElementMap field="sfield2" element="b"/>
                  </sx:onRecord>
                </group1>
              </sx:innerGroup>
              <sx:innerGroup startTest="sx:current/SRecord">
                <group2>
                  <sx:onRecord recordType="SRecord">
                    <sx:fieldElementMap field="sfield1" element="c"/>
                  </sx:onRecord>
                </group2>
              </sx:innerGroup>
            </record>
          </sx:groupBy>
        </ytds>
      </sx:recordMapping>

## See also

- sx:outerGroup
- sx:groupChoice
- sx:groupBy

## Name

sx:insertContent — Deprecated in 0.9.3, replaced by sx:nestedContent

└ sx:mapXml

## Name

sx:mapXml — Abstract element standing for any element that maps records to XML

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

None

## Description

This is an abstract element that allows us to refer generically to any record map element.

## Examples

## See also

- sx:fieldElementMap
- sx:transformRecord
- sx:defaultFieldElementMap
- sx:onRecord
- sx:groupBy
- sx:innerGroup
- sx:outerGroup
- sx:groupChoice
- literal

## Name

sx:nestedContent — Nested XML content

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- One or more sx:content elements.

## Examples

Example 67. Inserting content into a record mapping

This example shows how to insert a schedule of dates from a second reader in a record mapping.

    <sx:recordMapping id="swaption-xml-mapping" ...

      <swaption ...

        <sx:choose>
          <sx:when test="option_style_type='BERMUDA'">
            <bermudaExercise>
              <bermudaExerciseDates>
                <sx:nestedContent>
                  <sx:recordContent>
                    <sx:sqlReader>
                      <sx:sqlConnectionPool ref="jdbcPool"/>
                      <sx:sqlQuery recordType="exerciseSchedule"
                                   trim="yes">
                        SELECT E.settlement_date
                        FROM option_exer_schedule_dates E
                        WHERE E.exercise_schedule_id = {sec_id}
                      </sx:sqlQuery>
                    </sx:sqlReader>
                    <sx:recordMapping ref="exerciseScheduleMapping"/>
                  </sx:recordContent>
                </sx:nestedContent>
              </bermudaExerciseDates>
            </bermudaExercise>
          </sx:when>
          <sx:when ...

## See also

- sx:recordMapping

## Name

sx:onRecord — On record event

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | Records with the specified recordType name will trigger this event processing. If no recordType attribute is specified, all records will be processed.
test | No | XPath | An XPath boolean expression evaluated against the XML representation of the record.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of literal elements and sx:mapXml.
- Any number of sx:subrecordMapping elements.
- Any number of sx:recordMapping elements.

## Description

This instruction allows markup to be inserted into the output for each record received event. It may be restricted to records of a certain record type, or, more generally, to records satisfying an XPath expression evaluated against the XML representation of the record (in which case the record type is the root element.) Either the `recordType` or the `test` attribute, but not both, may be set to restrict the instruction to selected records.

## Name

sx:outerGroup — Output outer grouping elements

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to `true`
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to `startTest`.

## Content

- Any number of literal elements and sx:mapXml elements.
- Any number of specializations of sx:sort, including sx:reorderRecords.
- Optionally, any number of sx:parameter elements.

## Description

Grouping begins when processing a record and the `startTest` expression evaluates as `true`. Grouping ends on a succeeding record when the `endTest` expression evaluates as `true`, or when a parent group to which this group belongs ends. The test for the end of a group is exclusive, that is, if `endTest` evaluates as `true` when processing a record, that record is excluded from the group.

The test expressions are XPATH expressions evaluated against the XML representations of the current (sx:current) and previous (sx:previous) records.

A `sx:outerGroup` element has `startTest` and `endTest` attributes to determine the beginning and end of a group. This element, unlike an sx:innerGroup, may allow descendant elements to be produced even if a grouping at this level is not recognized.

This element will not produce any immediate descendents unless a grouping at this level is recognized, it will not produce any content between this element and an immediate descendent grouping element. It will, however, allow content to be produced in a contained grouping element, if the conditions are in effect for grouping at that level.

An `sx:outerGroup` checks the start/end conditions for each record, and if the record does not belong to the group, it still processes the child elements, looking for another contained group element (innerGroup, outerGroup, groupBy, etc.), and if it finds one the start/end conditions for that group are checked. If the record belongs to that contained group, the content of the contained group will be output, but not the content between the ancestor outerGroup and the interior group.

## See also

- sx:onRecord
- sx:innerGroup

## Name

sx:reorderRecords — Reorder records within a group

└ sx:sort

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordTypes | Yes | QName | A space separated list of record types.

## Content

None.

## See also

- sx:innerGroup
- sx:outerGroup
- sx:groupBy
- literal

## Name

sx:recordMapping — Mapping of records to XML

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of literal elements.

## See also

- sx:onRecord
- sx:fieldAttributeMap
- sx:fieldElementMap

## Name

sx:recordSubtreeMap — Deprecated, replaced by sx:transformRecord

## Name

sx:segmentMapping — Deprecated in 0.9.3, replaced by sx:subrecordMapping

└ sx:mapXml

## Name

sx:subrecordMapping — Map subrecords of a composite record to XML

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
field | Yes | QName | The name of a repeating group field to map (deprecated in 0.9.5, use repeatingGroup instead.)
repeatingGroup | Yes | QName | The name of a repeating group field to map.

## Content

- Any number of literal elements and sx:mapXml elements.
- Optionally, any number of sx:parameter elements.

## Name

sx:sort — Abstract element standing for a sort element

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---

## Content

None.

## Description

This is an abstract element that represents sorting.

## Examples

## See also

- sx:reorderRecords

## Name

sx:transformRecord — Transform record to XML

└ sx:mapXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.

- Any number of sx:content elements, such as sx:xslt elements. These will be applied in document order.

## See also

- sx:recordMapping
- sx:defaultFieldElementMap

# Inverse Record Mapping Elements

## Name

sx:documentSubtreeMap — Deprecated, aliased to sx:onSubtree

└ sx:shredXml

## Name

sx:flattenSubtree — Flatten XML subtree

└ sx:shredXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
match | No | XSLT pattern | Define a condition that an element in the XML fragment must satisfy in order to be mapped to a record of the specified type. Defaults to "/*"
recordType | Yes | QName | The record type of the output record.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:subtreeFieldMap elements.

## Name

sx:inverseRecordMapping — Map XML to records

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Any number of sx:onSubtree elements.
- Optionally, any number of sx:parameter elements.

## Description

The `sx:inverseRecordMapping` element takes a stream of XML tags and transforms them to a flow of records. Each record flowing through `ServingXML` must have a recordType, say "book". In the content of an `sx:inverseRecordMapping`, the instructions

        <sx:onSubtree path="/myns:books/myns:book">
          <sx:flattenSubtree recordType="book">
            <sx:subtreeFieldMap select="myns:title" field="title"/>
            <sx:subtreeFieldMap select="myns:author" field="author"/>
          </sx:flattenSubtree>

extract the "myns:book" subtrees from the XML and map them to records of type "book".

Now, when writing the records to a flat file, you can use the recordType "book" in the flat file definition to discriminate between different record types, for example

      <sx:flatRecordTypeChoice id="bookType">
        <sx:delimitedField name="xxx"/> <!-- unused, used for input only -->
        <sx:when test="/book"> <!-- matches against record type "book" -->
          <sx:flatRecordType name="book">
            <sx:fieldDelimiter value=","/>
            <sx:delimitedField name="title" quote="always"/>
            <sx:delimitedField name="author"/>
          </sx:flatRecordType>

Note that the recordType of the record becomes the root element of the XML representation of the record, so the test is written as "/book". Also note that the discrimination is based on the test expression, it's unrelated to the sx:flatRecordType attribute `name`, which could just as well be "ABook".

One restriction of referring to the recordType in the flat file definition like this is that this flat file definition can be used for XML -> flat only, for flat -> XML the discrimination has to be based on field values. But generally you'll want to use the same flat file definiton for flat->XML and XML->flat.

Using one flat file definition is always possible in simple cases with a single recordType, but in more complex cases using sx:flatRecordTypeChoice, it requires that flat->XML and XML->flat both discriminate by field values.

So suppose you have a flat file definition like

      <sx:flatRecordTypeChoice id="bookType">
        <sx:delimitedField name="tag"/> <!-- used for input only -->
        <sx:when test="tag = 'B'"> <!-- matches against field "tag" -->
        <sx:flatRecordType name="book">
        <sx:delimitedField name="tag"/>
        <!-- other fields -->

On input, the first field of the record will be read in, and generally speaking, as many fields will be read in as appear immediately below the sx:flatRecordTypeChoice. These fields may then be referred to in test expressions to determine the record type. Once the type is known, the complete record is read and assigned a recordType.

On output, the fields appearing immediately below the sx:flatRecordTypeChoice aren't used. Instead, the sx:when test expressions test against the record about to be written, and if that record has a field called tag with the value 'B',

    <sx:when test="tag = 'B'"

will evaluate as true.

So note the following:

- In the second line of

      <sx:flatRecordTypeChoice id="bookType">
      <sx:delimitedField name="tag"/> <!-- used for input only -->
      <sx:when test="tag = 'B'"> <!-- matches against field "tag" -->

  the field "tag" is used in flat->xml but not xml->flat, where it is ignored.

- In the second line of

      <sx:when test="tag = 'B'"> <!-- matches against field "tag" -->
      <sx:flatRecordType name="book">

  the name "book" becomes the recordType of the input record in flat->XML, but is ignored in XML->flat (the recordType is thrown away, it isn't written to the flat file.)

- In the third line of

      <sx:flatRecordTypeChoice id="bookType">
      <sx:delimitedField name="tag"/> <!-- used for input only -->
      <sx:when test="tag = 'B'"> <!-- matches against field "tag" -->

  the field tag appearing in the test expression is a field at the beginning of the input record in flat->XML, and it's a field of the output record in XML->flat.

## Examples

Example 68. Mapping master/detail content to composite records

Suppose you have a document of countries,

    <countries>
      <country countryCode="ATF">
        <countryName>FRENCH SOUTHERN TERRITORIES, D.R. OF</countryName>
      </country>
      <country countryCode="VUT">
        <countryName>VANUATU</countryName>
      </country>
      <country countryCode="WLF">
        <countryName>WALLIS &amp; FUTUNA ISLANDS</countryName>
      </country>
    </countries>

Now suppose you want to map each "country" subtree to a corresponding "country" record containing two fields, "name" and "code". For this you can use the sx:inverseRecordMapping instruction below.

      <sx:inverseRecordMapping id="countriesToFileMapping">
        <sx:onSubtree path="country">
          <sx:flattenSubtree  recordType="country">
            <sx:subtreeFieldMap select="countryName" field="name"/>
            <sx:subtreeFieldMap select="@countryCode" field="code"/>
          </sx:flattenSubtree>
        </sx:onSubtree>
      </sx:inverseRecordMapping>

Note that the sx:onSubtree element extracts the "country" subtrees. The sx:flattenSubtree element flattens the subtree into a record.

## See also

- sx:onSubtree
- sx:flattenSubtree
- sx:subtreeFieldMap

## Name

sx:onSubtree — On subtree event

└ sx:shredXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
path | Yes | SAXPath | A SAXPath expression.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:onSubtree and sx:flattenSubtree elements.

## See also

- sx:inverseRecordMapping
- sx:flattenSubtree
- sx:subtreeFieldMap

## Name

sx:shredXml — Abstract element standing for any element that maps XML to records

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

None

## Description

This is an abstract element that stands for any inverse record mapping element.

## Examples

## See also

- sx:subtreeFieldMap
- sx:flattenSubtree
- sx:onSubtree

## Name

sx:subtreeFieldMap — Map from subtree to field

└ sx:shredXml

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
match | No | XSLT pattern | Define a condition that an element in the XML fragment must satisfy in order to be selected by an XPath expression. Defaults to "/*"
select | No | XPath expression | Apply an XPath expression to the collection of elements in the XML fragment that satisfy the conditon of the `match` pattern. The expression is evaluated as a string. If the match pattern matches several elements, the XPath expression will be applied to each of them, evaluating to multiple field values.
field | Yes | QName | The name of an output field.

## Content

None.

## Examples

Example 69. Mapping master/detail content to composite records

Suppose you have a master/detail XML document

    <masterDetail>
      <master id="1">
        <name>aName</name>
        <detail id="11">
          <date>2008-09-03</date>
          <type>aType</type>
        </detail>
        <detail id="12">
          <date>2008-09-06</date>
          <type>aType</type>
        </detail>
        <detail id="13">
          <date>2008-09-10</date>
          <type>aType</type>
        </detail>
      </master>
      <master id="2">
        <name>anotherName</name>
        <detail id="21">
          <date>2008-10-03</date>
          <type>aType</type>
        </detail>
        <detail id="22">
          <date>2008-10-06</date>
          <type>aType</type>
        </detail>
        <detail id="23">
          <date>2008-10-07</date>
          <type>anotherType</type>
        </detail>
      </master>
    </masterDetail>

Suppose also that you want to map the two "master" subtrees to two composite records, each composed of a repeating group field named "details" that contains the "detail" subrecords. For this you can use the sx:inverseRecordMapping instruction below.

      <sx:inverseRecordMapping id="masterDetailMapping">
        <sx:onSubtree path="/masterDetail/master">
          <sx:flattenSubtree recordType="master">
            <sx:subtreeFieldMap select="@id" field="masterId"/>
            <sx:subtreeFieldMap select="name" field="name"/>
            <sx:subtreeFieldMap match="detail" field="details">
              <sx:flattenSubtree recordType="detail">
                <sx:subtreeFieldMap select="@id" field="detailId"/>
                <sx:subtreeFieldMap select="date" field="date"/>
                <sx:subtreeFieldMap select="type" field="type"/>
              </sx:flattenSubtree>
            </sx:subtreeFieldMap>
          </sx:flattenSubtree>
        </sx:onSubtree>
      </sx:inverseRecordMapping>

Note that the instruction <sx:subtreeFieldMap match="detail" field="details"> <sx:flattenSubtree recordType="detail"> <sx:subtreeFieldMap select="@id" field="detailId"/> <sx:subtreeFieldMap select="date" field="date"/> <sx:subtreeFieldMap select="type" field="type"/> </sx:flattenSubtree> </sx:subtreeFieldMap> matches each "detail" child in the "master" subtree and produces the repeating group field "details" containing the "detail" subrecords.

## See also

- sx:inverseRecordMapping
- sx:onSubtree
- sx:flattenSubtree

## Name

sx:subtreeRecordMap — Deprecated, aliased to sx:flattenSubtree

└ sx:shredXml

# Flat File Elements

## Name

Flat File Options - Attributes — Flat file options

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
flushRecordOnWrite | No | true|false | Indicates whether to flush the output stream every time a record is written. Defaults to `false`.
trim | No | true|false | Indicates whether to trim leading and trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
trimLeading | No | true|false | Indicates whether to trim leading whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
trimWithinQuotes | No | true|false | Indicates whether to trim quoted values of leading and trailing whitespace. Defaults to `false`.
trimLeadingWithinQuotes | No | true|false | Indicates whether to trim quoted values of leading whitespace. Defaults to `false` .
trimTrailingWithinQuotes | No | true|false | Indicates whether to trim quoted values of trailing whitespace. Defaults to `false`.
trimQuoted | No | true|false | Deprecated as of version 1.1.0, use `trimWithinQuotes` instead.
trimTrailing | No | true|false | Indicates whether to trim trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
quote | No | "auto" or "always" or "never" | Indicates whether a value should be searched for a field delimiter, and if so enclosed in quote marks, or whether a value should always be enclosed in quote marks. The default is `never` for positional files, `auto` for delimited or mixed files. Previous versions supported yes/no values, which have been deprecated, but are translated to "auto" and "never" respectively.
omitFinalFieldDelimiter | No | true|false | Defaults to `true`. (For backwards compatability, "yes"/"no" is also supported.)
omitFinalRepeatDelimiter | No | true|false | Defaults to `true` (For backwards compatability, "yes"/"no" is also supported.)
padCharacter | No | Character | The pad character used for formatting values into a field of fixed width, e.g., a space or zero.
justify | No | "left","right", or "center" | Indicates how to align the data within the field.
lineDelimited | No | true|false | If set to `true`, records are expected to end with end-of-line delimiters, otherwise fixed width records are assumed. Defaults to `true`. (For backwards compatability, "yes"/"no" is also supported.)
countPositionsInBytes | No | true|false | If set to `true`, positions between fields are counted in bytes, otherwise positons are counted in characters. Defaults to `true` if any field is a binary field or if flat file signatures are specified, otherwise defaults to `false`.
ignoreTrailingEmptyLines | No | true|false | If set to `true`, lines at the end of files that are empty (apart from space, tab and record delimiter characters) are ignored. Defaults to `true`. (For backwards compatability, "yes"/"no" is also supported.)
ignoreEmptyLines | No | true|false | If set to `true`, all lines in the files that are empty (apart from space, tab and record delimiter characters) are ignored. Defaults to `false`. (For backwards compatability, "yes"/"no" is also supported.)

## Name

Flat File Options - Elements — Flat File Options

## Content

- Any number of sx:recordDelimiter elements.

- Any number of sx:segmentDelimiter elements.

- Any number of sx:repeatDelimiter elements.

- Any number of sx:fieldDelimiter elements.

- Any number of sx:subfieldDelimiter elements.

- Any number of sx:nameDelimiter elements.

- A sx:quoteSymbol element.

- Zero or many sx:commentStarter elements.

## Name

sx:annotationRecord — Annotation record

└ sx:metaRecord

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | No | QName | The name of the annotation record.
width | Yes | number | The width of the annotation record.
justify | No | "left","right", or "center" | Indicates how to align the data within the field. The default is "left".

## Content

An input string.

## Description

## Name

sx:binaryField — Binary field

└ sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | Yes | QName | The name of the field.
label | No | SubstitutionExpr | A label for the field.
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
width | Yes | SubstitutionExpr | The width of the field.

## Content

- Optionally, a sx:defaultValue element, defaults to the empty string (for writing if there are missing field values.)

## See also

- sx:recordMapping

## Examples

Example 70. First field of each record has a special character.

In the example below, the first two records in the file start with the hexadecimal values 03 and 04. These values are needed to differentiate the record type, but these valued cannot be written as &#x03; and &#x04; in XML, as these are not valid XML characters.

      <sx:flatFile id="transactionFile">
        <sx:flatFileBody>
          <sx:flatRecordTypeChoice>
            <sx:binaryField name="firstField" width="1"/>
            <sx:when test="firstField='03'">
              <sx:flatRecordType id="R03" name="R03">
                <sx:binaryField name="firstField" label="firstField" width="1" />
                <sx:positionalField name="CLIENUM" label="CLIENUM" width="007" />
              </sx:flatRecordType>
            </sx:when>
            <sx:when test="firstField='04'">
              <sx:flatRecordType id="R04" name="R04">
                <sx:binaryField name="firstField" label="firstField" width="1" />
                <sx:positionalField name="NAME" label="NAME" width="020" />
              </sx:flatRecordType>
            </sx:when>
          </sx:flatRecordTypeChoice>
        </sx:flatFileBody>
      </sx:flatFile>

## Name

sx:commentStarter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
value | Yes | String | The value of a comment symbol.

## Content

None.

## Name

sx:commentSymbol — Deprecated, aliased to sx:commentStarter

## Name

sx:compositeFlatRecordType — Composite flat record type

└ sx:metaRecord

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent

## Content

- Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements

- One or more specializations of the abstract sx:flatRecordField element, including sx:positionalField, sx:binaryField, sx:integerField and sx:delimitedField. If positional and delimited fields are mixed, the positional fields should precede the delimited fields.

- One sx:recordComposition element.

## See also

- sx:flatFile
- sx:onRecord
- sx:fieldAttributeMap
- sx:fieldElementMap

## Name

sx:crcFlatFileSignature — Deprecated, replaced by sx:flatFileSignature with method="crc"

## Name

sx:delimitedField — Delimited field

└ sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | Yes | QName | The name of the field.
label | No | SubstitutionExpr | A label for the field.
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
trim | No | true|false | Indicates whether to trim leading and trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
trimLeading | No | true|false | Indicates whether to trim leading whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
trimTrailing | No | true|false | Indicates whether to trim trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
trimWithinQuotes | No | true|false | Indicates whether to trim quoted values of leading and trailing whitespace. Defaults to the setting at the record level.
trimLeadingWithinQuotes | No | true|false | Indicates whether to trim quoted values of leading whitespace. Defaults to the setting at the record level.
trimTrailingWithinQuotes | No | true|false | Indicates whether to trim quoted values of trailing whitespace. Defaults to the setting at the record level.
quote | No | "auto" or "always" or "never" | Indicates whether a value should be searched for a field delimiter, and if so enclosed in quote marks, or whether a value should always be enclosed in quote marks. The default is `auto`. Previous versions supported yes/no values, which have been deprecated, but are translated to "auto" and "never" respectively.
alwaysQuote | No | "yes" or "no" | Deprecated as of version 0.6.3, use quote="always" instead.
minLength | No | number | If the length of the field value is less than `minLength`, it will be padded with the `padCharacter`.
maxLength | No | number | If the length of the field is greater than `maxValue`, it will be truncated.
justify | No | "left","right", or "center" | The alignment rule used for formatting values into a field of fixed width. The default is "left".
padCharacter | No | Character | The pad character used for formatting values into a field of fixed width, e.g., a space or zero. The default is a space.
maxWidth | No | number | The maximum field width, including delimiter. If the number of characters read exceeds the specified `width`, that will be regarded as the end of this field and the beginning of the next. Defaults to the record width.
width | No | number | Deprecated, use `maxWidth` instead.
omitFinalFieldDelimiter | No | true|false | Defaults to `true` (For backwards compatability, "yes"/"no" is also supported.)

## Content

- Optionally, any number of sx:fieldDelimiter and sx:subfieldDelimiter elements. If not specified, defaults to the field and subfield delimiters in scope, if any.element.

- Optionally, a sx:quoteSymbol element. If not specified, defaults to the quote symbol in scope, if none, defaults to `"`.

- Optionally, a sx:defaultValue element, defaults to the empty string (for writing if there are missing field values.)

## See also

- sx:recordMapping

## Notes

- If you have a field value that includes a character that is the same as the quote symbol, you must escape that character. For example, if the quote symbol is the default double quotation mark, escaped by a second quote symbol, and if your record data is

      "Gun, with Occaisonal Music","""SHARP, FUNNY, VISIONARY"""

  then the values become

      Gun, with Occaisonal Music
      "SHARP, FUNNY, VISIONARY"

## Name

sx:delimitedNamedField — Delimited name/value pair

└ sx:flatRecordField, sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
label | No | SubstitutionExpr | A label for the field.
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
trim | No | true|false | Indicates whether to trim leading and trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
trimLeading | No | true|false | Indicates whether to trim leading whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
trimTrailing | No | true|false | Indicates whether to trim trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
minLength | No | number | If the length of the field value is less than `minLength`, it will be padded with the `padCharacter`.
maxLength | No | number | If the length of the field is greater than `maxValue`, it will be truncated.
justify | No | "left","right", or "center" | The alignment rule used for formatting values into a field of fixed width. The default is "left".
padCharacter | No | Character | The pad character used for formatting values into a field of fixed width, e.g., a space or zero. The default is a space.
maxWidth | No | number | The maximum field width, including delimiter. If the number of characters read exceeds the specified `width`, that will be regarded as the end of this field and the beginning of the next. Defaults to the record width.
omitFinalFieldDelimiter | No | true|false | Defaults to `true` (For backwards compatability, "yes"/"no" is also supported.)

## Content

- Optionally, any number of sx:fieldDelimiter and sx:subfieldDelimiter elements. If not specified, defaults to the field and subfield delimiters in scope, if any.

- Optionally, a sx:quoteSymbol element. If not specified, defaults to the quote symbol in scope, if none, defaults to `"`.

- Optionally, a sx:defaultValue element, defaults to the empty string (for writing if there are missing field values.)

- Optionally, a sx:nameDelimiter element. If not specified, defaults to the tag delimiter in scope. If there is no tag delimiter, an error is raised.

## See also

- sx:repeatingField

## Notes

- If you have a field value that includes a character that is the same as the quote symbol, you must escape that character. For example, if the quote symbol is the default double quotation mark, escaped by a second quote symbol, and if your record data is

      "Gun, with Occaisonal Music","""SHARP, FUNNY, VISIONARY"""

  then the values become

      Gun, with Occaisonal Music
      "SHARP, FUNNY, VISIONARY"

## Name

sx:fieldDelimiter — Field delimiter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
value | No | SubstitutionExpr | A string of one or more characters that indicates the end of a field.
escapeCharacter | No | Character | An escape character used to escape the delimiter.

## Content

Optionally, a sx:separator element.

## Description

The field delimiter indicates the end of the field value. It is excluded from the field value. It may be one or more characters in length.

The following special encodings may appear in a delimiter value.

- \t, to indicate a tab.
- \r, to indicate a carriage return.
- \n, to indicate a line feed.

You can also use numerical entity references to specify delimiter values, e.g. &#x09; is another way of specifying a tab character.

The value of the delimiter may be specified either by a `value` attribute or by the sx:separator content.

## Notes

- If you have a field value that includes a character that is the same as the delimiter, you must define the field to have quoted field values and enclose the value of the field in quotes.

## Name

sx:flatFile — Flat file

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent

## Content

- Optionally, any number of flat file option elements, for example, any number of sx:recordDelimiter elements, or any number of sx:commentStarter elements.

- Optionally, a sx:flatFileTrailer element.

- A sx:flatFileBody element.

- Optionally, any number of sx:flatFileSignature elements.

## Description

By default there are two record delimiters: a linefeed, or a carriage return followed by a linefeed. When serializing XML to a flat file, if more than one record delimiter has been defined, the serializer checks to see if one of the delimiters matches the system conventional end-of-line character. If so, it uses that one, otherwise it uses the first one.

## Examples

See sx:flatFileReader

## See also

- sx:flatFileReader

- sx:flatFileWriter

## Name

sx:flatFileBody — Flat file body

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent

## Content

A sx:flatRecordType element, or a sx:flatRecordTypeChoice element.

## See also

### Examples

Example 71. Using a sx:flatFileBody element.

      <sx:flatFile id="tradesFlatFile">
        <sx:commentStarter value="#"/>
        <sx:flatFileBody>
          <sx:flatRecordTypeChoice>
            <sx:positionalField name="record_type" width="2"/>
            <sx:when test="record_type='TR'">
              <sx:flatRecordType name="trade">
                <sx:positionalField name="record_type" width="2"/>
                <sx:positionalField name="id" width="4"/>
                <sx:positionalField name="trade_date" width="10"/>
                <sx:positionalField name="trade_time" width="8"/>
                <sx:positionalField name="description" width="30"/>
              </sx:flatRecordType>
            </sx:when>
            <sx:when test="record_type='TN'">
              <sx:flatRecordType name="transaction">
                <sx:positionalField name="record_type" width="2"/>
                <sx:positionalField name="id" width="4"/>
                <sx:positionalField name="reference" width="5"/>
                <sx:positionalField name="description" width="30"/>
              </sx:flatRecordType>
            </sx:when>
          </sx:flatRecordTypeChoice>
        </sx:flatFileBody>
      </sx:flatFile>

      <sx:recordMapping id="tradesToXmlMapping">
        <trades>
          <sx:onRecord recordType="trade">
            <trade>
              <sx:fieldAttributeMap field="id" attribute="id"/>
              <sx:fieldElementMap field="description" element="description"/>
            </trade>
          </sx:onRecord>
          <sx:onRecord recordType="transaction">
            <transaction>
              <sx:fieldAttributeMap field="id" attribute="id"/>
              <sx:fieldElementMap field="reference" element="reference"/>
              <sx:fieldElementMap field="description" element="description"/>
            </transaction>
          </sx:onRecord>
        </trades>
      </sx:recordMapping>

- sx:flatFile

- sx:onRecord

- sx:fieldAttributeMap

- sx:fieldElementMap

## Name

sx:flatFileSignature — Flat file signature

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | Yes | QName | Identifies a header or trailer record.
field | Yes | QName | Identifies a field in a header or trailer record.
method | Yes | string | Must be one of "crc", "size, or "custom".
class | No (unless method is "custom") | Java class name | The name of a Java class that implements com.servingxml.components.flatfile.SignatureMethod
validate | No | true|false | Indicates whether, when reading a file, the computed signature should be validated against the value stored in the header or trailer. Defaults to `true`. (For backwards compatability, "yes"/"no" is also supported.)

## Content

None.

## Description

Computes the size, CRC, or custom signature of the raw data from the body of the flat file (excluding header and trailer.) When the file is being written, the signature is stored in the header or trailer field identified by record type and field name. When the file is being read, the computed signature is compared to the signature from the header or trailer field, and an error is raised if they differ.

## Examples

See sx:flatFileHeader and sx:flatFileTrailer

## See also

- sx:flatFile

- sx:flatFileHeader

- sx:flatFileTrailer

## Name

sx:flatFileHeader — Flat file header

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
lineCount | No | Number | The number of lines in the header.
recordLength | No | Integer | The total length of the header records, including record delimiter, if any.

## Content

- One or more sx:metaRecord elements.

## Examples

Example 72. A flat file header which contains title headings for columns.

The header declaration below will prepend a two line header to a flat file:

- A list of title headings for columns.

- A blank line before the data section.

      <sx:flatFile id="booksFile">
        <sx:flatFileHeader>
          <sx:flatRecordType ref="bookType"/>
          <sx:annotationRecord/>
        </sx:flatFileHeader>
        <sx:flatFileBody>
          <sx:flatRecordType ref="bookType"/>
        </sx:flatFileBody>
      </sx:flatFile>

      <sx:flatRecordType id="bookType" name="bookType">
        <sx:positionalField name="category" label="Category" width="1"/>
        <sx:positionalField name="author" label="Author" width="30"/>
        <sx:positionalField name="title" label="Title" width="30"/>
        <sx:positionalField name="price" label="Price" width="10" justify="right"/>
      </sx:flatRecordType>

Note the following:

- In header and trailer sections, the `label` attributes of fields are treated as data values.

## See also

- sx:flatFileSignature

## Name

sx:flatFileReader — Read flat file

└ sx:recordReader

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent

## Content

- Optionally, any number of sx:parameter elements.

- Optionally, any number of flat file option elements, for example, any number of sx:recordDelimiter elements, or any number of sx:commentStarter elements.

- Optionally, a sx:streamSource element.

- Optionally, a sx:flatFile element. Defaults to a file reader that examines the first row of the file for delimited column headings.

## Examples

Example 73. Example of a flat file record reader.

      <sx:flatFileReader id="countries">
        <sx:urlSource url="books/countries.csv"/>

        <sx:flatFile>
          <sx:flatFileBody>
            <sx:flatRecordType name="country">
              <sx:fieldDelimiter value=","/>
              <sx:delimitedField name="countryCode"/>
              <sx:delimitedField name="countryName"/>
            </sx:flatRecordType>
          </sx:flatFileBody>
        </sx:flatFile>

      </sx:flatFileReader>

## See also

- sx:recordContent

## Name

sx:flatRecordField — Abstract element standing for any flat record field

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference an id.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:flatRecordField`, such as sx:delimitedField.

## Examples

## See also

- sx:flatRecordType
- sx:delimitedField
- sx:positionalField
- sx:binaryField
- sx:integerField
- sx:repeatingGroup
- sx:repeatingField

## Name

sx:flatRecordType — Flat record type

└ sx:metaRecord, sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent
name | No | SubstitutionExpr | A QName, or an expression that evaluates to a QName. Defaults to "record"
recordLength | No | SubstitutionExpr | The total length of the record, including record delimiter, if any.

## Content

- Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements

- One or more specializations of the abstract sx:flatRecordField element, including sx:delimitedField, sx:positionalField, sx:repeatingGroup, and sx:flatRecordType elements. If positional and delimited fields are mixed, the positional fields should precede the delimited fields. Note that you can extend other flat record types by referring to the base sx:flatRecordType elements in the content.

## Examples

Example 74. The "country" record.

    <sx:flatRecordType id="countryRec" name="country">
      <sx:fieldDelimiter value=","/>
      <sx:delimitedField name="code"/>
      <sx:delimitedField name="name"/>
    </sx:flatRecordType>

Example 75. Extending the "country" record with a "message" field.

      <sx:flatRecordType name="countryDiscard">
        <sx:fieldDelimiter value=","/>
        <sx:delimitedField name="message"/>
        <sx:flatRecordType ref="countryRec"/>
      </sx:flatRecordType>

The reference to the "country" record above is expanded into the fields of the "country" record.

## See also

- sx:flatFile
- sx:onRecord
- sx:fieldAttributeMap
- sx:fieldElementMap

## Name

sx:flatRecordTypeChoice — Choose from alternative record definitions

└ sx:metaRecord

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent

## Content

- Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements

- One or more specializations of the abstract sx:flatRecordField element, including sx:positionalField, sx:binaryField, sx:integerField and sx:delimitedField. If positional and delimited fields are mixed, the positional fields should precede the delimited fields.

- One or more `sx:when` elements, optionally followed by one `sx:otherwise` element. The `sx:when` elements must have a `test` attribute, an XPath expression that is evaluated against a document containing the above fields. The `sx:when` and `sx:otherwise` elements must contain one sx:flatRecordType or sx:flatRecordTypeChoice child element.

## See also

- sx:flatFile
- sx:onRecord
- sx:fieldAttributeMap
- sx:fieldElementMap

## Name

sx:flatFileTrailer — Flat file trailer

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
lineCount | No | Number | The number of lines in the trailer.
recordLength | No | Integer | The total length of the header records, including record delimiter, if any.

## Content

- One or more sx:metaRecord elements.

## Examples

Example 76. A flat file trailer which contains a record count.

The trailer declaration below will append a two line trailer to a flat file:

- A blank line, followed by

- Number of records: <recordCount>

      <sx:flatFileTrailer>
        <sx:annotationRecord></sx:annotationRecord>
        <sx:flatRecordType ref="trailer"/>
      </sx:flatFileTrailer>

      <sx:flatRecordType id="trailer" name="trailer">
        <sx:positionalField name="recordCountLabel" width="19" label="Number of records: "/>
        <sx:positionalField name="recordCount"  width="10" label="{$sx:recordCount}"/>
      </sx:flatRecordType>

Note the following:

- In header and trailer sections, the `label` attributes of fields are treated as data values.

- In a `sx:positionalField` element, the value of the `label` attribute can contain references to parameters, in particular to `$sx:recordCount`, which is a parameter that the file record writer adds after finishing writing records.

Example 77. A flat file trailer which contains size and CRC file signatures.

The flat file declaration below will append a trailer to a flat file that contains the size in bytes of the flat file body, followed by the CRC value calculated for the flat file body.

      <sx:flatFile id="sampleFlatFile">
        <sx:flatFileBody>
          ...
        </sx:flatFileBody>

        <sx:flatFileSignature recordType="fileSignatures" field="filecrc" method="crc"/>
        <sx:flatFileSignature recordType="fileSignatures" field="filesize" method="size"/>
        <sx:flatFileTrailer>
          <sx:flatRecordType ref="sampleTrailerRecord"/>
        </sx:flatFileTrailer>
      </sx:flatFile>

      <sx:flatRecordType id="sampleTrailerRecord" name="fileSignatures">
        <sx:fieldDelimiter value="|"/>
        <sx:delimitedField name="filesize"/>
        <sx:delimitedField name="filecrc"/>
      </sx:flatRecordType>

Note the following:

- The `sx:flatFile` element contains two `sx:flatFileSignature` elements, which define the rules for checking the CRC and size when reading the file, and signing the header or trailer with a CRC and size when writing the file.

- The `sx:flatFileSignature` element has attributes `recordType` and `field`, which identify where in the header or trailer the signature value belongs.

## See also

- sx:flatFileSignature

## Name

sx:flatFileWriter — Abstract element standing for any flat file writer

└ sx:recordWriter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent

## Content

- Optionally, any number of sx:parameter elements.
- Optionally, a sx:streamSink element.
- Optionally, a sx:flatFile element. If omitted, the file structure defaults to a CSV file format with labels and values reflecting the names and values in the records.

## Examples

Example 78. Example of a flat file record writer.

## See also

- sx:recordWriter

## Name

sx:integerField — Integer field

└ sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | Yes | QName | The name of the field.
label | No | SubstitutionExpr | A label for the field.
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
width | Yes | number | The width of the field, which must be 1, 2, 4, or 8.
bigEndian | No | true|false | Specifies the byte order, defaults to `true`.

## Content

- Optionally, a sx:defaultValue element, defaults to the empty string (for writing if there are missing field values.)

## Description

This element supports reading and writing of integer values encoded as BIG ENDIAN or LITTLE ENDIAN.

## See also

- sx:recordMapping

## Name

sx:metaRecord — Meta record

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference an id.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:metaRecord`, such as sx:flatRecordType.

## See also

- sx:flatRecordType
- sx:annotationRecord

## Name

sx:nameDelimiter — Separate a field name and value

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
value | No | SubstitutionExpr | The character(s) used to separate name/value pairs.

## Content

Optionally, a sx:separator element.

## Description

Value of the character(s) used to separate name/value pairs.

The following special encodings may appear in a delimiter value.

- \t, to indicate a tab.
- \r, to indicate a carriage return.
- \n, to indicate a line feed.

You can also use numerical entity references to specify delimiter values, e.g. &#x09; is another way of specifying a tab character.

The value of the delimiter may be specified either by a `value` attribute or by the sx:separator content.

## Name

sx:packedDecimalField — Packed decimal field

└ sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | Yes | QName | The name of the field.
label | No | SubstitutionExpr | A label for the field.
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
width | No | number | The width of the field. Defaults to the width corresponding to the digitCount.
digitCount | No | number | The total number of digits in the packed decimal number.
decimalPlaces | No | number | The number of places to the right of the implied decimal. Defaults to `0`.

## Content

- Optionally, a sx:defaultValue element, defaults to the empty string (for writing if there are missing field values.)

## See also

- sx:recordMapping

## Name

sx:nonrepeatingGroup — A nonrepeating group is a field that contains at most one group of subfields within a segment (an area of a record terminated with a segment delimiter.)

└ sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent
name | Yes | QName | The name of the nonrepeating group field.
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.

## Content

- Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements

- A sx:flatRecordType element, or a sx:flatRecordTypeChoice element.

## Description

The sx:segmentDelimiter, if not supplied, defaults to the end of the record.

A nonrepeating group reads at most one record

## See also

- sx:repeatingGroup

## Name

sx:overpunchField — Overpunch field

└ sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | Yes | QName | The name of the field.
label | No | SubstitutionExpr | A label for the field.
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
width | Yes | SubstitutionExpr | The width of the field.

## Content

- Optionally, a sx:defaultValue element, defaults to the empty string (for writing if there are missing field values.)

## See also

- sx:recordMapping

## Examples

Example 79. Overpunch field.

      <sx:flatRecordType>
        <sx:overpunchField name="field1" width="4"/>
      </sx:flatRecordType>

## Name

sx:positionalField — Positional field

└ sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
name | Yes | QName | The name of the field.
label | No | SubstitutionExpr | A label for the field.
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
width | Yes | SubstitutionExpr | The width of the field.
trim | No | true|false | Indicates whether to trim leading and trailing whitespace. The default is `true`
trimLeading | No | true|false | Indicates whether to trim leading whitespace. The default is `true`
trimTrailing | No | true|false | Indicates whether to trim trailing whitespace. The default is `true`
justify | No | "left","right", or "center" | The alignment rule used for formatting values into a field of fixed width. The default is "left".
padCharacter | No | Character | The pad character used for formatting values into a field of fixed width, e.g., a space or zero. The default is a space.

## Content

- Optionally, a sx:defaultValue element, defaults to the empty string (for writing if there are missing field values.)

## See also

- sx:recordMapping

## Examples

Example 80. Positional field using start attribute.

In the example below, positions one through two are assigned to `short-record-type`, and positions one through five are assigned to `record-type`. The `value` field starts at position six.

       <sx:flatRecordType name="hot">
         <sx:positionalField name="short-record-type"  width="2"/>
         <sx:positionalField name="record-type" start="1" width="5"/>
         <sx:positionalField name="value" width="7"/>
       </sx:flatRecordType>

Example 81. Variable length positional field.

In the example below, the input file contains a variable length field called "remarksText". The field width is specified using the value of its preceding field, called "remarksSize".

      <sx:flatRecordType name="transaction">
        <sx:positionalField name="remarksSize" width="4"/>
        <sx:positionalField name="remarksText" width="{remarksSize}"/>
      </sx:flatRecordType>

## Name

sx:recordComposition — Compose individual physical records into a composite logical record

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to `true`
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to `startTest`.
suppressRDW | No | true|false | Suppress the 4-byte record descriptor word (RDW) from the front of the logical record, defaults to `false`.

## Content

- Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements

- One sx:metaRecord element.

## See also

- sx:compositeFlatRecordType

## Name

sx:recordDelimiter — Separate records

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
start | No | SubstitutionExpr | A string of one or more characters that identifies the beginning of a record. If omitted, the record begins past the end of the previous record, or the beginning of the file.
end | No | SubstitutionExpr | A string of one or more characters that identifies the end of a record.
value | No | SubstitutionExpr | Same as `end`.
continuation | No | SubstitutionExpr | A string of one or more characters that indicates a continuation character, which allows a record to be extended onto the next line.
continuationSequence | No | SubstitutionExpr | The continuation + delimiter.
escapeCharacter | No | Character | An escape character used to escape the delimiter.

## Content

Optionally, a sx:separator element.

## Description

The record delimiter indicates the end of the record.

The following special encodings may appear in a record delimiter or continuation value.

- \t, to indicate a tab.
- \r, to indicate a carriage return.
- \n, to indicate a line feed.

You can also use numerical entity references to specify delimiter values, e.g. &#x0A; is another way of specifying a line feed character.

The value of the delimiter may be specified either by a `value` attribute or by the sx:separator content.

## Name

sx:repeatDelimiter — Separate repeating groups within a segment

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
start | No | SubstitutionExpr | A string of one or more characters that identifies the beginning of a segment separated by start-end delimiters.
end | No | SubstitutionExpr | A string of one or more characters that identifies the end of a segment separated by start-end delimiters.
value | No | SubstitutionExpr | A string of one or more characters that indicates the end of a segment within a repeating group.
escapeCharacter | No | Character | An escape character used to escape the delimiter.

## Content

Optionally, a sx:separator element.

## Description

The repeat delimiter separates segments within a repeating group. It may be one or more characters in length.

The following special encodings may appear in a delimiter value.

- \t, to indicate a tab.
- \r, to indicate a carriage return.
- \n, to indicate a line feed.

You can also use numerical entity references to specify delimiter values, e.g. &#x09; is another way of specifying a tab character.

The value of the delimiter may be specified either by a `value` attribute or by the sx:separator content.

## Notes

- If you have a value that includes a character that is the same as the delimiter, the value must be enclosed in quotes.

## Name

sx:repeatingField — Field repeats

└ sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent
count | No | SubstitutionExpr | A fixed number of repeating tagged fields.

## Content

- Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements

- Optionally, a sx:defaultValue element, defaults to the empty string (for writing if there are missing field values.)

- One sx:flatRecordField element.

## See also

- sx:recordMapping

## Notes

- If you have a field value that includes a character that is the same as the quote symbol, you must escape that character. For example, if the quote symbol is the default double quotation mark, escaped by a second quote symbol, and if your record data is

      "Gun, with Occaisonal Music","""SHARP, FUNNY, VISIONARY"""

  then the values become

      Gun, with Occaisonal Music
      "SHARP, FUNNY, VISIONARY"

## Name

sx:repeatingNamedField — Deprecated, replaced by sx:repeatingField

## Name

sx:repeatingGroup — A repeating group is a field that contains zero or more groups of subfields within a segment (an area of a record terminated with a segment delimiter.) The groups may be separated by sx:repeatDelimiters, or may be of fixed length.

└ sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent
name | Yes | QName | The name of the repeating group field.
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
count | No | SubstitutionExpr | A fixed number of repeating records.

## Content

- Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements

- A sx:flatRecordType element, or a sx:flatRecordTypeChoice element.

## Description

If an sx:repeatDelimiter is supplied in the content, or is inherited from an ancestor element of the record type, each member of the repeating group is assumed to be separated by the repeat delimiter, and terminated either by the sx:segmentDelimiter, or earlier by the value of the `count` attribute (if supplied.) The sx:segmentDelimiter, if not supplied, defaults to the end of the record.

If an sx:repeatDelimiter is neither supplied in the content nor inherited from an ancestor element, each member of the repeating group is assumed to follow sequentially, and is read according, up to the value of the `count` attribute.

The difference between a repeating group and a repeating segment is that only a specific composite of fields is repeated, not an entire segment.

## See also

- sx:repeatingField

## Name

sx:repeatingSegment — Deprecated, superceded by sx:repeatingGroup

└ sx:flatRecordField

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent
name | Yes | QName | The name of the repeating segment field.
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
count | No | SubstitutionExpr | A fixed number of repeating segments.

## Content

- Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements

- A sx:flatRecordType element, or a sx:flatRecordTypeChoice element.

## Description

Each member of the repeating segment is assumed to be separated by a sx:segmentDelimiter. The segment delimiter may be a simple terminating value, e.g. "\r", or alternatively the segment delimiter may be a start-end pair, e.g. "{"-"}". If the latter, the repeating segments will be the content of the start-end pairs at the same level (including nested start-end pairs.)

The repeating segment is terminated either by the value of the `count` attribute (if supplied), or by the end of an enclosing segment, or the end of the record.

## See also

- sx:repeatingGroup
- sx:repeatingField

## Name

sx:segmentConcatenation — Concatenate a number of physical records as segments of one logical record.

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to `true`
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to `startTest`.
suppressRDW | No | true|false | Suppress the 4-byte record descriptor word (RDW) from the front of the logical record, defaults to `false`.

## Content

- Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements

- One sx:metaRecord element.

## See also

- sx:vbsFlatRecordType

## Name

sx:segmentDelimiter — Separate a record into segments containing repeating groups

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
start | No | SubstitutionExpr | A string of one or more characters that identifies the beginning of a segment separated by start-end delimiters.
end | No | SubstitutionExpr | A string of one or more characters that identifies the end of a segment separated by start-end delimiters.
value | No | SubstitutionExpr | A string of one or more characters that indicates the end of a segment.
escapeCharacter | No | Character | An escape character used to escape the delimiter.

## Content

Optionally, a sx:separator element.

## Description

The segment delimiter indicates the end of a repeating group of segments within a record. It may be one or more characters in length.

The following special encodings may appear in a delimiter value.

- \t, to indicate a tab.
- \r, to indicate a carriage return.
- \n, to indicate a line feed.

You can also use numerical entity references to specify delimiter values, e.g. &#x09; is another way of specifying a tab character.

The value of the delimiter may be specified either by a `value` attribute or by the sx:separator content.

## Notes

- If you have a value that includes a character that is the same as the delimiter, the value must be enclosed in quotes.

## Name

sx:separator — Abstract element standing for any separator

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | No | QName | This attribute is used to reference an id.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:separator`, such as sx:whitespaceSeparator.

## See also

- sx:whitespaceSeparator

## Name

sx:sizeFlatFileSignature — Deprecated, replaced by sx:flatFileSignature with method="size"

## Name

sx:subfieldDelimiter — Separate values within a field

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
value | No | SubstitutionExpr | A string of one or more characters that indicates the end of a value in a multivalued field.
escapeCharacter | No | Character | An escape character used to escape the delimiter.

## Content

Optionally, a sx:separator element.

## Description

The subfield delimiter indicates the end of a value in a multivalued delimiter separated field.

The following special encodings may appear in a delimiter value.

- \t, to indicate a tab.
- \r, to indicate a carriage return.
- \n, to indicate a line feed.

You can also use numerical entity references to specify delimiter values, e.g. &#x09; is another way of specifying a tab character.

The value of the delimiter may be specified either by a `value` attribute or by the sx:separator content.

## Name

sx:tagDelimiter — Deprecated, aliased to sx:nameDelimiter

## Name

sx:taggedDelimitedField — Deprecated, aliased to sx:delimitedNamedField

## Name

sx:taggedFlatRecordField — Deprecated, aliased to sx:flatRecordField

## Name

sx:vbsFlatRecordType — Variable Block Segment (VBS) record type

└ sx:metaRecord

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
flat file option attributes | No |  | Standard flat file options, may be overriden in a descendent

## Content

- Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements

- One or more specializations of the abstract sx:flatRecordField element, including sx:positionalField, sx:binaryField, sx:integerField and sx:delimitedField. If positional and delimited fields are mixed, the positional fields should precede the delimited fields.

- One sx:segmentConcatenation element.

## See also

- sx:flatFile
- sx:onRecord
- sx:fieldAttributeMap
- sx:fieldElementMap

## Name

sx:whitespaceSeparator — Separate fields with whitespace

└ sx:separator

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

None.

## Description

The whitespace separator permits fields or records to be separated by one or more whitespace characters.

## See also

- sx:recordDelimiter
- sx:fieldDelimiter
- sx:subfieldDelimiter

# SQL Elements

## Name

sx:customJdbcConnectionPool — Custom JDBC connection pool

└ sx:jdbcConnectionPool

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
class | Yes | Java class | The name of a Java class that implements `com.servingxml.components.sql.JdbcConnectionPool`.

## Content

- Optionally, any number of sx:property elements.

## Description

This element allows you to configure a custom JDBC connection pool by providing an implementation of the interface

    public interface JdbcConnectionPool {

      Connection getConnection() throws SQLException;

      void releaseConnection(Connection connection);
    }

The implementation should have a constructor that takes one argument, a `java.util.Properties` instance. There you will find the custom properties you specified with the sx:property elements.

## Example

Example 82. Example of a custom JDBC connection pool.

Figure 2. Resources script entry

      <sx:customJdbcConnectionPool id="custom-jdbc-pool" class="MyJdbcConnectionPool">
        <sx:property name="driver" value="oracle.jdbc.driver.OracleDriver"/>
        <sx:property name="databaseUrl" value="jdbc:oracle:thin:@127.0.0.1:1521:dev"/>
        <sx:property name="user" value="scott"/>
        <sx:property name="password" value="spring"/>
      </sx:customJdbcConnectionPool>

Figure 3. Simple JdbcConnectionPool implementation

    public class MyJdbcConnectionPool implements JdbcConnectionPool {

      private final String driver;
      private final String databaseUrl;
      private final String user;
      private final String password;

      public MyJdbcConnectionPool(Properties properties)
       {
        this.driver = properties.getProperty("driver");
        this.databaseUrl = properties.getProperty("databaseUrl");
        this.user = properties.getProperty("user");
        this.password = properties.getProperty("password");

        if (driver == null) {
          throw new ServingXmlException("driver required");
        }

        try {
          Class.forName(driver);
        } catch (java.lang.ClassNotFoundException e) {
          throw new ServingXmlException("Failed to load jdbc driver class.  " + e.getMessage());
        }

        if (databaseUrl == null) {
          throw new ServingXmlException("databaseUrl required");
        }
        if (user == null) {
          throw new ServingXmlException("user required");
        }
        if (password == null) {
          throw new ServingXmlException("password required");
        }
      }

      public Connection getConnection() throws SQLException {
        Connection connection = DriverManager.getConnection(databaseUrl, user, password);
        return connection;
      }

      public void releaseConnection(Connection connection) {
        try {
          connection.close();
        } catch(Exception e) {
        }
      }
    }

## Name

sx:jdbcConnectionPool — Abstract element standing for a JDBC connection pool

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference the id of a JDBC connection pool.

## Content

None.

## Description

This is an abstract element that allows us to refer generically to any specialization of `sx:jdbcConnectionPool`, such as sx:sqlConnectionPool.

## Examples

## See also

- sx:sqlConnectionPool
- sx:customJdbcConnectionPool

## Name

sx:sqlBatchWriter — SQL batch writer

└ sx:recordWriter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
batchSize | No | QName | The batch size. Defaults to 100.

## Content

- Optionally, any number of sx:parameter elements.
- A sx:jdbcConnectionPool element.
- One sx:sqlUpdateDatabase element.

## Description

For bulk inserts, JDBC batches may be expected to take only 10-20% of the time needed for default (autocommit) behavior. There is a DB-dependent limit on the number of records in the batch, which is likely related to the size of the SQL statement that gets issued on the executeBatch. There is, however, a rapidly diminishing return to the batch size. In general, 50-100 rows per batch will likely achieve most of the benefit.

Note that some DBMS's (or JDBC drivers) may not support JDBC batches.

## Examples

## See also

- sx:jdbcConnectionPool
- sx:sqlUpdate
- sx:sqlWriter

## Name

sx:sqlCommand — Execute a command on the server after opening a connection

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

An SQL command.

## Examples

Example 83. Example of a SQL command.

    <sx:sqlCommand>set forceplan on</sx:sqlCommand>

## Name

sx:sqlConnectionPool — SQL connection pool

└ sx:jdbcConnectionPool

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
driver | Yes | Java class | The class name of the JDBC driver.
databaseUrl | Yes | URL | The JDBC database URL.
user | No | String | The database user name.
password | No | String | The database password.
minConnections | No | Number | The minimum number of connections to keep in the pool. The default is zero.
maxConnections | No | Number | The maximum number of connections to keep in the pool. The default is any number.
testStatement | No | String | A statement to test the liveness of the database before obtaining a connection.

## Content

Optionally, any number of sx:sqlCommand elements.

## Name

sx:sqlPrepare — Prepare SQL statement

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

The content is a SQL insert or update statement. The statement may have embedded parameter and field names. The format for an embedded parameter is {$parameterName}, and for an embedded field name is {fieldName}.

## Examples

Example 84. Example of a SQL prepare statement.

      <sx:sqlUpdate>
        <sx:parameter name="employee-no" value="{EMPNO}" type="xs:long"/>
        <sx:parameter name="mgr" value="{MGR}" type="xs:long"/>
        <sx:parameter name="hiredate" value="{HIREDATE}" type="xs:date"/>
        <sx:parameter name="salary" value="{SAL}" type="xs:decimal"/>
        <sx:parameter name="commission" value="{COMM}" type="xs:decimal"/>
        <sx:sqlPrepare>
          INSERT INTO EMP_HISTORY(EMPNO, ENAME, JOB, MGR, HIREDATE, SAL, COMM)
          VALUES({$employee-no},{NAME},{JOB}, {$mgr}, {$hiredate},  {$salary}, {$commission})
        </sx:sqlPrepare>
      </sx:sqlUpdate>

Because the SQL insert executes a prepared statement, values must be associated with appropriate types. If the data source is a SQL query source, they will already be associated with SQL types, and no further action is really necessary. In the case of other data sources, however, values by default will be associated with string types, and may need to be recast in parameter assignments, as shown.

## See also

- sx:sqlWriter
- sx:quoteSymbol

## Name

sx:sqlQuery — SQL query

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | The record type of the SQL query. Defaults to "record"
trim | No | true|false | Indicates whether to trim both leading and trailing whitespace from all returned values. Defaults to `false`. (For backwards compatability, "yes"/"no" is also supported.)
trimLeading | No | true|false | Indicates whether to trim leading whitespace from all returned values. Defaults to `false`. (For backwards compatability, "yes"/"no" is also supported.)
trimTrailing | No | true|false | Indicates whether to trim trailing whitespace from all returned values. Defaults to `false`. (For backwards compatability, "yes"/"no" is also supported.)

## Content

Optionally, any number of sx:parameter elements.

Optionally, but deprecated, a sx:quoteSymbol element, to specify escaping of quote symbols in substitution variables. The default, if there is no sx:escapeSubstitutions element in scope, is to escape single quote characters, "'", with two single quote characters, "''". If you need to change the default, use the the configuration element sx:escapeSubstitutions instead of sx:quoteSymbol.

.

The content is a SQL select statement. The statement may have embedded parameter and field names. The format for an embedded parameter is {$parameterName}, and for an embedded field name is {fieldName}. Parameter and field values in the current context will be substituted by name. Parameter and field references bracketed by quote symbols will have their values searched for quote symbols, which if found will be escaped.

The SQL statement may also contain a sx:choose element. This allows for the construction of ad hoc SQL statements based on passed parameters.

## Examples

Example 85. Example of a parameterized query with double quote escaping.

      <sx:sqlQuery recordType = "employee">
        <sx:escapeSubstitutions character='"' escapeCharacter='"'/>
        SELECT EMPNO, ENAME AS NAME,JOB FROM EMP
            WHERE JOB = "{$job}"
      </sx:sqlQuery>

In this example, we specify the double quote as the quote symbol, to be escaped with two double quotes. Since the parameter "job" appears within the specified quote symbols, values of "job" will be searched for double quotes, which if found will be replaced by two double quotes.

Note that if the sx:quoteSymbol element is omitted, the default quote symbol is the single quote, to be escaped with two single quotes.

Example 86. Example of a parameterized query that resolves into alternate SQL statements.

        <sx:parameter name="jobList">
          <sx:toString value="{$job}" separator=",">
            <sx:quoteSymbol character="'" escapeCharacter="'"/>
          </sx:toString>
        </sx:parameter>

        <sx:sqlQuery recordType = "employee">
          SELECT EMPNO, ENAME AS NAME,JOB FROM EMP WHERE 1=1
          <sx:choose>
            <sx:when test="$jobList">
              AND JOB IN ({$jobList})
            </sx:when>
          </sx:choose>
          ORDER BY JOB,ENAME
        </sx:sqlQuery>

In this example, the parameter "job" may have multiple values. In the sx:toString instruction, the multiple values are concatenated into a string of comma-separated, quoted values. If the string is non-empty, the query expression resolves into a select statement with an "IN" clause; otherwise it resolves into a select statement that selects all rows.

## See also

- sx:sqlReader
- sx:quoteSymbol
- sx:toString

## Name

sx:sqlReader — SQL record reader

└ sx:recordReader

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- A sx:jdbcConnectionPool element.
- A sx:sqlQuery element.

## Description

Note that data values resulting from a SQL query are mapped to XML Schema types according to the rules given in XML Schema types.

## Examples

Example 87. Example of a SQL Record Reader.

    <sx:resources xmlns:sx="http://www.servingxml.com/core">

      <sx:service id="employees">
        <sx:serialize>
          <sx:content ref="employees"/>
        </sx:serialize>
      </sx:service>

      <sx:sqlConnectionPool id="jdbcPool"
                             driver="oracle.jdbc.driver.OracleDriver"
                             databaseUrl="jdbc:oracle:thin:@127.0.0.1:1521:dev"
                             user="scott"
                             password="spring"
                             minConnections="2"
                             testStatement="SELECT * FROM DUAL"/>

      <sx:recordContent id="employees">
        <sx:sqlReader>
          <sx:sqlConnectionPool ref="jdbcPool"/>

          <sx:parameter name="jobList">
            <sx:toString value="{$job}" separator=",">
              <sx:quoteSymbol character="'" escapeCharacter="'"/>
            </sx:toString>
          </sx:parameter>

          <sx:sqlQuery recordType = "employee">
            SELECT EMPNO, ENAME AS NAME,JOB FROM EMP WHERE 1=1
            <sx:choose>
              <sx:when test="$jobList">
                AND JOB IN ({$jobList})
              </sx:when>
            </sx:choose>
            ORDER BY JOB,ENAME
          </sx:sqlQuery>
        </sx:sqlReader>

        <sx:recordMapping>
          <employees>
            <sx:groupBy fields="JOB">
              <sx:elementMap element="{JOB}">
                <sx:onRecord>
                  <employee>
                    <sx:fieldAttributeMap field="EMPNO" attribute="employee-no"/>
                    <sx:fieldElementMap field="NAME" element="name"/>
                  </employee>
                </sx:onRecord>
              </sx:elementMap>
            </sx:groupBy>
          </employees>
        </sx:recordMapping>

      </sx:recordContent>

    </sx:resources>

Executing the `employees` service with two `job` parameters, like this

        java -jar dir/servingxml.jar -r resources.xml employees -o output/analysts.txt employees
            job=ANALYST job=CLERK

results in the following SQL statement being sent to the Oracle server:

    SELECT EMPNO, ENAME AS NAME,JOB
      FROM EMP
      WHERE 1=1 AND JOB IN ('ANALYST','CLERK')
      ORDER BY JOB,ENAME

## See also

- sx:jdbcConnectionPool
- sx:sqlQuery
- sx:recordContent

## Name

sx:sqlUpdate — Update or insert rows

└ sx:sqlUpdateDatabase

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recordType | No | QName | Apply updates to records of this record type. Defaults to all records.

## Content

Optionally, any number of sx:parameter elements.

A `sx:sqlUpdate` may contain either text with embedded parameters and fields, which will be evaluated as a SQL statement, or alternatively an sx:sqlPrepare element, which will be compiled into a SQL prepared statement.

Any number of sx:sqlUpdateDatabase elements, such as an sx:sqlUpdateDetail element. The child updates will be part of the same transaction as the parent.

Optionally, but deprecated, a sx:quoteSymbol element, to specify escaping of quote symbols in substitution variables. The default, if there is no sx:escapeSubstitutions element in scope, is to escape single quote characters, "'", with two single quote characters, "''". If you need to change the default, use the the configuration element sx:escapeSubstitutions instead of sx:quoteSymbol.

.

A text SQL update or insert statement may have embedded parameter and field names. The format for an embedded parameter is {$parameterName}, and for an embedded field name is {fieldName}. Parameter and field values in the current context will be substituted by name. Parameter and field references bracketed by quote symbols will have their values searched for quote symbols, which if found will be escaped.

A text SQL statement may also contain a sx:choose element.

## Examples

Example 88. Example of a text SQL update statement.

    <sx:sqlUpdate>
      <sx:quoteSymbol character='"' escapeCharacter='"'/>
      UPDATE EMP SET JOB = "{$job}" WHERE EMPNO={$empNo}
    </sx:sqlUpdate>

In this example, we specify the double quote as the quote symbol, to be escaped with two double quotes. Since the parameter "job" appears within the specified quote symbols, values of "job" will be searched for double quotes, which if found will be replaced by two double quotes. Values of the parameter "empNo", however, will not be searched for double quotes.

Note that if the sx:quoteSymbol element is omitted, the default quote symbol is the single quote, to be escaped with two single quotes.

Example 89. Example of a prepared SQL update statement.

      <sx:sqlUpdate>
        <!-- Because the SQL insert executes a prepared statement, values must be
              associated with appropriate types.
        -->
        <sx:parameter name="employee-no" value="{EMPNO}" type="xs:long"/>
        <sx:parameter name="mgr" value="{MGR}" type="xs:long"/>
        <sx:parameter name="hiredate" value="{HIREDATE}" type="xs:date"/>
        <sx:parameter name="salary" value="{SAL}" type="xs:decimal"/>
        <sx:parameter name="commission" value="{COMM}" type="xs:decimal"/>
        <sx:sqlPrepare>
          INSERT INTO EMP_HISTORY(EMPNO, ENAME, JOB, MGR, HIREDATE, SAL, COMM)
          VALUES({$employee-no},{NAME},{JOB}, {$mgr}, {$hiredate},  {$salary}, {$commission})
        </sx:sqlPrepare>
      </sx:sqlUpdate>

## See also

- sx:sqlWriter
- sx:quoteSymbol

## Name

sx:sqlUpdateChoice — Update based on results of query

└ sx:sqlUpdateDatabase

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.

- A sx:sqlQuery element.

- Optionally, a `sx:recordFound` element, which contains sx:sqlUpdateDatabase elements that will be executed if the query returns rows.

- Optionally, a `sx:recordNotFound` element, which contains sx:sqlUpdateDatabase elements that will be executed if the query does not returns rows.

## Examples

Example 90. Example of a SQL update statement.

      <sx:sqlUpdateChoice>
        <sx:sqlQuery>
          SELECT EMPNO FROM EMP_HISTORY WHERE EMPNO = {EMPNO}
        </sx:sqlQuery>
        <sx:recordNotFound>
          <sx:sqlUpdate>
            INSERT INTO EMP_HISTORY(EMPNO, ENAME) VALUES({EMPNO},'{NAME}')
          </sx:sqlUpdate>
        </sx:recordNotFound>
        <sx:recordFound>
          <sx:sqlUpdate>
            UPDATE EMP_HISTORY SET ENAME = '{NAME}' WHERE EMPNO = {EMPNO}
          </sx:sqlUpdate>
        </sx:recordFound>
      </sx:sqlUpdateChoice>

## See also

- sx:sqlWriter

## Name

sx:sqlUpdateDatabase — Abstract element standing for a SQL update

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
ref | Yes | QName | This attribute is used to reference an id.

## Content

None.

## Description

This is an abstract element that allows you to refer generically to any element supporting add, change, and delete in a SQL database, including sx:sqlUpdate, sx:sqlUpdateChoice, and sx:sqlUpdateDetail.

## Examples

## See also

- sx:sqlUpdate
- sx:sqlUpdateChoice
- sx:sqlUpdateDetail

## Name

sx:sqlUpdateDetail — Update detail rows in one transaction

└ sx:sqlUpdateDatabase

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
field | Yes | QName | The name of a repeating group field whose subrecords are to be written to the database.

## Content

- Optionally, any number of sx:parameter elements.

- Any number of sx:sqlUpdateDatabase elements.

## Examples

Example 91. Example of a SQL update detail statement.

Suppose you have a stream of composite records of type "master" that contain a repeating group field named "details" having subrecords of type "detail". The XML representation of one of these records might look like this:

    <master>
      <masterId>1</masterId>
      <name>aName</name>
      <details>
        <detail>
          <detailId>11</detailId>
          <date>2008-09-03</date>
          <type>aType</type>
        </detail>
        <detail>
          <detailId>12</detailId>
          <date>2008-09-06</date>
          <type>aType</type>
        </detail>
        <detail>
          <detailId>13</detailId>
          <date>2008-09-10</date>
          <type>aType</type>
        </detail>
      </details>
    </master>

The SQL writer below inserts the master/detail records into a master table and a detail table as a single transaction.

      <sx:sqlWriter id="masterDetailWriter">
        <sx:sqlConnectionPool ref="jdbcPool"/>
        <sx:sqlUpdate>
            INSERT INTO master(master_id,name) VALUES({masterId},'{name}')
          <sx:sqlUpdateDetail field="details">
            <sx:sqlUpdate>
              INSERT INTO detail(detail_id,detail_date,detail_type)
              VALUES({detailId},to_date('{date}','yyyy-mm-dd'),'{type}')
            </sx:sqlUpdate>
          </sx:sqlUpdateDetail>
        </sx:sqlUpdate>
      </sx:sqlWriter>

## See also

- sx:sqlWriter
- sx:sqlUpdate

## Name

sx:sqlWriter — SQL record writer

└ sx:recordWriter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- A sx:jdbcConnectionPool element.
- One or more sx:sqlUpdate or sx:sqlUpdateChoice elements. The updates are wrapped in a transaction and will either all succeed or all fail.

## Examples

## See also

- sx:jdbcConnectionPool
- sx:sqlUpdate
- sx:recordWriter

# SUN Multi Schema Validator Extension

This section describes the SUN Multi Schema Validator extension elements. All SUN MSV extension elements require the namespace declaration `xmlns:msv="http://www.servingxml.com/extensions/msv"` to appear in the resources script.

## Name

msv:msvFilter — Deprecated, replaced by msv:schemaValidator

└ sx:content

## Name

msv:msvRecordFilter — Deprecated, replaced by msv:recordValidator

## Name

msv:recordValidator — Validate record with XML schema

└ sx:recordFilter

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.

## Content

- Optionally, any number of sx:parameter elements.
- A sx:streamSource element, or a sx:saxSource element, or an in-lined XML schema document.

## Description

This instruction validates individual records as they are read in from a flat file or SQL source, and discards records when errors are encountered.

## Content

- A sx:streamSource element, or a sx:saxSource element, or an in-lined XSLT tree.

## Examples

Example 92. Validating individual records in the incoming countries flat file.

### Resources script

    <sx:recordContent id="countries">
      <sx:recordStream>
        <sx:flatFileReader>
          <sx:urlSource url="data/countries.csv"/>
          <sx:flatFile ref="countriesFile"/>
        </sx:flatFileReader>
        <msv:recordValidator>
          <sx:urlSource url="data/country-record.xsd"/>
        </msv:recordValidator>
        <sx:discardHandler>
          <sx:log message="{$sx:message}"/>
          <sx:modifyRecord>
            <sx:newField name="message" value="{$sx:message}"/>
          </sx:modifyRecord>
          <sx:flatFileWriter>
            <sx:fileSink file="output/countryDiscards.csv"/>
            <sx:flatFile ref="discardFile"/>
          </sx:flatFileWriter>
        </sx:discardHandler>
      </sx:recordStream>
      <sx:recordMapping ref="countriesToXmlMapping"/>
    </sx:recordContent>

    <sx:flatRecordType id="country" name="country">
      <sx:fieldDelimiter value=","/>
      <sx:delimitedField name="code"/>
      <sx:delimitedField name="name"/>
    </sx:flatRecordType>

    <sx:flatFile id="discardFile">
      <sx:flatFileBody>
        <sx:flatRecordType name="countryDiscard">
          <sx:fieldDelimiter value=","/>
          <sx:delimitedField name="message"/>
          <sx:flatRecordType ref="country"/>
        </sx:flatRecordType>
      </sx:flatFileBody>
    </sx:flatFile>

### Schema

    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

     <!-- This element's name matches the value of the name attribute in the sx:flatRecordType element. -->
     <xs:element name="country" type="CountryType"/>

     <xs:complexType name="CountryType">
      <xs:sequence>
       <xs:element name="code" type="CountryCode"/>
       <xs:element name="name" type="xs:string"/>
      </xs:sequence>
     </xs:complexType>

      <xs:simpleType name='CountryCode'>
        <xs:restriction base='xs:string'>
          <xs:length value='3' fixed='true'/>
        </xs:restriction>
      </xs:simpleType>
    </xs:schema>

## See also

- sx:discardHandler

## Name

msv:schemaValidator — Validate XML with schema

└ sx:content, sx:validator

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
message | No | SubstitutionExpr | A message indicating the error if validation fails, defaults to the message provided by the MSV validator.

## Content

- A sx:streamSource element, or a sx:saxSource element, or an in-lined XML schema document.

## Description

This instruction validates the XML output as it is produced, and will abort processing if an error is encountered.

## Examples

Example 93. Validating the countries document.

### Resources script

    <sx:resources xmlns:sx="http://www.servingxml.com/core"
                  xmlns:msv="http://www.servingxml.com/extensions/msv">

      <sx:service id="countries">
        <sx:serialize>
          <sx:transform>
            <sx:content ref="countries"/>
            <msv:schemaValidator>
              <sx:urlSource url="data/countries.xsd"/>
            </msv:schemaValidator>
          </sx:transform>
        </sx:serialize>
      </sx:service>

      <sx:recordContent id="countries" name="countries">
        <sx:flatFileReader>
          <sx:urlSource url="data/countries.csv"/>
          <sx:flatFile ref="countriesFile"/>
        </sx:flatFileReader>
        <sx:recordMapping ref="countriesToXmlMapping"/>
      </sx:recordContent>

      <sx:flatFile id="countriesFile">
        <sx:commentStarter value="#"/>
        <sx:flatFileBody>
          <sx:flatRecordType name="country">
            <sx:fieldDelimiter value=","/>
            <sx:delimitedField name="code"/>
            <sx:delimitedField name="name" trimLeading="true"/>
          </sx:flatRecordType>
        </sx:flatFileBody>
      </sx:flatFile>

      <sx:recordMapping id="countriesToXmlMapping">
        <countries>
          <sx:onRecord>
            <country>
              <sx:fieldElementMap field="name" element="countryName"/>
              <sx:fieldAttributeMap field="code" attribute="countryCode"/>
            </country>
          </sx:onRecord>
        </countries>
      </sx:recordMapping>

    </sx:resources>

### Schema

    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

     <!-- This element's name is the same as that of the root element appearing inside the sx:recordMapping element. -->
     <xs:element name="countries" type="CountriesType"/>

     <xs:complexType name="CountriesType">
      <xs:sequence>
          <xs:element name="country" type="CountryType" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
     </xs:complexType>

     <xs:complexType name="CountryType">
      <xs:sequence>
       <xs:element name="countryName" type="xs:string"/>
      </xs:sequence>
      <xs:attribute name="countryCode" type="CountryCode"/>
     </xs:complexType>

      <xs:simpleType name='CountryCode'>
        <xs:restriction base='xs:string'>
          <xs:length value='3' fixed='true'/>
        </xs:restriction>
      </xs:simpleType>
    </xs:schema>

# Apache FOP Extension

This section describes the Apache FOP extension elements. All Apache FOP extension elements require the namespace declaration `xmlns:fop="http://www.servingxml.com/extensions/fop"` to appear in the resources script.

## Name

fop:foEmitter — Deprecated, aliased to fop:foSerializer

└ sx:saxSink

## Name

fop:foSerializer — Apache FOP xsl/fo serializer

└ sx:saxSink

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
mimeType | No | string | The MIME type of the output, which must be a supported FOP MIME type. Defaults to "application/pdf".

## Content

None.

## Examples

Example 94. Serializing xsl-fo with an Apache FOP serializer to produce pdf.

    <sx:resources xmlns:sx="http://www.servingxml.com/core"
                  xmlns:fop="http://www.servingxml.com/extensions/fop"> ...

      <sx:service id="pulp">
        <sx:serialize>
          <fop:foSerializer/>
          <sx:transform>
            <sx:content ref="myns:pulp"/>
            <sx:xslt ref="novel-fo"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

Example 95. Serializing xsl-fo with an Apache FOP serializer to produce RTF.

    <sx:resources xmlns:sx="http://www.servingxml.com/core"
                  xmlns:fop="http://www.servingxml.com/extensions/fop"> ...

      <sx:service id="pulp">
        <sx:serialize>
          <fop:foSerializer mimeType="application/rtf"/>
          <sx:transform>
            <sx:content ref="myns:pulp"/>
            <sx:xslt ref="novel-fo"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

# Java Mail Extension

This section describes the Java Mail extension elements. All Java Mail extension elements require the namespace declaration `xmlns:jm="http://www.servingxml.com/extensions/javamail"` to appear in the resources script.

## Name

jm:attachment — Attachment

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
filename | No | SubstitutionExpr | The name of the attached file.

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:task elements.

## Description

A jm:attachment instruction defines a sequence of content generation, transform, filter and serialization steps that result in serialized output of some MIME type as an attachment to a message.

## Name

jm:mailAccount — Mail account

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
smtpHost | Yes | host | The smtp host.

## Content

A jm:sender element.

## Examples

Example 96. Defining a mail account.

      <jm:mailAccount id="my-account"
                      smtpHost="changeme">
        <jm:sender displayName="changeme" emailAddress="changeme"/>
      </jm:mailAccount>

## Name

jm:message — Message

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
smtpHost | Yes | host | The smtp host.

## Content

- Optionally, a text body.
- Optionally, any number of jm:part elements.
- Optionally, any number of jm:attachment elements.

itemizedlist>

## Name

jm:part — MIME part

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
type | No | type code | The type of a part. The only allowed value is "alternative"

## Content

- Optionally, any number of sx:parameter elements.
- Any number of sx:task elements.

## Description

A jm:part instruction defines a sequence of content generation, transform, filter and serialization steps that result in serialized output of some MIME type in the body of a message.

## Name

jm:sender — Sender

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
displayName | No | String | The display name for the owner of the account.
emailAddess | Yes | address | The email address of the sender.

## Content

None.

## Name

jm:sendMail — Send mail

└ sx:task, sx:stringable

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
subject | Yes | String | The subject of the message.
to | Yes | SubstitutionExpr | A comma separated list of email addresses of recipients.
cc | Yes | SubstitutionExpr | A comma separated list of email addresses of recipients.

## Content

- Optionally, any number of sx:parameter elements.
- A jm:mailAccount element.
- A jm:message element.
- A sx:onError element.

itemizedlist>

## Examples

Example 97. Mail example.

    <sx:resources xmlns:sx="http://www.servingxml.com/core"
                  xmlns:fop="http://www.servingxml.com/extensions/fop"
                  xmlns:jm="http://www.servingxml.com/extensions/javamail"> ...

      <sx:service id="pulp">
          <!--  Our first action is to send an email with the pulp novel as an attachment   -->
          <jm:sendMail subject="test" to="john@yyy.com" cc="linda@zzz.com">
            <jm:mailAccount ref="myMailAccount"/>
            <jm:message>

              <!-- Put some HTML in the message body -->
              <jm:part type="alternative">
                <sx:transform>
                  <sx:document><xxx/></sx:document>
                  <sx:xslt ref="welcome/html"/>
                </sx:transform>
              </jm:part>

              <jm:attachment filename="pulp.pdf">
                <fop:foSerializer/>
                <sx:transform>
                   <sx:content ref="pulp"/>
                   <sx:xslt ref="novel/fo"/>
                </sx:transform>
              </jm:attachment>
            </jm:message>
          </jm:sendMail>

      </sx:service>

# EDT FTP Extension

This section describes the EDT FTP extension elements. All EDT FTP extension elements require the namespace declaration `xmlns:edt="http://www.servingxml.com/extensions/edtftp"` to appear in the resources script.

## Name

edt:ftpClient — FTP client

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
host | Yes | String | Host name.
port | No | Number | The port number, defaults to 21.
user | Yes | String | The user name.
password | No | String | The password.
remoteSiteCommand | No | String | Optional remote site command.

## Content

None.

## Name

edt:ftpDirectoryReader — FTP directory reader

└ sx:recordReader

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
recurse | No | true|false | Set to `true` to recurse through a directory tree, `false` otherwise. Defaults to "false." (For backwards compatability, yes/no is also supported.)
maxItems | No | Number | The maximum number of directory items to read.
directory | No | SubstitutionExpr | The remote directory. Defaults to the current directory on the remote server.

## Content

- Optionally, any number of sx:parameter elements.

## Description

Each record will have type

- directory - if the entry is a directory
- file - if the entry is a file.

Each record will contain the following fields:

- parentDir - the parent directory, if any (deprecated, use parentDirectory instead)
- parentDirectory - the parent directory, if any
- name - the name of the file or directory.
- lastModified - the time the file was last modified, with a lexical representation as defined for xs:dateTime of XML Schema Part 2: Datatypes.
- size - the file size, in bytes
- permissions
- owner
- isLink - "yes" or "no"

## Name

edt:ftpSink — FTP sink

└ sx:streamSink

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
transferType | No | binary or ascii | The transfer type, defaults to ascii.
remoteDir | No | SubstitutionExpr | Deprecated - use `remoteDirectory` instead.
remoteDirectory | No | SubstitutionExpr | The remote directory.
remoteFile | SubstitutionExpr | String | The name of the remote output file, may contain parameters in the form {$myParam}.
localDir | No | SubstitutionExpr | The local directory.
localFile | No | SubstitutionExpr | The local file to write to before sending it to the remote directory. Defaults to a timestamped temporary file.
deleteLocalFile | No | true|false | Delete the local file after processing the remote file. Defaults to `false`. (For backwards compatability, yes/no is also supported.)

## Content

- A edt:ftpClient element.

## Examples

Example 98. Example of FTP file sink.

    <sx:resources xmlns:sx="http://www.servingxml.com/core"
                  xmlns:edt="http://www.servingxml.com/extensions/edtftp">

      <edt:ftpClient  id="myhost" host="myhost.com"
              user="anonymous" password="xxx"/>

      <sx:service id="books">
        <sx:serialize>
          <sx:xsltSerializer>
            <edt:ftpSink remoteDirectory="incoming" remoteFile="books.xml">
              <edt:ftpClient ref="myhost"/>
            </edt:ftpSink>
          </sx:xsltSerializer>
          <sx:transform>
            <sx:content ref="books"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

      <sx:document id="books" href="documents/books.xml"/>

    </sx:resources>

## See also

- sx:streamSink
- edt:ftpClient

## Name

edt:ftpSource — FTP source

└ sx:streamSource

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
transferType | No | binary or ascii | The transfer type, defaults to ascii.
remoteDir | No | SubstitutionExpr | Deprecated - use `remoteDirectory` instead.
remoteDirectory | No | SubstitutionExpr | The remote directory.
remoteFile | Yes | SubstitutionExpr | The name of the remote input file, may contain parameters in the form {$myParam}.
localDir | No | SubstitutionExpr | The local directory.
localFile | No | SubstitutionExpr | The local file to write to before reading its content. Defaults to a timestamped temporary file.
deleteLocalFile | No | true|false | Delete the local file after processing the remote file. Defaults to `false`. (For backwards compatability, yes/no is also supported.)

## Content

- A edt:ftpClient element.

## Examples

Example 99. Example of FTP file source.

    <sx:resources xmlns:sx="http://www.servingxml.com/core"
                  xmlns:edt="http://www.servingxml.com/extensions/edtftp">

      <edt:ftpClient  id="myhost" host="myhost.com"
              user="anonymous" password="xxx"/>

      <sx:service id="books">
        <sx:serialize>
          <sx:transform>
            <sx:content ref="books"/>
          </sx:transform>
        </sx:serialize>
      </sx:service>

      <sx:document id="books" href="documents/books.xml">
          <edt:ftpSource remoteDirectory="incoming" remoteFile="books.xml">
              <edt:ftpClient ref="myhost"/>
          </edt:ftpSource>
    </sx:document>

    </sx:resources>

## See also

- sx:streamSource
- edt:ftpClient

# Saxon XQuery Extension

This section describes the Saxon XQuery extension element. All Saxon extension elements require the namespace declaration `xmlns:saxon="http://www.servingxml.com/extensions/saxon"` to appear in the resources script.

## Name

saxon:xquery — Saxon 9 xquery processor

└ sx:content

## Attributes

Name | Required | Value | Description
--- | --- | --- | ---
idref-attributes | No |  | Common id ref attributes.
documentBase | No | SubstitutionExpr | This attribute is used to explicitly set the the static context of the query. The base can be relative, in which case it is resolved relative to xml:base, if in scope, or otherwise the location of the resources script.

## Content

- Optionally, an sx:content specialization, such as a sx:document, sx:recordContent or sx:transform element, to specify the initial context item.

- Either an sx:streamSource element to load the query, or an sx:stringable element to specify the query inline (usually a sx:preserveMarkup element.)

## Description

The `saxon:xquery` element wraps the Saxon XQuery processor.

Prefix declarations appearing in the `saxon:xquery` element will form part of the static context of the query, but they will not be copied into result trees unless the prefix is actually used in an element or attribute name. These declarations will be overridden by declarations that appear in the query prolog.

The attribute `documentBase` can be used to set the static base URI for the query, defaults to the `xml:base` in scope, or if there is none, to the location of the resources file.

## Examples

Example 100. XQuery example.

      <!-- This is "TestF" in the Saxon sample file XQJExamples.java -->

    <sx:service id="test1">
      <sx:serialize >
        <sx:transform>
          <saxon:xquery>
            <sx:preserveMarkup>
              document { <a xmlns='http://a/uri' z:in='out'
                           xmlns:z='http://z/uri'><b>{2+2}</b></a> }
            </sx:preserveMarkup>
          </saxon:xquery>
        </sx:transform>
      </sx:serialize>
    </sx:service>

Example 101. XQuery example.

    <sx:service id="test2">
      <sx:serialize>
        <sx:transform>
          <saxon:xquery xmlns:myns="http://mycompany.com/mynames/">
            <sx:document>
              <sx:fileSource file="data/books.xml"/>
            </sx:document>
            <sx:preserveMarkup>
              <copy>{//myns:book[1]}</copy>
            </sx:preserveMarkup>
          </saxon:xquery>
        </sx:transform>
      </sx:serialize>
    </sx:service>

Example 102. Initializing parameters from an XML file.

In this example, parameter values come from an XML file,

    <parameters>
      <validate>yes</validate>
    </parameters>

The parameter declaration below initializes the parameter `validate` with an XQuery FLWOR expression.

      <sx:service id="countries">
        <sx:parameter name="validate">
          <saxon:xquery>
            <sx:toString>doc('data/parameters.xml')/parameters/validate
            </sx:toString>
          </saxon:xquery>
        </sx:parameter>

        <sx:serialize>
          <sx:choose>
            <sx:when test="$validate='yes'">
              <sx:transform>
                <sx:content ref="countries"/>
                <msv:schemaValidator>
                  <sx:urlSource url="data/countries.xsd"/>
                </msv:schemaValidator>
              </sx:transform>
            </sx:when>
            <sx:otherwise>
              <sx:transform>
                <sx:content ref="countries"/>
              </sx:transform>
            </sx:otherwise>
          </sx:choose>
        </sx:serialize>
      </sx:service>

## Glossary

CSV

  Comma separated values (CSV).

Mime Type

  The Multipurpose Internet Mail Extension (MIME) type, which identifies the type of document.

NameTest

  A qName, or a wildcard (*),or a space separated list of qNames.

NCName

  NCName stands for "no colon name." An example is "books."

QName

  QName stands for "qualified name." An example is "myns:books."

Regex

  Regular expression.

SAXPath

  A `SAXPath` pattern is an expression that matches on a stack of SAX events as they flow through a SAX filter. The syntax for a `SAXPath` is a restricted XSLT match pattern, including the parts that make sense for filtering on the SAX `startElement` event. The match pattern is evaluated against the path of elements leading to the current element, the attributes of the elements, and any parameters in scope.

  A SAXPath pattern consists of a series of one or more elements separated by "/" or "//". An absolute SAXPath pattern begins with a "/" or "//", and is matched against the entire path of elements. A relative SAXPath pattern is matched against a portion of the path that ends at the current element. Each matched path is assigned a position, starting with 1.

  A "//" expands to match any series of elements separating two matched path entries. The wildcard "*" may be used to match against any element.

  Examples of SAXPath expressions.

  - `/myns:books/myns:book` matches on all `myns:book` child elements of the root element `myns:books`.

  - `/myns:books/myns:book[1]` matches on the first `myns:book` child element of the root element `myns:books`.

  - `/myns:books/myns:book[2]` matches on the second `myns:book` child element of the root element `myns:books`.

  - `myns:book[@price=10.50]` matches on all `myns:book` elements that have an attribute `price` with value `10.5`.

  - `myns:title` matches on all `myns:title` elements

  - `//myns:title` matches on all `myns:title` elements

  - `/myns:books/*/myns:author` matches on all `myns:author` grandchild elements of the root element `myns:books`

  - `product[@type='SWAP']/leg` matches on all `leg` child elements of `product` parent elements that have an attribute `type` with value `SWAP`.

  - `product[@type='SWAP']/leg[@side="PAY"]` matches on all `leg` elements that have an attribute `side` with value `PAY` and a parent element `product` that has an attribute `type` with value `SWAP`.

  Predicates that a path entry must satisfy are appended to the entry with square brackets, for example,

        product[@type='SWAP' and $selection='SWAP']

  Predicates may refer to attributes of the associated element, any parameters in scope, string literals, or numerical constants. The supported binary operators are as follows.

  Table 1. Binary operators.

  Precedence | Operator
  --- | ---
  0 | or
  1 | and
  2 | =,!=,<,<,=,>,>=

  Expressions may be grouped inside parenthesis to override the default operator precedence, for example

        product[(@type='SWAP' or @type='CDS' or @type='TRS') and $selection='SWAP']

SubstitutionExpr

  A string value that may contain one or more parameters enclosed in curly braces, e.g. "{$my-param}.xml" and in contexts allowing a record, one or more fields in curly braces, e.g. "{my-field}"

Uniform Resource Identifier

  A short string that stands for the name or address of a resource.

## Appendix A. Data Type Mappings

Table A.1. Supported XML Schema Types

| XML Schema Type
--- | ---
Character types | xs:string
Numeric types | xs:byte
| xs:integer
| xs:long
| xs:float
| xs:double
| xs:decimal
Date types | xs:dateTime
| xs:date
| xs:time
Bit data types | xs:boolean
| xs:hexBinary

Table A.2. Supported JDBC Data Type Mappings

| JBC Data Type | XML Schema Type
--- | --- | ---
Character types | CHAR | xs:string
| VARCHAR | xs:string
| LONGVARCHAR | xs:string
| CLOB | xs:string
Numeric types | TINYINT | xs:byte
| SMALLINT | xs:short
| INTEGER | xs:integer
| BIGINT | xs:long
| BIGINT | xs:long
| FLOAT | xs:float
| DOUBLE | xs:double
| BIGINT | xs:long
| DECIMAL | xs:decimal
| NUMERIC | xs:decimal
Date types | TIMESTAMP | xs:dateTime
| DATE | xs:date
| TIME | xs:time
Bit data types | BIT | xs:boolean
| BINARY | xs:hexBinary
| VARBINARY | xs:hexBinary
| LONGVARBINARY | xs:hexBinary

## Appendix B. Deprecated Elements and Attributes

Table B.1. Deprecated and removed elements

Element | Change | Version changed | Replace with | Comment
--- | --- | --- | --- | ---
sx:replaceRecordFilter | Deprecated | 1.0.2 | sx:replaceRecord |
sx:defaultFieldMapping | Deprecated | 1.0.0 | sx:defaultFieldElementMap |
sx:escapeVariables | Deprecated | 1.0.0 | sx:escapeSubstitutions |
sx:spannedFlatRecordType | Deprecated | 1.0.0 | sx:vbsFlatRecordType |
sx:xmlRecordReader | Deprecated | 1.0.0 | sx:subtreeRecordReader |
sx:validateRecord | Deprecated | 1.0.0 | sx:recordValidator |
sx:validateField | Deprecated | 1.0.0 | sx:fieldValidator |
sx:insertContent | Deprecated | 0.9.3 | sx:nestedContent |
sx:segmentMapping | Deprecated | 0.9.3 | sx:subrecordMapping |
sx:replace | Deprecated | 0.9.2 | sx:findAndReplace |
sx:taggedFlatRecordField | Removed | 0.9.0 | sx:flatRecordField |
sx:tagDelimiter | Deprecated | 0.9.0 | sx:nameDelimiter |
sx:taggedDelimitedField | Deprecated | 0.9.0 | sx:delimitedNamedField |
sx:repeatingTaggedField | Deprecated | 0.9.0 | sx:repeatingField |
sx:repeatingSegment | Deprecated | 0.8.4 | sx:repeatingGroup |
sx:aggregateRecord | Deprecated | 0.8.3 | sx:composeRecord |
sx:recordAggregator | Deprecated | 0.8.2 | sx:composeRecord |
sx:subtreeRecordMap | Deprecated | 0.8.1 | sx:flattenSubtree |
sx:documentFragment | Deprecated | 0.8.1 | sx:nestedContent |
sx:removeEmptyElementFilter | Deprecated | 0.8.0 | sx:removeEmptyElements |
sx:aggregate | Deprecated | 0.8.1 | sx:nestedContent |
sx:recordTest | Deprecated | 0.8.0 | sx:recordRestriction |
sx:regexFieldCriteria | Deprecated | 0.8.0 | sx:fieldRestriction |
sx:startGroup | Deprecated | 0.6.5 | `startTest` | The `test` attribute of `sx:startGroup"` has the same meaning as the `startTest` attribute attribute of sx:innerGroup and sx:outerGroup . When converting, this value remains the same.
sx:endGroup | Deprecated | 0.6.5 | `endTest` attribute | The `test` attribute of `sx:endGroup` is applied to the "current" record, and identifies the last record (inclusive) of a group. Consequently, it usually needs to test the "next" record. The `endTest` attribute, by contrast, is applied to the "next" record. When converting, a test against the "current" record must be changed to a test against the "previous" record, and a test against the "next" record must be changed to a test against the "current" record.
msv:msvFilter | Deprecated | 0.6.4 | msv:schemaValidator |
sx:discardFilter | Deprecated | 0.6.2 | sx:discardHandler | `sx:discardFilter` came before a sequence of filters and writers; `sx:discardHandler` comes after a sequence of filters and writers
sx:date | Deprecated | 0.6.1 | sx:currentDateTime and sx:formatDateTime |
sx:xmlEmitter | Deprecated | 0.6.1 | sx:xsltSerializer |
sx:customEmitter | Deprecated | 0.6.1 | sx:customSerializer |
fop:foEmitter | Removed | 0.6.1 | fop:foSerializer |
sx:commentSymbol | Deprecated | 0.6.0 | sx:commentStarter |
sx:restrictRecordType | Deprecated | 0.6.0 | sx:recordRestriction |
sx:restrictField | Deprecated | 0.6.0 | sx:fieldRestriction |
sx:subtreeFilter | Deprecated | 0.6.0 | sx:processSubtree |
sx:processRecordFilter | Deprecated | 0.6.0 | sx:processRecord |
sx:crcFlatFileSignature | Deprecated | 0.5.5 | sx:flatFileSignature |
sx:sizeFlatFileSignature | Deprecated | 0.5.5 | sx:flatFileSignature |
sx:processRecords | Deprecated | 0.5.3 | sx:recordStream |
sx:msvRecordFilter | Deprecated | 0.5.2 | msv:recordValidator |
sx:recordSubtreeMap | Deprecated | 0.5.0 | sx:transformRecord |
sx:writeRecords | Deprecated | 0.5.0 | sx:recordStream |
sx:documentSubtreeMap | Deprecated | 0.5.0 | sx:onSubtree |
sx:style | Deprecated | 0.5.0 | sx:xslt |
Record filter children of record reader | Removed | 0.4.2 | Record filter siblings of record reader | Discouraged since 0.4.0. Examples were changed except for sx:directoryReader examples (now updated.)
sx:flatFileContent | Removed | 0.4.2 | sx:recordContent and sx:flatFileReader | Deprecated since 0.1.3.
sx:processFragmentFilter | Deprecated | 0.3.4 | sx:processSubtree |
sx:documentFragmentContentMap | Deprecated | 0.3.4 | sx:onSubtree |
sx:documentFragmentRecordMap | Deprecated | 0.3.4 | sx:flattenSubtree |
sx:documentFragmentFieldMap | Deprecated | 0.3.4 | sx:subtreeFieldMap |
sx:documentRecordMap | Removed | 0.1.8 | sx:onSubtree |
sx:element | Deprecated | 0.3.2 | sx:elementMap |
sx:fieldSetElementMap | Deprecated | 0.3.2 | sx:defaultFieldElementMap |
sx:flowFilter | Deprecated | 0.3.2 | sx:processSubtree |
sx:flowRecordFilter | Deprecated | 0.3.2 | sx:processRecord |
sx:subrecordFilter | Deprecated | 0.3.0 | See the edi example |
sx:taskRunnerFilter | Deprecated | 0.3.0 | sx:processSubtree |
sx:taskRunnerRecordFilter | Deprecated | 0.3.0 | sx:processRecord |
sx:flatFileRecordType | Deprecated | 0.2.5 | sx:flatRecordType |
sx:chooseGroup | Deprecated | 0.2.5 | sx:groupChoice |
sx:transformerSettings | Deprecated | 0.2.5 | sx:xsltConfiguration |
sx:subtaskFilter | Deprecated | 0.2.4 | sx:processSubtree |
sx:subtaskRecordFilter | Deprecated | 0.2.4 | sx:processRecord |
sx:processDocument | Removed | 0.3.0 | Omit, sx:transform is okay. |
sx:currentRecordFilter | Deprecated | 0.2.0 | sx:processRecord |
sx:documentFragmentFilter | Deprecated | 0.2.0 | sx:processSubtree |
sx:jaxpConfiguration | Deprecated | 0.2.0 | sx:xsltConfiguration |
sx:documentFragmentFilter | Deprecated | 0.1.8 | sx:processSubtree |
sx:pathFieldMap | Removed | 0.1.8 | sx:subtreeFieldMap |
sx:expirySettings | Removed | 0.1.8 | sx:expiryOptions |
sx:pathRecordMap | Removed | 0.1.8 | sx:onSubtree |
sx:customSerializer | Removed | 0.1.7 | sx:customSerializer |
fop:fopSerializer | Removed | 0.1.7 | fop:foSerializer |
sx:customProperty | Deprecated | 0.1.7 | sx:property |
sx:taskRecordFilter | Deprecated | 0.1.7 | sx:processRecord |
sx:saxParser | Deprecated | 0.1.7 | sx:saxReader |
sx:removeEmptyElements | Deprecated | 0.1.6 | sx:removeEmptyElements |
sx:customXmlFilter | Deprecated | 0.1.6 | sx:saxFilter |
sx:emptyContent | Deprecated | 0.1.6 | sx:emptyDocument |
sx:flatFileLayout | Deprecated | 0.1.6 | sx:flatFile |
sx:jdbcConnectionPool | Made abstract | 0.1.6 | sx:sqlConnectionPool | Old version still supported.
sx:mailOutput | Removed | 0.1.6 | jm:sendMail |
sx:readerWriterRecordFilter | Removed | 0.1.6 | sx:processRecord |
sx:recordOutput | Deprecated | 0.1.6 | sx:writeRecords |
sx:restrictFieldFilter | Deprecated | 0.1.6 | sx:fieldRestriction |
sx:streamContent | Deprecated | 0.1.6 | sx:document |
sx:streamOutput | Deprecated | 0.1.6 | sx:serialize |
sx:suppressEmptyElementFilter | Deprecated | 0.1.6 | sx:removeEmptyElements |
sx:delimitedFieldType | Deprecated | 0.1.4 | sx:delimitedField |
sx:flatFileRecord | Deprecated | 0.1.4 | sx:flatFileBody |
sx:positionalFieldType | Deprecated | 0.1.4 | sx:positionalField |
sx:field | Deprecated | 0.1.3 | sx:positionalField or sx:delimitedField |
sx:flatFileContent | Deprecated | 0.1.3 | sx:recordContent | Use a sx:flatFileReader child element.
sx:sqlContent | Removed | 0.1.3 | sx:recordContent | Use a sx:sqlReader child element

Table B.2. Deprecated and removed attributes

Element | Attribute | Change | Version changed | Replace with
--- | --- | --- | --- | ---
sx:customJdbcConnectionPool | className | Deprecated | 0.1.6 | class
sx:customRecordFilter | className | Deprecated | 0.1.6 | class
sx:saxFilter (saxFilter) | className | Deprecated | 0.1.6 | class
sx:dynamicContent | className | Deprecated | 0.1.6 | class
sx:customRecordFilter | classHandler | Deprecated | 0.1.5 | class
sx:saxFilter (sx:saxFilter) | classHandler | Deprecated | 0.1.5 | class
sx:dynamicContent | classHandler | Deprecated | 0.1.5 | class

## Index

### A

aggregateRecords, sx:aggregateRecords
and, sx:and
annotationRecord, sx:annotationRecord
assert, sx:assert
attachment, jm:attachment
attribute, sx:attribute

### B

batchedRecordWriter, sx:batchedRecordWriter
batchedSerializer, sx:batchedSerializer
batchRecords, sx:batchRecords
binaryField, sx:binaryField

### C

cachedContent, sx:cachedContent
cacheSettings, sx:cacheSettings
cdata, sx:cdata
choose, sx:choose
command, sx:command
commandArg, sx:commandArg
commandSink, sx:commandSink
commandSource, sx:commandSource
commentStarter, sx:commentStarter
commentSymbol, sx:commentSymbol
composeRecords, sx:composeRecord
compositeFlatRecordType, sx:compositeFlatRecordType
concat, sx:concat
content, sx:content
convertDate, sx:convertDate
convertToDateTime, sx:convertToDateTime
crcFlatFileSignature, sx:crcFlatFileSignature
currentDate, sx:currentDate
currentDateTime, sx:currentDateTime
currentTime, sx:currentTime
customEmitter, sx:customEmitter
customJdbcConnectionPool, sx:customJdbcConnectionPool
customRecordFilter, sx:customRecordFilter
customRecordReader, sx:customRecordReader
customSerializer, sx:customSerializer

### D

date, sx:date
decomposeRecords, sx:decomposeRecord
defaultFieldAttributeMap, sx:defaultFieldAttributeMap
defaultFieldElementMap, sx:defaultFieldElementMap
defaultStreamSink, sx:defaultStreamSink
defaultStreamSource, sx:defaultStreamSource
defaultValue, sx:defaultValue
delimitedField, sx:delimitedField
delimitedNamedField, sx:delimitedNamedField
directoryReader, sx:directoryReader
discard, sx:discard
discardFilter, sx:discardFilter
discardHandler, sx:discardHandler
documentFragment, sx:documentFragment
documentSequence, sx:documentSequence
documentSubtreeMap, sx:documentSubtreeMap
dynamicContent, sx:dynamicContent

### E

elementMap, sx:elementMap
emptyDocument, sx:emptyDocument
envVariable, sx:envVariable
escapeMarkup, sx:escapeMarkup
escapeVariables, sx:escapeVariables
expiryOptions, sx:expiryOptions

### F

fieldAttributeMap, sx:fieldAttributeMap
fieldDelimiter, sx:fieldDelimiter
fieldElementMap, sx:fieldElementMap
fieldElementSequenceMap, sx:fieldElementSequenceMap
fieldRestriction, sx:fieldRestriction
fieldValidator, sx:fieldValidator
fileFilter, sx:fileFilter
fileSink, sx:fileSink
fileSource, sx:fileSource
filter, sx:filter
findAndReplace, sx:findAndReplace
flatFile, sx:flatFile
flatFileBody, sx:flatFileBody
flatFileHeader, sx:flatFileHeader
flatFileReader, sx:flatFileReader
flatFileSignature, sx:flatFileSignature
flatFileTrailer, sx:flatFileTrailer
flatFileWriter, sx:flatFileWriter
flatRecordField, sx:flatRecordField
flatRecordType, sx:flatRecordType
flatRecordTypeChoice, sx:flatRecordTypeChoice
flattenSubtree, sx:flattenSubtree
foEmitter, fop:foEmitter
formatDateTime, sx:formatDateTime
foSerializer, fop:foSerializer
ftpClient, edt:ftpClient
ftpDirectoryReader, edt:ftpDirectoryReader
ftpSink, edt:ftpSink
ftpSource, edt:ftpSource

### G

groupBy, sx:groupBy
groupChoice, sx:groupChoice

### I

include, sx:include
inlineSource, sx:inlineSource
innerGroup, sx:innerGroup
insertContent, sx:insertContent, sx:nestedContent
integerField, sx:integerField
inverseRecordMapping, sx:inverseRecordMapping

### J

jdbcConnectionPool, sx:jdbcConnectionPool

### K

key, sx:key
keyField, sx:keyField

### L

lineNumber, sx:lineNumber
log, sx:log

### M

mailAccount, jm:mailAccount
mapXml, sx:mapXml
message, jm:message
metaRecord, sx:metaRecord
modifyRecord, sx:modifyRecord
msvFilter, msv:msvFilter
msvRecordFilter, msv:msvRecordFilter

### N

nameDelimiter, sx:nameDelimiter
newField, sx:newField
newRecord, sx:newRecord

### O

onError, sx:onError
onRecord, sx:onRecord
onSubtree, sx:onSubtree
or, sx:or
otherwise, sx:otherwise
outerGroup, sx:outerGroup
outputProperty, sx:outputProperty
overpunchField, sx:overpunchField

### P

packedDecimalField, sx:packedDecimalField
parameter, sx:parameter
parameterReader, sx:parameterReader
part, jm:part
patternMatcher, sx:patternMatcher
positionalField, sx:positionalField
preserveMarkup, sx:preserveMarkup
processRecord, sx:processRecord
processRecordFilter, sx:processRecordFilter
processRecords, sx:processRecords
processSubtree, sx:processSubtree
property, sx:property

### Q

quoteSymbol, sx:quoteSymbol

### R

raiseError, sx:raiseError
recordAggregator, sx:recordAggregator
recordComposition, sx:recordComposition
recordContent, sx:recordContent
recordDelimiter, sx:recordDelimiter
recordFilter, sx:recordFilter
recordMapping, sx:recordMapping
recordProjection, sx:recordProjection
recordReader, sx:recordReader
recordRestriction, sx:recordRestriction
recordStream, sx:recordStream
recordSubtreeMap, sx:recordSubtreeMap
recordTee, sx:recordTee
recordTest, sx:recordTest
recordValidator, sx:recordValidator, msv:recordValidator
recordWriter, sx:recordWriter
regexFieldCriteria, sx:regexFieldCriteria
removeEmptyAttributes, sx:removeEmptyAttributes
removeEmptyElementFilter, sx:removeEmptyElementFilter, sx:removeEmptyElementFilter
removeEmptyElements, sx:removeEmptyElements
reorderRecords, sx:reorderRecords
repeatDelimiter, sx:repeatDelimiter
repeatingField, sx:repeatingField, sx:repeatingNamedField
repeatingGroup, sx:nonrepeatingGroup, sx:repeatingGroup
repeatingSegment, sx:repeatingSegment
replace, sx:replace
replaceRecord, sx:replaceRecord
replaceRecordFilter, sx:replaceRecordFilter
resources, sx:resources
restrictField, sx:restrictField
restriction, sx:restriction
restrictRecordFilter, sx:restrictRecordFilter
restrictRecordType, sx:restrictRecordType, sx:restrictRecordType
runService, sx:runService

### S

saxFilter, sx:saxFilter
saxReader, sx:saxReader
saxSink, sx:saxSink
saxSource, sx:saxSource
schemaValidator, msv:schemaValidator
segmentComposition, sx:segmentConcatenation
segmentDelimiter, sx:segmentDelimiter
segmentMapping, sx:segmentMapping
sender, jm:sender
sendMail, jm:sendMail
separator, sx:separator
serialize, sx:serialize
service, sx:service
shredXml, sx:shredXml
sizeFlatFileSignature, sx:sizeFlatFileSignature
sort, sx:sort
sqlBatchWriter, sx:sqlBatchWriter
sqlCommand, sx:sqlCommand
sqlConnectionPool, sx:sqlConnectionPool
sqlPrepare, sx:sqlPrepare
sqlQuery, sx:sqlQuery
sqlReader, sx:sqlReader
sqlUpdate, sx:sqlUpdate
sqlUpdateChoice, sx:sqlUpdateChoice
sqlUpdateDatabase, sx:sqlUpdateDatabase
sqlUpdateDetail, sx:sqlUpdateDetail
sqlWriter, sx:sqlWriter
streamSink, sx:streamSink
streamSource, sx:streamSource
string, sx:string
stringable, sx:stringable
stringSource, sx:stringSource
style, sx:style
subfieldDelimiter, sx:subfieldDelimiter
subrecordMapping, sx:subrecordMapping
subtreeFieldMap, sx:subtreeFieldMap
subtreeFilter, sx:subtreeFilter
subtreeRecordMap, sx:subtreeRecordMap
subtreeRecordReader, sx:subtreeRecordReader
sx:defaultFieldMapping, sx:defaultFieldMapping
sx:escapeSubstitutions, sx:escapeSubstitutions
systemProperty, sx:systemProperty

### T

tagDelimiter, sx:tagDelimiter
tagTee, sx:tagTee
task, sx:task
toString, sx:toString
transform, sx:transform
transformerSettings, sx:xsltConfiguration
transformRecord, sx:transformRecord

### U

unmatchedRecord, sx:unmatchedRecord
urlSource, sx:urlSource

### V

validateField, sx:validateField
validateRecord, sx:validateRecord
validator, sx:validator
valueRestriction, sx:valueRestriction
vbsFlatRecordType, sx:vbsFlatRecordType

### W

when, sx:when
whitespaceSeparator, sx:whitespaceSeparator
withParameters, sx:withParameters
wrap, sx:wrap
writeRecords, sx:writeRecords

### X

xmlRecordReader, sx:xmlRecordReader
xquery, saxon:xquery
xslt, sx:xslt
xsltSerializer, sx:xmlEmitter, sx:xsltSerializer