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.


Table of Contents

I. Configuration Elements
sx:cacheSettings — Cache settings
sx:escapeSubstitutions — Define escape rules for special characters in evaluations of SubstitutionExpr
sx:escapeVariables — Deprecated in 1.0, replaced by sx:escapeSubstitutions
sx:expiryOptions — Expiry options
sx:patternMatcher — Regular expression pattern matcher
sx:xsltConfiguration — XSLT configuration
II. Common Elements
id ref attributes — Common id ref attributes for referencing top level elements
sx:defaultValue — Defines a default value for a parameter or field
sx:documentation — To annotate scripts with human readable documentation. sx:documentation elements may appear anywhere in resources scripts, and are ignored by the processor.
sx:parameter — Parameter
sx:property — Property
sx:systemProperty — System property
sx:validator — Abstract element standing for a validator
sx:removeEmptyElementFilter — Deprecated, aliased to sx:removeEmptyElements
sx:withParameters — Declare the parameters that need to be passed to an XSLT processor
III. Resources, Service and Task Elements
sx:choose — Choose from alternatives with XPATH test conditions
sx:include — Include another resources script
sx:onError — Catches an exception raised by a sx:task element, to be revisited
sx:raiseError — Raises an exception inside an sx:onError, to be revisited
sx:resources — The root element of a resources script
sx:runService — Runs another service from within a resources script
sx:service — Service
sx:task — Abstract element standing for a task
IV. String Elements
sx:concat — Common attributes for elements
sx:convertDate — Convert date
sx:convertToDateTime — Convert to datetime
sx:currentDate — Current date
sx:currentDateTime — Current datetime
sx:currentTime — Current time
sx:date — Deprecated, replaced by sx:currentDateTime and sx:formatDateTime
sx:escapeMarkup — Evaluate children as a string, escaping XML tags
sx:findAndReplace — Find and replace in a string using regular expressions
sx:formatDateTime — Format datetime
sx:lineNumber — Output current line number
sx:preserveMarkup — Evaluate children as a string, preserving XML tags without escaping them
sx:replace — Deprecated, replaced in 0.9.2 by sx:findAndReplace
sx:string — Abstract element standing for any string element, e.g. sx:toString
sx:stringable — Abstract element standing for any element that can render itself as a string, e.g. sx:transform
sx:toString — Ouput a string
V. Stream Source and Sink Elements
sx:command — Command
sx:commandArg — Command argument
sx:commandSink — Command sink
sx:commandSource — Command source
sx:defaultStreamSink — Default stream sink
sx:defaultStreamSource — Default stream source
sx:envVariable — Environment variable
sx:fileSink — File sink
sx:fileSource — File source
sx:inlineSource — Inline source
sx:streamSink — Abstract element standing for a stream sink
sx:streamSource — Abstract element standing for a stream source
sx:stringSource — String source
sx:urlSource — URL source
VI. XML Content Producing and Transforming Elements
sx:assert — Assert
sx:attribute — Add an attribute to wrapping elements inside a sx:wrap element
sx:batchedSerializer — Batched serializer
sx:cachedContent — Cached content
sx:content — Abstract element standing for XML content
sx:customEmitter — Deprecated, aliased to sx:customSerializer
sx:customSerializer — Custom serializer
sx:document — XML document
sx:documentSequence — Document sequence
sx:dynamicContent — Dynamic content
sx:saxSink — Abstract element standing for a sink of SAX events
sx:emptyDocument — Empty XML document
sx:filter — Deprecated in 1.0.0, use sx:content instead
sx:key — Key for XML content
sx:keyField — Key field
sx:outputProperty — Output property for XML serializer
sx:processSubtree — Perform tasks on subtrees of an XML document
sx:recordContent — XML content from records
sx:removeEmptyAttributes — Remove empty attributes from XML elements
sx:removeEmptyElementFilter — Deprecated, aliased to sx:removeEmptyElements
sx:removeEmptyElements — Remove empty elements from XML content
sx:saxFilter — SAX filter
sx:saxReader — SAX reader
sx:saxSource — Abstract element standing for a source of SAX events
sx:serialize — Serialize XML content
sx:style — Deprecated, aliased to sx:xslt
sx:tagTee — Splits the stream of SAX events
sx:subtreeFilter — Apply XML filters to subtrees of XML
sx:transform — Transform XML content
sx:wrap — Wrap XML content with surrounding elements
sx:xmlEmitter — Deprecated, aliased to sx:xsltSerializer
sx:xslt — XSLT stylesheet
sx:xsltSerializer — XML serializer of XSLT processor
VII. Record Readers, Writers and Filters
sx:aggregateRecords — Deprecated, replaced by sx:combineRecords
sx:and — And operator
sx:batchRecords — Batch records
sx:batchedRecordWriter — Write records in batches
sx:combineRecords — Compose a composite record
sx:composeRecord — Deprecated in version 1.1.2, aliased to sx:combineRecords
sx:customRecordFilter — Custom record filter
sx:customRecordReader — Custom record reader
sx:decomposeRecord — Deprecated in version 1.1.2, aliased to sx:decomposeRecord
sx:discard — Discard a record
sx:discardFilter — Deprecated, replaced by sx:discardHandler
sx:discardHandler — Discard record handler
sx:fieldRestriction — Restrict field
sx:fieldValidator — Field validator
sx:fileFilter — File filter
sx:log — Log
sx:modifyRecord — Modify a record
sx:newField — Add a field to a record
sx:newRecord — Create a new record
sx:or — Or condition
sx:parameterReader — Read parameters as record
sx:processRecord — Perform tasks on individual record
sx:processRecordFilter — Deprecated, replaced by sx:processRecord
sx:processRecords — Deprecated, aliased to sx:recordStream
sx:regexFieldCriteria — Deprecated, aliased to sx:fieldRestriction
sx:quoteSymbol — Quote symbol
sx:recordAggregator — Deprecated, replaced by sx:combineRecords
sx:recordProjection — Project a subset of fields
sx:recordFilter — Abstract element standing for a record filter
sx:recordReader — Abstract element standing for a record reader
sx:recordRestriction — Restriction on a record
sx:recordWriter — Abstract element standing for a record writer
sx:recordStream — A record stream
sx:recordTee — Split record stream
sx:recordTest — Deprecated, replaced by sx:recordRestriction
sx:recordValidator — Validate record
sx:replaceRecord — Replace record with one or more other records
sx:replaceRecordFilter — Deprecated in version 1.0.2, replaced by sx:replaceRecord
sx:restrictRecordType — Deprecated, aliased to sx:recordRestriction
sx:restriction — Abstract element standing for a restriction
sx:restrictField — Deprecated, aliased to sx:fieldRestriction
sx:restrictRecordFilter — Restrict records
sx:restrictRecordType — Deprecated, aliased to sx:recordRestriction
sx:splitRecord — Decompose a composite record into its constituent subrecords
sx:directoryReader — Read a directory
sx:subtreeRecordReader — Read subtrees of XML document as records
sx:validateField — Deprecated in version 1.0, replaced by sx:fieldValidator
sx:validateRecord — Deprecated in version 1.0, replaced by sx:recordValidator
sx:valueRestriction — Restrict value
sx:writeRecords — Deprecated, replaced by sx:recordStream
sx:xmlRecordReader — Deprecated in version 1.0, replaced by sx:subtreeRecordReader
VIII. Record Mapping Elements
Grouping Element — Grouping Element
Literal Element — Literal Element
sx:cdata — CDATA output
sx:defaultFieldAttributeMap — Default field attribute map
sx:defaultFieldElementMap — Default field element map
sx:defaultFieldMapping — Deprecated in version 1.0, aliased to sx:defaultFieldElementMap
sx:documentFragment — Deprecated, replaced by sx:nestedContent
sx:elementMap — Element map
sx:fieldAttributeMap — Map field to attribute
sx:fieldElementMap — Map field to element
sx:fieldElementSequenceMap — Map field to element sequence
sx:groupBy — Group by fields
sx:groupChoice — Choose one of another of alternative groupings
sx:innerGroup — Output inner grouping elements
sx:insertContent — Deprecated in 0.9.3, replaced by sx:nestedContent
sx:mapXml — Abstract element standing for any element that maps records to XML
sx:nestedContent — Nested XML content
sx:onRecord — On record event
sx:outerGroup — Output outer grouping elements
sx:reorderRecords — Reorder records within a group
sx:recordMapping — Mapping of records to XML
sx:recordSubtreeMap — Deprecated, replaced by sx:transformRecord
sx:segmentMapping — Deprecated in 0.9.3, replaced by sx:subrecordMapping
sx:subrecordMapping — Map subrecords of a composite record to XML
sx:sort — Abstract element standing for a sort element
sx:transformRecord — Transform record to XML
IX. Inverse Record Mapping Elements
sx:documentSubtreeMap — Deprecated, aliased to sx:onSubtree
sx:flattenSubtree — Flatten XML subtree
sx:inverseRecordMapping — Map XML to records
sx:onSubtree — On subtree event
sx:shredXml — Abstract element standing for any element that maps XML to records
sx:subtreeFieldMap — Map from subtree to field
sx:subtreeRecordMap — Deprecated, aliased to sx:flattenSubtree
X. Flat File Elements
Flat File Options - Attributes — Flat file options
Flat File Options - Elements — Flat File Options
sx:annotationRecord — Annotation record
sx:binaryField — Binary field
sx:combinePhysicalRecords — Combine multiple physical records into a composite logical record
sx:commentStarter
sx:commentSymbol — Deprecated, aliased to sx:commentStarter
sx:compositeFlatRecordType — Composite flat record type
sx:crcFlatFileSignature — Deprecated, replaced by sx:flatFileSignature with method="crc"
sx:delimitedField — Delimited field
sx:delimitedNamedField — Delimited name/value pair
sx:fieldDelimiter — Field delimiter
sx:flatFile — Flat file
sx:flatFileBody — Flat file body
sx:flatFileSignature — Flat file signature
sx:flatFileHeader — Flat file header
sx:flatFileReader — Read flat file
sx:flatRecordField — Abstract element standing for any flat record field
sx:flatRecordType — Flat record type
sx:flatRecordTypeChoice — Choose from alternative record definitions
sx:flatFileTrailer — Flat file trailer
sx:flatFileWriter — Abstract element standing for any flat file writer
sx:integerField — Integer field
sx:mergePhysicalSegments — Merges a number of physical segments into one logical record.
sx:metaRecord — Meta record
sx:nameDelimiter — Separate a field name and value
sx:packedDecimalField — Packed decimal field
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:overpunchField — Overpunch field
sx:positionalField — Positional field
sx:recordComposition — Deprecated in version 1.1.2, aliased to sx:combinePhysicalRecords
sx:recordDelimiter — Separate records
sx:repeatDelimiter — Separate repeating groups within a segment
sx:repeatingField — Field repeats
sx:repeatingNamedField — Deprecated, replaced by sx:repeatingField
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:segmentComposition — Deprecated in 1.1.2, aliased to sx:mergePhysicalSegments
sx:segmentDelimiter — Separate a record into segments containing repeating groups
sx:separator — Abstract element standing for any separator
sx:sizeFlatFileSignature — Deprecated, replaced by sx:flatFileSignature with method="size"
sx:subfieldDelimiter — Separate values within a field
sx:tagDelimiter — Deprecated, aliased to sx:nameDelimiter
sx:taggedDelimitedField — Deprecated, aliased to sx:delimitedNamedField
sx:taggedFlatRecordField — Deprecated, aliased to sx:flatRecordField
sx:vbsFlatRecordType — Variable Block Segment (VBS) record type
sx:whitespaceSeparator — Separate fields with whitespace
XI. SQL Elements
sx:customJdbcConnectionPool — Custom JDBC connection pool
sx:jdbcConnectionPool — Abstract element standing for a JDBC connection pool
sx:sqlBatchWriter — SQL batch writer
sx:sqlCommand — Execute a command on the server after opening a connection
sx:sqlConnectionPool — SQL connection pool
sx:sqlPrepare — Prepare SQL statement
sx:sqlQuery — SQL query
sx:sqlReader — SQL record reader
sx:sqlUpdate — Update or insert rows
sx:sqlUpdateChoice — Update based on results of query
sx:sqlUpdateDatabase — Abstract element standing for a SQL update
sx:sqlUpdateDetail — Update detail rows in one transaction
sx:sqlWriter — SQL record writer
XII. SUN Multi Schema Validator Extension
msv:msvFilter — Deprecated, replaced by msv:schemaValidator
msv:msvRecordFilter — Deprecated, replaced by msv:recordValidator
msv:recordValidator — Validate record with XML schema
msv:schemaValidator — Validate XML with schema
XIII. Apache FOP Extension
fop:foEmitter — Deprecated, aliased to fop:foSerializer
fop:foSerializer — Apache FOP xsl/fo serializer
XIV. Java Mail Extension
jm:attachment — Attachment
jm:mailAccount — Mail account
jm:message — Message
jm:part — MIME part
jm:sender — Sender
jm:sendMail — Send mail
XV. EDT FTP Extension
edt:ftpClient — FTP client
edt:ftpDirectoryReader — FTP directory reader
edt:ftpSink — FTP sink
edt:ftpSource — FTP source
XVI. Saxon XQuery Extension
saxon:xquery — Saxon 9 xquery processor
Glossary
A. Data Type Mappings
B. Deprecated Elements and Attributes
Index

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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
escapeNotrue|falsetrue if a character should be escaped, false otherwise. Defaults to true
characterNoCharacterThe character to optionally enclose field values. Defaults to the double quotation mark.
escapeCharacterNoCharacterThe escape character used to escape the quote symbol, e.g. the backslash ('\') or the quote symbol itself.
escapeSequenceNoStringThe 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;"/>



Name

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


Name

sx:expiryOptions — Expiry options

Attributes

NameRequiredValueDescription
revalidateNostring 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

NameRequiredValueDescription
classYesJava classAn implementation of the com.servingxml.components.regex.PatternMatcher interface.

Content

None.


Name

sx:xsltConfiguration — XSLT configuration

Attributes

NameRequiredValueDescription
versionNoXSLT versionThe 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

NameRequiredValueDescription
idNoQNameAn identifier of an element instance. This id is the target for references by ref attributes.
refNoQNameThis 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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
valueNoSubstitutionExprA string value that may contain a parameter inside curly braces, e.g. "{$my-param}.xml".
selectNoXPath expressionAn XPath expression evaluated against an sx:content substitutable child element, or, if none, 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

Examples

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


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



Name

sx:documentation — To annotate scripts with human readable documentation. sx:documentation elements may appear anywhere in resources scripts, and are ignored by the processor.

Attributes

None

Content

Human readable documentation.


Name

sx:parameter — Parameter

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
nameYesQNameThe name of the parameter.
valueNoSubstitutionExprA string value that may reference a parameter or field name inside curly braces, e.g. "{$my-param}.xml".
selectNoXPath expressionAn XPath expression evaluated against an sx:content substitutable child element, or, if none, the default XML document.
typeNoXML Schema typesThe 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


Name

sx:property — Property

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
keyYesStringDeprecated, use name instead.
nameYesStringThe custom property name.
valueYesStringThe custom property value.

Content

None.


Name

sx:systemProperty — System property

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
keyYesStringDeprecated, use name instead.
nameYesStringThe system property name.
valueYesStringThe value of a system property.

Content

None.


Name

sx:validator — Abstract element standing for a validator

Attributes

NameRequiredValueDescription
refYesQNameThis 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


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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
parametersYesNameTest listA 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.
exceptParametersNoNameTest listA 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.

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

Description

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

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

NameRequiredValueDescription
testYesXPath Boolean ExpressionThe boolean expression to evaluate.

Content

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


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:


Name

sx:include — Include another resources script

Attributes

NameRequiredValueDescription
hrefYesURIA URI identifying a resources script.

Content

None.


Name

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

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.

Content

One or more action elements from the following list.

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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.

Content

Description

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

See also


Name

sx:resources — The root element of a resources script

Attributes

NameRequiredValueDescription
nsNoURIThe 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


Name

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

  └ sx:task, sx:stringable

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
serviceYesSubstitutionExprAn expression that evaluates to a QName identifying a service.

Content

Description

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

See also


Name

sx:service — Service

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.

Content

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>



Name

sx:task — Abstract element standing for a task

Attributes

NameRequiredValueDescription
refYesQNameThis 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

String Elements


Name

sx:concat — Common attributes for elements

  └ sx:string, sx:stringable

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
separatorNocharA separator to separate each string value in the content.
quoteSymbolNocharA symbol to surround each string value.

Content

Any number of sx:stringable elements.

Description


Name

sx:convertDate — Convert date

  └ sx:string, sx:stringable

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
fromFormatYesStringThe format of the input string, which must must follow the syntax specified for the JDK SimpleDateFormat class.
toFormatNoStringThe 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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
formatYesStringThe format of the input string, which must must follow the syntax specified for the JDK SimpleDateFormat class.
inputTimezoneNoStringThe time zone for the input date. Defaults to the Java default time zone.
outputTimezoneNoStringThe 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

NameRequiredValueDescription
idref-attributesNo 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

NameRequiredValueDescription
idref-attributesNo 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

NameRequiredValueDescription
idref-attributesNo 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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
formatNoStringThe 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

NameRequiredValueDescription
idref-attributesNo 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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
searchForYesRegexMatch sub-sequences of the input string against this pattern.
replaceWithYesStringReplace 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.
caseSensitiveNotrue | falseDefaults to true .
useRegexNotrue | falseDefaults 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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
formatNoStringThe 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

NameRequiredValueDescription
idref-attributesNo 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

NameRequiredValueDescription
idref-attributesNo 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

NameRequiredValueDescription
refYesQNameThis 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.


Name

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

Attributes

NameRequiredValueDescription
refYesQNameThis 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.


Name

sx:toString — Ouput a string

  └ sx:string, sx:stringable

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
selectNoXPath expressionAn XPath expression evaluated against an sx:content substitutable child element, or, if none, the default XML document.
valueNoSubstitutionExprA string value that may contain one or more parameters enclosed in curly braces, e.g. "{$my-param}.xml".
separatorNocharA separator to separate the pieces if the expression resolves to multiple values.
quoteSymbolNocharA 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.


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.


Name

sx:commandSink — Command sink

  └ sx:streamSink

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
directoryNoSubstitutionExprOptionally, the current working directory.
encodingNoStringA charset name. Defaults to the platform's default charset.

Content

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


Name

sx:commandSource — Command source

  └ sx:streamSource

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
directoryNoSubstitutionExprOptionally, the current working directory.
encodingNoStringA charset name. Defaults to the platform's default charset.

Content

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


Name

sx:defaultStreamSink — Default stream sink

  └ sx:streamSink

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
encodingNoStringA 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


Name

sx:defaultStreamSource — Default stream source

  └ sx:streamSource

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
encodingNoStringA 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


Name

sx:envVariable — Environment variable

Attributes

None

Content

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


Name

sx:fileSink — File sink

  └ sx:streamSink

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
directoryNoSubstitutionExprAn optional directory name.
fileYesSubstitutionExprThe name of the output file, may contain parameters in the form {$myParam}.
encodingNoStringA 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


Name

sx:fileSource — File source

  └ sx:streamSource

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
directoryNoSubstitutionExprAn optional directory name.
fileYesSubstitutionExprThe name of the input file, may contain parameters in the form {$myParam}.
encodingNoStringA 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


Name

sx:inlineSource — Inline source

  └ sx:streamSource

Attributes

NameRequiredValueDescription
idref-attributesNo 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


Name

sx:streamSink — Abstract element standing for a stream sink

Attributes

NameRequiredValueDescription
refYesQNameThis 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


Name

sx:streamSource — Abstract element standing for a stream source

Attributes

NameRequiredValueDescription
refNoQNameThis 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


Name

sx:stringSource — String source

  └ sx:streamSource

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.

Content

None.


Name

sx:urlSource — URL source

  └ sx:streamSource

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
urlYesSubstitutionExprThe name of the input url, may contain parameters in the form {$myParam}.
encodingNoStringA 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

XML Content Producing and Transforming Elements


Name

sx:assert — Assert

  └ sx:content, sx:validator

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
testYesXPath Boolean ExpressionAn 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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
attributeYesSubstitutionExpr 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.
selectNoXPath expressionAn XPath expression evaluated against an sx:content substitutable child element, or, if none, the default XML document.
valueNoSubstitutionExprExpress 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


Name

sx:batchedSerializer — Batched serializer

  └ sx:saxSink

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
pathYesSAXPath A SAXPath expression, which identifies subtrees.
batchSizeYesInteger The number of subtrees in a batch.
maxFilesNoInteger The maximum number of batch files.

Content

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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.

Content

Content

Description

This element permits caching of XML content.


Name

sx:content — Abstract element standing for XML content

Attributes

NameRequiredValueDescription

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>



Name

sx:customEmitter — Deprecated, aliased to sx:customSerializer

  └ sx:saxSink


Name

sx:customSerializer — Custom serializer

  └ sx:saxSink

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
classYesJava ClassThe name of a Java class that implements com.servingxml.io.saxsink.SaxSink.

Content

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

NameRequiredValueDescription
idref-attributesNo 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>



Name

sx:documentSequence — Document sequence

  └ sx:content

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
wrapWithNoSubstitutionExprWrap all documents in the sequence with this root element.

Content

Either

or

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


Name

sx:dynamicContent — Dynamic content

  └ sx:content

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
classYesJava ClassThe name of a Java class that implements com.servingxml.components.content.dynamic.RequestHandler and, optionally, com.servingxml.components.content.dynamic.Cacheable.

Content

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>



Name

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

Attributes

NameRequiredValueDescription
refYesQNameThis 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.


Name

sx:emptyDocument — Empty XML document

  └ sx:content

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.

Content

None.

Examples


Name

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

Attributes

NameRequiredValueDescription

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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.

Content

Examples

See sx:dynamicContent.


Name

sx:keyField — Key field

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
nameNoNameReference 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.


Name

sx:outputProperty — Output property for XML serializer

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
nameYesStringThe output property name.
valueYesSubstitutionExprThe 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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
pathYesSAXPath A SAXPath expression.

Content

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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
nameNoQNameThe 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>



Name

sx:removeEmptyAttributes — Remove empty attributes from XML elements

  └ sx:content

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
elementsYesNameTest listA 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.
exceptElementsNoNameTest listA 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.
attributesYesNameTest listA 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.
exceptAttributesNoNameTest listA 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> 



Name

sx:removeEmptyElementFilter — Deprecated, aliased to sx:removeEmptyElements

  └ sx:content


Name

sx:removeEmptyElements — Remove empty elements from XML content

  └ sx:content

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
elementsYesNameTest listA 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.
exceptNoNameTest listDeprecated, use exceptElements instead.
exceptElementsNoNameTest listA 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> 



Name

sx:saxFilter — SAX filter

  └ sx:content

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
classYesJava ClassThe name of a Java class that implements org.xml.sax.XMLFilter.

Content

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>


Name

sx:saxReader — SAX reader

  └ sx:saxSource

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.
classYesJava ClassThe name of a Java class that implements org.xml.sax.XMLReader.
systemIdNoSubstitutionExprThe system id passed to the parse method of the reader. Defaults to an empty string.

Content

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

NameRequiredValueDescription
idref-attributesNo 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


Name

sx:serialize — Serialize XML content

  └ sx:task, sx:stringable

Attributes

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.

Content

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


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

NameRequiredValueDescription
idref-attributesNo Common id ref attributes.

Content

See also


    Name

    sx:subtreeFilter — Apply XML filters to subtrees of XML

      └ sx:content

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    pathYesSAXPath A SAXPath expression.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    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


    Name

    sx:wrap — Wrap XML content with surrounding elements

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

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    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


    Name

    sx:xmlEmitter — Deprecated, aliased to sx:xsltSerializer

      └ sx:saxSink


    Name

    sx:xslt — XSLT stylesheet

      └ sx:content

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    documentBaseNoSubstitutionExprThis 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

    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>
    


    Name

    sx:xsltSerializer — XML serializer of XSLT processor

      └ sx:saxSink

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    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:combineRecords


    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> 
    


    Name

    sx:batchRecords — Batch records

      └ sx:recordFilter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    batchSizeYesNumber

    The batch size.

    recordTypeNoNameTestCount 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    batchSizeYesNumber

    The batch size.

    recordTypeNoNameTestCount 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:combineRecords — Compose a composite record

      └ sx:recordFilter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeYesSubstitutionExprThe name of the composite record type.
    repeatingGroupYesQNameThe name of the field containing a list of records.
    startTestNoXPath Boolean ExprXPath boolean expression to test for start of grouping. Defaults to true
    endTestNoXPath Boolean ExprXPath boolean expression to test for end of grouping. Defaults to startTest.
    compositeRecordTypeNoQNameDeprecated in version 0.9.5 - replaced by recordType attribute.
    repeatingGroupFieldNoQNameDeprecated in version 0.9.5 - replaced by repeatingGroup attribute.

    Content

    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",

    REMTEIREM
    REMAAAA
    REMBBB
    REMCCC

    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:combineRecords 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:combineRecords recordType="composite" repeatingGroup="detail"
                    startTest="sx:current/orderRemarks"
                    endTest="not(sx:current/orderRemarks)">
          <sx:newField name="remarks" select="detail/orderRemarks/REM"/>
        </sx:combineRecords>
    
    

    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


    Name

    sx:composeRecord — Deprecated in version 1.1.2, aliased to sx:combineRecords

      └ sx:recordFilter


    Name

    sx:customRecordFilter — Custom record filter

      └ sx:recordFilter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    classYesJava ClassThe name of a Java class that implements com.servingxml.components.recordio.RecordFilter

    Content

    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);
      }
    }
    


    Name

    sx:customRecordReader — Custom record reader

      └ sx:recordFilter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    classYesJava ClassThe name of a Java class that implements com.servingxml.components.recordio.RecordFilter

    Content

    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);
      }
    }                              
    


    Name

    sx:decomposeRecord — Deprecated in version 1.1.2, aliased to sx:decomposeRecord

      └ sx:recordFilter


    Name

    sx:discard — Discard a record

      └ sx:recordFilter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo 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.


    Name

    sx:discardFilter — Deprecated, replaced by sx:discardHandler

      └ sx:recordFilter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameApply discard handling to records of this type. Defaults to records of any type.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameApply discard handling to records of this type. Defaults to records of any type.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    fieldYesQNameThe name of the field.
    patternYesRegexThe regular expression to be tested against the value of the field.
    negateNotrue/falseReverses 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    fieldNameYesQNameThe name of the field to validate.
    messageYesSubstitutionExprA message indicating the error if validation fails.

    Content

    Description


    Name

    sx:fileFilter — File filter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    patternYesRegexThe regular expression to be tested against the file name.
    negateNotrue/falseReverses 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.


    Name

    sx:log — Log

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    messageNoSubstitutionExprA string value that may contain parameters inside curly braces, e.g. "{$message}".
    levelNoerror/warning/notice/traceDefaults 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


    Name

    sx:modifyRecord — Modify a record

      └ sx:recordFilter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    newRecordTypeNoQNameThe record type name of the modified record. Defaults to the record type name of the original record.

    Content

    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.


    Name

    sx:newField — Add a field to a record

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    nameYesQNameThe name of the field.
    valueNoSubstitutionExprA string value that may reference a parameter or field inside curly braces, e.g. "{$my-param}.xml".
    selectNoXPath expressionAn XPath expression evaluated against an sx:content substitutable child element, or, if none, the XML representation of the record.
    matchYesRegexThe regular expression to be tested against the value of the field.

    Content

    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.


    Name

    sx:newRecord — Create a new record

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameThe type of the new record. Defaults to the type of the original record.
    fieldsNoNameTest listA 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 "*".
    exceptNoQName list(deprecated, use exceptFields instead)
    exceptFieldsNoQName listA 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

    Description

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


    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> 
    


    Name

    sx:parameterReader — Read parameters as record

      └ sx:recordReader

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameThe 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameTask records of this type. Defaults to records of any type.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    valueNoCharacterDeprecated - replaced by character in 0.9.1.
    characterNoCharacterThe character to optionally enclose field values. Defaults to the double quotation mark.
    escapedByNoCharacterDeprecated - replaced by escapeCharacter in 0.9.1.
    escapeCharacterNoCharacterThe escape character used to escape the quote symbol, e.g. the backslash ('\') or the quote symbol itself.
    escapeWithNoStringDeprecated - replaced by escapeSequence in 0.9.1.
    escapeSequenceNoStringThe 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;"/>
    
    


    Name

    sx:recordAggregator — Deprecated, replaced by sx:combineRecords


    Name

    sx:recordProjection — Project a subset of fields

      └ sx:recordFilter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameProduce a subset of fields for records of this type, or for all records if no type specified.
    newRecordTypeNoQNameThe type of the new record. Defaults to the type of the input record.
    fieldsNoNameTest listA 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 "*".
    exceptFieldsNoQName listA 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

    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


    Name

    sx:recordFilter — Abstract element standing for a record filter

    Attributes

    NameRequiredValueDescription
    refYesQNameThis 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


    Name

    sx:recordReader — Abstract element standing for a record reader

    Attributes

    NameRequiredValueDescription
    refYesQNameThis 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.


    Name

    sx:recordRestriction — Restriction on a record

      └ sx:restriction

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameThe name of the record type.
    testNoXPathAn XPath boolean expression evaluated against the XML representation of the record.
    negateNotrue/falseReverses 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

    NameRequiredValueDescription
    refYesQNameThis 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.


    Name

    sx:recordStream — A record stream

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

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameValidate records of this type.
    messageNoSubstitutionExprA message indicating the error if validation fails.

    Content

    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>
    


    Name

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

      └ sx:recordFilter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameApply changes to records of this type. Defaults to records of any type.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameApply changes to records of this type. Defaults to records of any type.

    Content

    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

    NameRequiredValueDescription
    refYesQNameThis 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


    Name

    sx:restrictField — Deprecated, aliased to sx:fieldRestriction


    Name

    sx:restrictRecordFilter — Restrict records

      └ sx:recordFilter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    operatorNoand/orDeprecated. 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

    Description

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

    See also

    Name

    sx:unmatchedRecord — A record stream

    Attributes

    None

    Content

    Description

    Handles unmatched records.


    Name

    sx:restrictRecordType — Deprecated, aliased to sx:recordRestriction


    Name

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

      └ sx:recordFilter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeYesQNameDecompose records of this type.
    repeatingGroupYesQNameDecompose records of the specified type on this repeating group field.
    subrecordTypeNoSubstitutionExprThe type of the decomposed records. Defaults to the record type of the subrecords in the repeating group.
    compositeRecordTypeNoQNameDeprecated in version 0.9.5 - replaced by recordType attribute.
    repeatingGroupFieldNoQNameDeprecated in version 0.9.5 - replaced by repeatingGroup attribute.
    ofRecordTypeNoQNameDeprecated - use recordType instead.
    onFieldNoQNameDeprecated - use repeatingGroup instead.

    Content

    Description

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


    Name

    sx:directoryReader — Read a directory

      └ sx:recordReader

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recurseNotrue|falseSet to "true" to recurse through a directory tree, "false" otherwise. Defaults to "false." (For backwards compatability, yes/no is also supported.)
    maxItemsNoNumberThe maximum number of directory items to read.
    directoryYesSubstitutionExprThe root directory.

    Content

    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:subtreeRecordReader — Read subtrees of XML document as records

      └ sx:recordReader

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    fieldNameYesQNameThe name of the field to validate.
    messageYesSubstitutionExprA message indicating the error if validation fails.

    Content

    Description


    Name

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

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameValidate records of this type.
    messageNoSubstitutionExprA message indicating the error if validation fails.

    Content

    Description


    Name

    sx:valueRestriction — Restrict value

      └ sx:restriction

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    patternYesRegexThe 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.


    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:

    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:


    Name

    sx:cdata — CDATA output

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo 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.


    Name

    sx:defaultFieldAttributeMap — Default field attribute map

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    fieldsYesNameTest listA 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.
    exceptFieldsNoQName listA 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


    Name

    sx:defaultFieldElementMap — Default field element map

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    fieldsYesNameTest listA 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.
    exceptNoQName listDeprecated, use exceptFields instead.
    exceptFieldsNoQName listA 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


    Name

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

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    fieldsYesNameTest listA 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.
    exceptNoQName listDeprecated, use exceptFields instead.
    exceptFieldsNoQName listA 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


    Name

    sx:documentFragment — Deprecated, replaced by sx:nestedContent

      └ sx:mapXml


    Name

    sx:elementMap — Element map

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    elementYesSubstitutionExpr 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.


    Name

    sx:fieldAttributeMap — Map field to attribute

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    attributeYesSubstitutionExpr 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.
    fieldNoQNameMap this field's value to the attribute value.
    selectNoXPath expressionApply 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.
    valueNoSubstitutionExprExpress 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.


    Name

    sx:fieldElementMap — Map field to element

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    elementYesSubstitutionExpr 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.
    matchNoXSLT patternDefine 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 "/*"
    selectNoXPath expressionApply 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.
    valueNoSubstitutionExprExpress the element value as a literal value, which may contain parameter names and field names enclosed in curly braces.
    fieldNoQNameMap 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.


    Name

    sx:fieldElementSequenceMap — Map field to element sequence

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    elementYesSubstitutionExpr 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.
    matchNoXSLT patternDefine 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 "/*"
    selectNoXPath expressionApply 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.
    valueNoSubstitutionExprExpress the element value as a literal value, which may contain parameter names and field names enclosed in curly braces.
    fieldNoQNameMap 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.

    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>
    
    


    Name

    sx:groupBy — Group by fields

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameGroup applies to fields of this record type.
    fieldsYesQNameA space separated list of fields to group by.

    Content

    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>
    
    


    Name

    sx:groupChoice — Choose one of another of alternative groupings

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    startTestNoXPath Boolean ExprXPath boolean expression to test for start of grouping. Defaults to true
    endTestNoXPath Boolean ExprXPath boolean expression to test for end of grouping. Defaults to startTest.

    Content

    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>
    
    


    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    None

    Description

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

    Examples


    Name

    sx:nestedContent — Nested XML content

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

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


    Name

    sx:onRecord — On record event

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQName Records with the specified recordType name will trigger this event processing. If no recordType attribute is specified, all records will be processed.
    testNoXPathAn XPath boolean expression evaluated against the XML representation of the record.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    startTestNoXPath Boolean ExprXPath boolean expression to test for start of grouping. Defaults to true
    endTestNoXPath Boolean ExprXPath boolean expression to test for end of grouping. Defaults to startTest.

    Content

    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.


    Name

    sx:reorderRecords — Reorder records within a group

      └ sx:sort

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypesYesQNameA space separated list of record types.

    Content

    None.


    Name

    sx:recordMapping — Mapping of records to XML

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content


    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    fieldYesQNameThe name of a repeating group field to map (deprecated in 0.9.5, use repeatingGroup instead.)
    repeatingGroupYesQNameThe name of a repeating group field to map.

    Content


    Name

    sx:sort — Abstract element standing for a sort element

    Attributes

    NameRequiredValueDescription

    Content

    None.

    Description

    This is an abstract element that represents sorting.

    Examples


    Name

    sx:transformRecord — Transform record to XML

      └ sx:mapXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo 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.

    Inverse Record Mapping Elements


    Name

    sx:documentSubtreeMap — Deprecated, aliased to sx:onSubtree

      └ sx:shredXml


    Name

    sx:flattenSubtree — Flatten XML subtree

      └ sx:shredXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    matchNoXSLT 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 "/*"
    recordTypeYesQName The record type of the output record.

    Content


    Name

    sx:inverseRecordMapping — Map XML to records

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    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.



    Name

    sx:onSubtree — On subtree event

      └ sx:shredXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    pathYesSAXPath A SAXPath expression.

    Content


    Name

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

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    None

    Description

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

    Examples


    Name

    sx:subtreeFieldMap — Map from subtree to field

      └ sx:shredXml

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    matchNoXSLT pattern Define a condition that an element in the XML fragment must satisfy in order to be selected by an XPath expression. Defaults to "/*"
    selectNoXPath 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.
    fieldYesQName 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.



    Name

    sx:subtreeRecordMap — Deprecated, aliased to sx:flattenSubtree

      └ sx:shredXml

    Flat File Elements


    Name

    Flat File Options - Attributes — Flat file options

    Attributes

    NameRequiredValueDescription
    flushRecordOnWriteNotrue|falseIndicates whether to flush the output stream every time a record is written. Defaults to false.
    trimNotrue|falseIndicates whether to trim leading and trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
    zeroBasedNotrue|falseIndicates whether position indexes are zero-based, defaults to false, by default position indexes are one-based.
    trimLeadingNotrue|falseIndicates whether to trim leading whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
    trimWithinQuotesNotrue|falseIndicates whether to trim quoted values of leading and trailing whitespace. Defaults to false.
    trimLeadingWithinQuotesNotrue|falseIndicates whether to trim quoted values of leading whitespace. Defaults to false .
    trimTrailingWithinQuotesNotrue|falseIndicates whether to trim quoted values of trailing whitespace. Defaults to false.
    trimQuotedNotrue|falseDeprecated as of version 1.1.0, use trimWithinQuotes instead.
    trimTrailingNotrue|falseIndicates whether to trim trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
    quoteNo"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.
    omitFinalFieldDelimiterNotrue|falseDefaults to true. (For backwards compatability, "yes"/"no" is also supported.)
    omitFinalRepeatDelimiterNotrue|falseDefaults to true (For backwards compatability, "yes"/"no" is also supported.)
    padCharacterNoCharacter The pad character used for formatting values into a field of fixed width, e.g., a space or zero.
    justifyNo"left","right", or "center"Indicates how to align the data within the field.
    lineDelimitedNotrue|falseIf 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.)
    countPositionsInBytesNotrue|falseIf 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.
    ignoreTrailingEmptyLinesNotrue|falseIf 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.)
    ignoreEmptyLinesNotrue|falseIf 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


    Name

    sx:annotationRecord — Annotation record

      └ sx:metaRecord

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    nameNoQNameThe name of the annotation record.
    widthYesnumberThe width of the annotation record.
    justifyNo"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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    nameYesQNameThe name of the field.
    labelNoSubstitutionExprA label for the field.
    startNonumberThe one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
    widthYesSubstitutionExprThe width of the field.

    Content

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

    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:combinePhysicalRecords — Combine multiple physical records into a composite logical record

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent
    startTestNoXPath Boolean ExprXPath boolean expression to test for start of grouping. Defaults to true
    endTestNoXPath Boolean ExprXPath boolean expression to test for end of grouping. Defaults to startTest.
    suppressRDWNotrue|falseSuppress the 4-byte record descriptor word (RDW) from the front of the logical record, defaults to false.

    Content


    Name

    sx:commentStarter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    valueYesStringThe 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent

    Content


    Name

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


    Name

    sx:delimitedField — Delimited field

      └ sx:flatRecordField

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    nameYesQNameThe name of the field.
    labelNoSubstitutionExprA label for the field.
    startNonumberThe one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
    trimNotrue|falseIndicates whether to trim leading and trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
    trimLeadingNotrue|falseIndicates whether to trim leading whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
    trimTrailingNotrue|falseIndicates whether to trim trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
    trimWithinQuotesNotrue|falseIndicates whether to trim quoted values of leading and trailing whitespace. Defaults to the setting at the record level.
    trimLeadingWithinQuotesNotrue|falseIndicates whether to trim quoted values of leading whitespace. Defaults to the setting at the record level.
    trimTrailingWithinQuotesNotrue|falseIndicates whether to trim quoted values of trailing whitespace. Defaults to the setting at the record level.
    quoteNo"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.
    alwaysQuoteNo"yes" or "no"Deprecated as of version 0.6.3, use quote="always" instead.
    minLengthNonumberIf the length of the field value is less than minLength, it will be padded with the padCharacter.
    maxLengthNonumberIf the length of the field is greater than maxValue, it will be truncated.
    justifyNo"left","right", or "center"The alignment rule used for formatting values into a field of fixed width. The default is "left".
    padCharacterNoCharacter The pad character used for formatting values into a field of fixed width, e.g., a space or zero. The default is a space.
    maxWidthNonumberThe 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.
    widthNonumberDeprecated, use maxWidth instead.
    omitFinalFieldDelimiterNotrue|falseDefaults 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.)

    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:flatRecordFieldsx:flatRecordField

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    labelNoSubstitutionExprA label for the field.
    startNonumberThe one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
    trimNotrue|falseIndicates whether to trim leading and trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
    trimLeadingNotrue|falseIndicates whether to trim leading whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
    trimTrailingNotrue|falseIndicates whether to trim trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.)
    minLengthNonumberIf the length of the field value is less than minLength, it will be padded with the padCharacter.
    maxLengthNonumberIf the length of the field is greater than maxValue, it will be truncated.
    justifyNo"left","right", or "center"The alignment rule used for formatting values into a field of fixed width. The default is "left".
    padCharacterNoCharacter The pad character used for formatting values into a field of fixed width, e.g., a space or zero. The default is a space.
    maxWidthNonumberThe 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.
    omitFinalFieldDelimiterNotrue|falseDefaults 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.

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    valueNoSubstitutionExprA string of one or more characters that indicates the end of a field.
    escapeCharacterNoCharacterAn 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent

    Content

    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


    Name

    sx:flatFileBody — Flat file body

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo 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>  
    
    


    Name

    sx:flatFileSignature — Flat file signature

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeYesQNameIdentifies a header or trailer record.
    fieldYesQNameIdentifies a field in a header or trailer record.
    methodYesstringMust be one of "crc", "size, or "custom".
    classNo (unless method is "custom")Java class nameThe name of a Java class that implements com.servingxml.components.flatfile.SignatureMethod
    validateNotrue|falseIndicates 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.


    Name

    sx:flatFileHeader — Flat file header

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    lineCountNoNumberThe number of lines in the header.
    recordLengthNoIntegerThe total length of the header records, including record delimiter, if any.

    Content

    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.



    Name

    sx:flatFileReader — Read flat file

      └ sx:recordReader

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent

    Content

    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>
    


    Name

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

    Attributes

    NameRequiredValueDescription
    refYesQNameThis 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


    Name

    sx:flatRecordType — Flat record type

      └ sx:metaRecord, sx:flatRecordField

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent
    nameNoSubstitutionExprA QName, or an expression that evaluates to a QName. Defaults to "record"
    recordLengthNoSubstitutionExprThe total length of the record, including record delimiter, if any.

    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.



    Name

    sx:flatRecordTypeChoice — Choose from alternative record definitions

      └ sx:metaRecord

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo 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.


    Name

    sx:flatFileTrailer — Flat file trailer

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    lineCountNoNumberThe number of lines in the trailer.
    recordLengthNoIntegerThe total length of the header records, including record delimiter, if any.

    Content

    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.



    Name

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

      └ sx:recordWriter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo 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


    Name

    sx:integerField — Integer field

      └ sx:flatRecordField

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    nameYesQNameThe name of the field.
    labelNoSubstitutionExprA label for the field.
    startNonumberThe one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
    widthYesnumberThe width of the field, which must be 1, 2, 4, or 8.
    bigEndianNotrue|falseSpecifies 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.


    Name

    sx:mergePhysicalSegments — Merges a number of physical segments into one logical record.

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent
    startTestNoXPath Boolean ExprXPath boolean expression to test for start of grouping. Defaults to true
    endTestNoXPath Boolean ExprXPath boolean expression to test for end of grouping. Defaults to startTest.
    segmentLengthNoSubstitutionExprThe length of the segment, may be read from a field in the header.
    suppressRDWNotrue|falseSuppress the 4-byte record descriptor word (RDW) from the front of the logical record, defaults to false.

    Content


    Name

    sx:metaRecord — Meta record

    Attributes

    NameRequiredValueDescription
    refYesQNameThis 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.


    Name

    sx:nameDelimiter — Separate a field name and value

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    valueNoSubstitutionExprThe 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    nameYesQNameThe name of the field.
    labelNoSubstitutionExprA label for the field.
    startNonumberThe one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
    widthNonumberThe width of the field. Defaults to the width corresponding to the digitCount.
    digitCountNonumberThe total number of digits in the packed decimal number.
    decimalPlacesNonumberThe 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.)

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent
    nameYesQNameThe name of the nonrepeating group field.
    startNonumberThe 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

    Description

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

    A nonrepeating group reads at most one record


    Name

    sx:overpunchField — Overpunch field

      └ sx:flatRecordField

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    nameYesQNameThe name of the field.
    labelNoSubstitutionExprA label for the field.
    startNonumberThe one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
    widthYesSubstitutionExprThe width of the field.
    decimalPlacesNonumberThe 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.)

    Examples

    Example 79. Overpunch field.

    The input consists of five overpunch fields with field width 5.

    
    11110111112222}2222J2222K12349
     
    

    The flat file definition is

    
      <sx:flatFile id="t:overpunch-file">
          <sx:recordDelimiter value="!"/>
        <sx:flatFileBody>
          <sx:flatRecordType>
            <sx:overpunchField name="value1" width="5" decimalPlaces="1"/>
            <sx:overpunchField name="value2" width="5" decimalPlaces="2"/>
            <sx:overpunchField name="value3" width="5" decimalPlaces="3"/>
            <sx:overpunchField name="value4" width="5" decimalPlaces="4"/>
            <sx:overpunchField name="value5" width="5" decimalPlaces="5"/>
          </sx:flatRecordType>
        </sx:flatFileBody>
      </sx:flatFile>
    
    

    The output with default record mapping is

    
    <document>
      <record>
        <value1>1111.0</value1>
        <value2>111.11</value2>
        <value3>-22.220</value3>
        <value4>-2.2221</value4>
        <value5>-0.22222</value5>
      </record>
    </document>
     
    


    Name

    sx:positionalField — Positional field

      └ sx:flatRecordField

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    nameYesQNameThe name of the field.
    labelNoSubstitutionExprA label for the field.
    startNonumberThe one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
    widthYesSubstitutionExprThe width of the field.
    trimNotrue|falseIndicates whether to trim leading and trailing whitespace. The default is true
    trimLeadingNotrue|falseIndicates whether to trim leading whitespace. The default is true
    trimTrailingNotrue|falseIndicates whether to trim trailing whitespace. The default is true
    justifyNo"left","right", or "center"The alignment rule used for formatting values into a field of fixed width. The default is "left".
    padCharacterNoCharacter 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.)

    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 — Deprecated in version 1.1.2, aliased to sx:combinePhysicalRecords

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent
    startTestNoXPath Boolean ExprXPath boolean expression to test for start of grouping. Defaults to true
    endTestNoXPath Boolean ExprXPath boolean expression to test for end of grouping. Defaults to startTest.
    suppressRDWNotrue|falseSuppress the 4-byte record descriptor word (RDW) from the front of the logical record, defaults to false.

    Content


    Name

    sx:recordDelimiter — Separate records

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    startNoSubstitutionExprA 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.
    endNoSubstitutionExprA string of one or more characters that identifies the end of a record.
    valueNoSubstitutionExprSame as end.
    continuationNoSubstitutionExprA string of one or more characters that indicates a continuation character, which allows a record to be extended onto the next line.
    continuationSequenceNoSubstitutionExprThe continuation + delimiter.
    escapeCharacterNoCharacterAn 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    startNoSubstitutionExprA string of one or more characters that identifies the beginning of a segment separated by start-end delimiters.
    endNoSubstitutionExprA string of one or more characters that identifies the end of a segment separated by start-end delimiters.
    valueNoSubstitutionExprA string of one or more characters that indicates the end of a segment within a repeating group.
    escapeCharacterNoCharacterAn 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent
    countNoSubstitutionExprA 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.

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent
    nameYesQNameThe name of the repeating group field.
    startNoSubstitutionExprThe (by default) one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field.
    countNoSubstitutionExprA fixed number of repeating records.

    Content

    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.


    Name

    sx:segmentComposition — Deprecated in 1.1.2, aliased to sx:mergePhysicalSegments

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent
    startTestNoXPath Boolean ExprXPath boolean expression to test for start of grouping. Defaults to true
    endTestNoXPath Boolean ExprXPath boolean expression to test for end of grouping. Defaults to startTest.
    suppressRDWNotrue|falseSuppress the 4-byte record descriptor word (RDW) from the front of the logical record, defaults to false.

    Content


    Name

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

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    startNoSubstitutionExprA string of one or more characters that identifies the beginning of a segment separated by start-end delimiters.
    endNoSubstitutionExprA string of one or more characters that identifies the end of a segment separated by start-end delimiters.
    valueNoSubstitutionExprA string of one or more characters that indicates the end of a segment.
    escapeCharacterNoCharacterAn 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

    NameRequiredValueDescription
    refNoQNameThis 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.


    Name

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


    Name

    sx:subfieldDelimiter — Separate values within a field

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    valueNoSubstitutionExprA string of one or more characters that indicates the end of a value in a multivalued field.
    escapeCharacterNoCharacterAn 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    flat file option attributesNo Standard flat file options, may be overriden in a descendent

    Content


    Name

    sx:whitespaceSeparator — Separate fields with whitespace

      └ sx:separator

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    None.

    Description

    The whitespace separator permits fields or records to be separated by one or more whitespace characters.

    SQL Elements


    Name

    sx:customJdbcConnectionPool — Custom JDBC connection pool

      └ sx:jdbcConnectionPool

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    classYesJava classThe name of a Java class that implements com.servingxml.components.sql.JdbcConnectionPool.

    Content

    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

    NameRequiredValueDescription
    refYesQNameThis 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


    Name

    sx:sqlBatchWriter — SQL batch writer

      └ sx:recordWriter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    batchSizeNoQNameThe batch size. Defaults to 100.

    Content

    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


    Name

    sx:sqlCommand — Execute a command on the server after opening a connection

    Attributes

    NameRequiredValueDescription
    idref-attributesNo 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    driverYesJava classThe class name of the JDBC driver.
    databaseUrlYesURLThe JDBC database URL.
    userNoStringThe database user name.
    passwordNoStringThe database password.
    minConnectionsNoNumberThe minimum number of connections to keep in the pool. The default is zero.
    maxConnectionsNoNumberThe maximum number of connections to keep in the pool. The default is any number.
    testStatementNoStringA 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

    NameRequiredValueDescription
    idref-attributesNo 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.



    Name

    sx:sqlQuery — SQL query

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameThe record type of the SQL query. Defaults to "record"
    trimNotrue|falseIndicates whether to trim both leading and trailing whitespace from all returned values. Defaults to false. (For backwards compatability, "yes"/"no" is also supported.)
    trimLeadingNotrue|falseIndicates whether to trim leading whitespace from all returned values. Defaults to false. (For backwards compatability, "yes"/"no" is also supported.)
    trimTrailingNotrue|falseIndicates 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.



    Name

    sx:sqlReader — SQL record reader

      └ sx:recordReader

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    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
    



    Name

    sx:sqlUpdate — Update or insert rows

      └ sx:sqlUpdateDatabase

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recordTypeNoQNameApply 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>
    
    


    Name

    sx:sqlUpdateChoice — Update based on results of query

      └ sx:sqlUpdateDatabase

    Attributes

    NameRequiredValueDescription
    idref-attributesNo 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


    Name

    sx:sqlUpdateDatabase — Abstract element standing for a SQL update

    Attributes

    NameRequiredValueDescription
    refYesQNameThis 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


    Name

    sx:sqlUpdateDetail — Update detail rows in one transaction

      └ sx:sqlUpdateDatabase

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    fieldYesQNameThe name of a repeating group field whose subrecords are to be written to the database.

    Content

    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>
    
    


    Name

    sx:sqlWriter — SQL record writer

      └ sx:recordWriter

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    Examples

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.

    Content

    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

    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>
    
    


    Name

    msv:schemaValidator — Validate XML with schema

      └ sx:content, sx:validator

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    messageNoSubstitutionExprA message indicating the error if validation fails, defaults to the message provided by the MSV validator.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    mimeTypeNostringThe 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    filenameNoSubstitutionExprThe name of the attached file.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    smtpHostYeshostThe 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    smtpHostYeshostThe 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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    typeNotype codeThe type of a part. The only allowed value is "alternative"

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    displayNameNoStringThe display name for the owner of the account.
    emailAddessYesaddressThe email address of the sender.

    Content

    None.


    Name

    jm:sendMail — Send mail

      └ sx:task, sx:stringable

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    subjectYesStringThe subject of the message.
    toYesSubstitutionExprA comma separated list of email addresses of recipients.
    ccYesSubstitutionExprA comma separated list of email addresses of recipients.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    hostYesStringHost name.
    portNoNumberThe port number, defaults to 21.
    userYesStringThe user name.
    passwordNoStringThe password.
    remoteSiteCommandNoStringOptional remote site command.

    Content

    None.


    Name

    edt:ftpDirectoryReader — FTP directory reader

      └ sx:recordReader

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    recurseNotrue|falseSet to true to recurse through a directory tree, false otherwise. Defaults to "false." (For backwards compatability, yes/no is also supported.)
    maxItemsNoNumberThe maximum number of directory items to read.
    directoryNoSubstitutionExprThe remote directory. Defaults to the current directory on the remote server.

    Content

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    transferTypeNobinary or asciiThe transfer type, defaults to ascii.
    remoteDirNoSubstitutionExprDeprecated - use remoteDirectory instead.
    remoteDirectoryNoSubstitutionExprThe remote directory.
    remoteFileSubstitutionExprStringThe name of the remote output file, may contain parameters in the form {$myParam}.
    localDirNoSubstitutionExprThe local directory.
    localFileNoSubstitutionExprThe local file to write to before sending it to the remote directory. Defaults to a timestamped temporary file.
    deleteLocalFileNotrue|falseDelete the local file after processing the remote file. Defaults to false. (For backwards compatability, yes/no is also supported.)

    Content

    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>
    
    


    Name

    edt:ftpSource — FTP source

      └ sx:streamSource

    Attributes

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    transferTypeNobinary or asciiThe transfer type, defaults to ascii.
    remoteDirNoSubstitutionExprDeprecated - use remoteDirectory instead.
    remoteDirectoryNoSubstitutionExprThe remote directory.
    remoteFileYesSubstitutionExprThe name of the remote input file, may contain parameters in the form {$myParam}.
    localDirNoSubstitutionExprThe local directory.
    localFileNoSubstitutionExprThe local file to write to before reading its content. Defaults to a timestamped temporary file.
    deleteLocalFileNotrue|falseDelete the local file after processing the remote file. Defaults to false. (For backwards compatability, yes/no is also supported.)

    Content

    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>
    
    

    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

    NameRequiredValueDescription
    idref-attributesNo Common id ref attributes.
    documentBaseNoSubstitutionExprThis 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

    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.

    PrecedenceOperator
    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 typesxs:string
    Numeric typesxs:byte
     xs:integer
     xs:long
     xs:float
     xs:double
     xs:decimal
    Date typesxs:dateTime
     xs:date
     xs:time
    Bit data typesxs:boolean
     xs:hexBinary

    Table A.2. Supported JDBC Data Type Mappings

     JBC Data TypeXML Schema Type
    Character typesCHARxs:string
     VARCHARxs:string
     LONGVARCHARxs:string
     CLOBxs:string
    Numeric typesTINYINTxs:byte
     SMALLINTxs:short
     INTEGERxs:integer
     BIGINTxs:long
     BIGINTxs:long
     FLOATxs:float
     DOUBLExs:double
     BIGINTxs:long
     DECIMALxs:decimal
     NUMERICxs:decimal
    Date typesTIMESTAMPxs:dateTime
     DATExs:date
     TIMExs:time
    Bit data typesBITxs:boolean
     BINARYxs:hexBinary
     VARBINARYxs:hexBinary
     LONGVARBINARYxs:hexBinary

    Appendix B. Deprecated Elements and Attributes

    Table B.1. Deprecated and removed elements

    ElementChangeVersion changedReplace withComment
    sx:composeRecordDeprecated1.1.2sx:combineRecords 
    sx:decomposeRecordDeprecated1.1.2sx:splitRecord 
    sx:recordCompositionDeprecated1.1.2sx:combinePhysicalRecords 
    sx:segmentConcatenationDeprecated1.1.2sx:mergePhysicalSegments 
    sx:repeatingSegmentRemoved1.2.0sx:repeatingGroup 
    sx:replaceRecordFilterDeprecated1.0.2sx:replaceRecord 
    sx:defaultFieldMappingDeprecated1.0.0sx:defaultFieldElementMap 
    sx:escapeVariablesDeprecated1.0.0sx:escapeSubstitutions 
    sx:spannedFlatRecordTypeDeprecated1.0.0sx:vbsFlatRecordType 
    sx:xmlRecordReaderDeprecated1.0.0sx:subtreeRecordReader 
    sx:validateRecordDeprecated1.0.0sx:recordValidator 
    sx:validateFieldDeprecated1.0.0sx:fieldValidator 
    sx:insertContentDeprecated0.9.3sx:nestedContent 
    sx:segmentMappingDeprecated0.9.3sx:subrecordMapping 
    sx:replaceDeprecated0.9.2sx:findAndReplace 
    sx:taggedFlatRecordFieldRemoved0.9.0sx:flatRecordField 
    sx:tagDelimiterDeprecated0.9.0sx:nameDelimiter 
    sx:taggedDelimitedFieldDeprecated0.9.0sx:delimitedNamedField 
    sx:repeatingTaggedFieldDeprecated0.9.0sx:repeatingField 
    sx:repeatingSegmentDeprecated0.8.4sx:repeatingGroup 
    sx:aggregateRecordDeprecated0.8.3sx:combineRecords 
    sx:recordAggregatorDeprecated0.8.2sx:combineRecords 
    sx:subtreeRecordMapDeprecated0.8.1sx:flattenSubtree 
    sx:documentFragmentDeprecated0.8.1sx:nestedContent 
    sx:removeEmptyElementFilterDeprecated0.8.0sx:removeEmptyElements 
    sx:aggregateDeprecated0.8.1sx:nestedContent 
    sx:recordTestDeprecated0.8.0sx:recordRestriction 
    sx:regexFieldCriteriaDeprecated0.8.0sx:fieldRestriction 
    sx:startGroupDeprecated0.6.5startTestThe 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:endGroupDeprecated0.6.5endTest attributeThe 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:msvFilterDeprecated0.6.4msv:schemaValidator 
    sx:discardFilterDeprecated0.6.2sx:discardHandlersx:discardFilter came before a sequence of filters and writers; sx:discardHandler comes after a sequence of filters and writers
    sx:dateDeprecated0.6.1sx:currentDateTime and sx:formatDateTime 
    sx:xmlEmitterDeprecated0.6.1sx:xsltSerializer 
    sx:customEmitterDeprecated0.6.1sx:customSerializer 
    fop:foEmitterRemoved0.6.1fop:foSerializer 
    sx:commentSymbolDeprecated0.6.0sx:commentStarter 
    sx:restrictRecordTypeDeprecated0.6.0sx:recordRestriction 
    sx:restrictFieldDeprecated0.6.0sx:fieldRestriction 
    sx:subtreeFilterDeprecated0.6.0sx:processSubtree 
    sx:processRecordFilterDeprecated0.6.0sx:processRecord 
    sx:crcFlatFileSignatureDeprecated0.5.5sx:flatFileSignature 
    sx:sizeFlatFileSignatureDeprecated0.5.5sx:flatFileSignature 
    sx:processRecordsDeprecated0.5.3sx:recordStream 
    sx:msvRecordFilterDeprecated0.5.2msv:recordValidator 
    sx:recordSubtreeMapDeprecated0.5.0sx:transformRecord 
    sx:writeRecordsDeprecated0.5.0sx:recordStream 
    sx:documentSubtreeMapDeprecated0.5.0sx:onSubtree 
    sx:styleDeprecated0.5.0sx:xslt 
    Record filter children of record readerRemoved0.4.2Record filter siblings of record readerDiscouraged since 0.4.0. Examples were changed except for sx:directoryReader examples (now updated.)
    sx:flatFileContentRemoved0.4.2sx:recordContent and sx:flatFileReaderDeprecated since 0.1.3.
    sx:processFragmentFilterDeprecated0.3.4sx:processSubtree 
    sx:documentFragmentContentMapDeprecated0.3.4sx:onSubtree 
    sx:documentFragmentRecordMapDeprecated0.3.4sx:flattenSubtree 
    sx:documentFragmentFieldMapDeprecated0.3.4sx:subtreeFieldMap 
    sx:documentRecordMapRemoved0.1.8sx:onSubtree 
    sx:elementDeprecated0.3.2sx:elementMap 
    sx:fieldSetElementMapDeprecated0.3.2sx:defaultFieldElementMap 
    sx:flowFilterDeprecated0.3.2sx:processSubtree 
    sx:flowRecordFilterDeprecated0.3.2sx:processRecord 
    sx:subrecordFilterDeprecated0.3.0See the edi example 
    sx:taskRunnerFilterDeprecated0.3.0sx:processSubtree 
    sx:taskRunnerRecordFilterDeprecated0.3.0sx:processRecord 
    sx:flatFileRecordTypeDeprecated0.2.5sx:flatRecordType 
    sx:chooseGroupDeprecated0.2.5sx:groupChoice 
    sx:transformerSettingsDeprecated0.2.5sx:xsltConfiguration 
    sx:subtaskFilterDeprecated0.2.4sx:processSubtree 
    sx:subtaskRecordFilterDeprecated0.2.4sx:processRecord 
    sx:processDocumentRemoved0.3.0Omit, sx:transform is okay. 
    sx:currentRecordFilterDeprecated0.2.0sx:processRecord 
    sx:documentFragmentFilterDeprecated0.2.0sx:processSubtree 
    sx:jaxpConfigurationDeprecated0.2.0sx:xsltConfiguration 
    sx:documentFragmentFilterDeprecated0.1.8sx:processSubtree 
    sx:pathFieldMapRemoved0.1.8sx:subtreeFieldMap 
    sx:expirySettingsRemoved0.1.8sx:expiryOptions 
    sx:pathRecordMapRemoved0.1.8sx:onSubtree 
    sx:customSerializerRemoved0.1.7sx:customSerializer 
    fop:fopSerializerRemoved0.1.7fop:foSerializer 
    sx:customPropertyDeprecated0.1.7sx:property 
    sx:taskRecordFilterDeprecated0.1.7sx:processRecord 
    sx:saxParserDeprecated0.1.7sx:saxReader 
    sx:removeEmptyElementsDeprecated0.1.6sx:removeEmptyElements 
    sx:customXmlFilterDeprecated0.1.6sx:saxFilter 
    sx:emptyContentDeprecated0.1.6sx:emptyDocument 
    sx:flatFileLayoutDeprecated0.1.6sx:flatFile 
    sx:jdbcConnectionPoolMade abstract0.1.6sx:sqlConnectionPoolOld version still supported.
    sx:mailOutputRemoved0.1.6jm:sendMail 
    sx:readerWriterRecordFilterRemoved0.1.6sx:processRecord 
    sx:recordOutputDeprecated0.1.6sx:writeRecords 
    sx:restrictFieldFilterDeprecated0.1.6sx:fieldRestriction 
    sx:streamContentDeprecated0.1.6sx:document 
    sx:streamOutputDeprecated0.1.6sx:serialize 
    sx:suppressEmptyElementFilterDeprecated0.1.6sx:removeEmptyElements 
    sx:delimitedFieldTypeDeprecated0.1.4sx:delimitedField 
    sx:flatFileRecordDeprecated0.1.4sx:flatFileBody 
    sx:positionalFieldTypeDeprecated0.1.4sx:positionalField 
    sx:fieldDeprecated0.1.3sx:positionalField or sx:delimitedField 
    sx:flatFileContentDeprecated0.1.3sx:recordContentUse a sx:flatFileReader child element.
    sx:sqlContentRemoved0.1.3sx:recordContentUse a sx:sqlReader child element

    Table B.2. Deprecated and removed attributes

    ElementAttributeChangeVersion changedReplace with
    sx:customJdbcConnectionPoolclassNameDeprecated0.1.6class
    sx:customRecordFilterclassNameDeprecated0.1.6class
    sx:saxFilter (saxFilter)classNameDeprecated0.1.6class
    sx:dynamicContentclassNameDeprecated0.1.6class
    sx:customRecordFilterclassHandlerDeprecated0.1.5class
    sx:saxFilter (sx:saxFilter)classHandlerDeprecated0.1.5class
    sx:dynamicContentclassHandlerDeprecated0.1.5class

    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
    combinePhysicalRecords, sx:combinePhysicalRecords
    combineRecords, sx:combineRecords
    command, sx:command
    commandArg, sx:commandArg
    commandSink, sx:commandSink
    commandSource, sx:commandSource
    commentStarter, sx:commentStarter
    commentSymbol, sx:commentSymbol
    composeRecord, 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
    decomposeRecord, 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
    document, sx:document
    documentation, sx:documentation
    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
    mergePhysicalSegments, sx:mergePhysicalSegments
    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
    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:segmentComposition
    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
    splitRecord, sx:splitRecord
    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