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
sx:escapeSubstitutions — Define escape rules for special characters in evaluations of SubstitutionExpr
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
escape | No | true|false | true if a character should be escaped, false
otherwise. Defaults to true |
character | No | Character | The character to optionally enclose field values. Defaults to the double quotation mark. |
escapeCharacter | No | Character | The escape character used to escape the quote symbol, e.g. the backslash ('\') or the quote symbol itself. |
escapeSequence | No | String | The character sequence used to replace the special character, e.g. '\"' or '""' to escape a double quote. |
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.
sx:expiryOptions — Expiry options
sx:patternMatcher — Regular expression pattern matcher
sx:xsltConfiguration — XSLT configuration
Name | Required | Value | Description |
---|---|---|---|
version | No | XSLT version | The value of the XSLT version attribute appearing in generated stylesheets. Defaults to "1.0" |
Optionally, any number of sx:outputProperty elements.
Optionally, any number of sx:systemProperty elements.
id ref attributes — Common id ref attributes for referencing top level elements
Name | Required | Value | Description |
---|---|---|---|
id | No | QName | An identifier of an element instance. This id is the target for references by ref attributes. |
ref | No | QName | This attribute is used to reference an id. |
The resources defined in a resources script may be given ids and referred to by reference, as shown below.
Figure 1. SAX pipeline with references
<sx:resources xmlns:sx="http://www.servingxml.com/core"> <sx:service id="myPipeline"> <sx:serialize> <sx:transform> <sx:content ref="myPreFilter"/> <sx:content ref="myFilter"/> <sx:content ref="myPostFilter"/> </sx:transform> </sx:serialize> </sx:service> <sx:saxFilter id="myPreFilter" class="PreFilter"/> <sx:xslt id="myFilter"> <sx:urlSource url="filter.xsl"/> </sx:xslt> <sx:saxFilter id="myPostFilter" class="PostFilter"/> </sx:resources>
Note that we could have written <sx:saxFilter ref="myPreFilter"/>
,
but instead we wrote <sx:content ref="myPreFilter"/>
,
substituting the abstract component sx:content for the derived sx:saxFilter.
Identifiers given to components must be unique up to
the abstract component level, for instance, a service and a filter may both be named "myPipeline",
but a sx:saxFilter and a sx:xslt must be identified differently.
sx:defaultValue — Defines a default value for a parameter or field
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
value | No | SubstitutionExpr | A string value that may contain a parameter inside curly braces, e.g. "{$my-param}.xml". |
select | No | XPath expression | An XPath expression evaluated against an sx:content substitutable child element, or, if none, the default XML document. |
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.
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.
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
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | Yes | QName | The name of the parameter. |
value | No | SubstitutionExpr | A string value that may reference a parameter or field name inside curly braces, e.g. "{$my-param}.xml". |
select | No | XPath expression | An XPath expression evaluated against an sx:content substitutable child element, or, if none, the default XML document. |
type | No | XML Schema types | The parameter value type. Defaults to xs:string The input parameter values will be converted to this type
if required. |
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.
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.
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>
sx:property — Property
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
key | Yes | String | Deprecated, use name instead. |
name | Yes | String | The custom property name. |
value | Yes | String | The custom property value. |
sx:systemProperty — System property
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
key | Yes | String | Deprecated, use name instead. |
name | Yes | String | The system property name. |
value | Yes | String | The value of a system property. |
sx:validator — Abstract element standing for a validator
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.
sx:withParameters — Declare the parameters that need to be passed to an XSLT processor
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
parameters | Yes | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all parameters." A namespace prefix followed by a colon followed by the value '*' means all parameters belonging to the namespace. |
exceptParameters | No | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all parameters." A namespace prefix followed by a colon followed by the value '*' means all parameters belonging to the namespace. |
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.
sx:choose — Choose from alternatives with XPATH test conditions
└ sx:task, sx:content, sx:recordFilter, sx:mapXml, sx:stringable
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.
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>
sx:when — When condition of an sx:choose
Name | Required | Value | Description |
---|---|---|---|
test | Yes | XPath Boolean Expression | The boolean expression to evaluate. |
sx:onError — Catches an exception raised by a sx:task element, to be revisited
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>
sx:raiseError — Raises an exception inside an sx:onError, to be revisited
A sx:raiseError
element results in an exception being thrown.
It is used inside an sx:onError element.
sx:resources — The root element of a resources script
Name | Required | Value | Description |
---|---|---|---|
ns | No | URI | The default namespace for the pages, documents, styles and serializers defined in this resources script. |
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
service | Yes | SubstitutionExpr | An expression that evaluates to a QName identifying a service. |
sx:service — Service
sx:task — Abstract element standing for a task
Name | Required | Value | Description |
---|---|---|---|
ref | Yes | QName | This attribute is used to reference the id of a task. |
This is an abstract element that allows us to refer generically to any specialization of
sx:task
, such as sx:transform.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
separator | No | char | A separator to separate each string value in the content. |
quoteSymbol | No | char | A symbol to surround each string value. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
fromFormat | Yes | String | The format of the input string, which must must follow the syntax specified for the JDK SimpleDateFormat class. |
toFormat | No | String | The format of the output string, which must must follow the syntax specified for the JDK SimpleDateFormat class. Defaults to the date format for the default locale. |
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
format | Yes | String | The format of the input string, which must must follow the syntax specified for the JDK SimpleDateFormat class. |
inputTimezone | No | String | The time zone for the input date. Defaults to the Java default time zone. |
outputTimezone | No | String | The time zone for the output date. Defaults to the Java default time zone. |
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.
The current date is output as a string with a lexical representation as defined for xs:date of XML Schema Part 2: Datatypes.
The current date is output as a string with a lexical representation as defined for xs:dateTime of XML Schema Part 2: Datatypes.
The current time is output as a string with a lexical representation as defined for xs:time of XML Schema Part 2: Datatypes.
sx:date — Deprecated, replaced by sx:currentDateTime and sx:formatDateTime
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
format | No | String | The format of the output string, which must must follow the syntax specified for the JDK SimpleDateFormat class. Defaults to the date format for the default locale. |
sx:findAndReplace — Find and replace in a string using regular expressions
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
searchFor | Yes | Regex | Match sub-sequences of the input string against this pattern. |
replaceWith | Yes | String | Replace all matches with this expression. Dollar signs ($) may be used as references to captured subsequences in the match regular expression, and backslashes (\) may be used to escape literal characters. |
caseSensitive | No | true | false | Defaults to true . |
useRegex | No | true | false | Defaults to true . |
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.
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
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
format | No | String | The format of the output string, which must must follow the syntax specified for the JDK SimpleDateFormat class. Defaults to the date format for the default locale. |
Lexical representation of one the eight XML Schema date/time datatypes, or an sx:stringable element that evaluates to a lexical representation.
sx:string — Abstract element standing for any string element, e.g. sx:toString
Name | Required | Value | Description |
---|---|---|---|
ref | Yes | QName | This attribute is used to reference the id of a string. |
This is an abstract element that allows us to refer generically to any specialization of
sx:stringable
, such as sx:toString.
sx:stringable — Abstract element standing for any element that can render itself as a string, e.g. sx:transform
Name | Required | Value | Description |
---|---|---|---|
ref | Yes | QName | This attribute is used to reference the id of a string. |
This is an abstract element that allows us to refer generically to any specialization of
sx:stringable
, such as sx:toString.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
select | No | XPath expression | An XPath expression evaluated against an sx:content substitutable child element, or, if none, the default XML document. |
value | No | SubstitutionExpr | A string value that may contain one or more parameters enclosed in curly braces, e.g. "{$my-param}.xml". |
separator | No | char | A separator to separate the pieces if the expression resolves to multiple values. |
quoteSymbol | No | char | A symbol to surround the pieces. Deprecated, use a sx:quoteSymbol child element instead. |
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.
sx:command — Command
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.
sx:commandArg — Command argument
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
directory | No | SubstitutionExpr | Optionally, the current working directory. |
encoding | No | String | A charset name. Defaults to the platform's default
charset .
|
One sx:command element.
Optionally, any number of sx:commandArg elements
Optionally, any number of sx:envVariable elements
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
directory | No | SubstitutionExpr | Optionally, the current working directory. |
encoding | No | String | A charset name. Defaults to the platform's default
charset .
|
One sx:command element.
Optionally, any number of sx:commandArg elements
Optionally, any number of sx:envVariable elements
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.
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>
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
encoding | No | String | A charset name. If a charset is not supplied,
the default will be the charset of the default sink, e.g., the platform's
default charset if the default sink is a flat file supplied to the command line app with the -o option.
|
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
encoding | No | String | A charset name. If an charset is not supplied,
the default will be the charset of the default source, e.g., the platform's
default charset if the default source is a flat file supplied to the command line app with the -i option.
|
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
directory | No | SubstitutionExpr | An optional directory name. |
file | Yes | SubstitutionExpr | The name of the output file, may contain parameters in the form {$myParam}. |
encoding | No | String | A charset name. If the output is XML, and a charset is not supplied,
the XML serializer will use the last encoding encountered in the output properties of the transformation pipeline.
If the output is a flat file, and a charset is not supplied, the default will be the platform's default charset.
|
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>
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
directory | No | SubstitutionExpr | An optional directory name. |
file | Yes | SubstitutionExpr | The name of the input file, may contain parameters in the form {$myParam}. |
encoding | No | String | A charset name. If the input is XML, and a charset is not supplied,
the XML parser will use the encoding specified by the XML declaration. If the input is a
flat file, and a charset is not supplied, the default will be the platform's default charset.
|
sx:streamSink — Abstract element standing for a stream sink
Name | Required | Value | Description |
---|---|---|---|
ref | Yes | QName | This attribute is used to reference the id of a stream sink. |
This is an abstract element that allows us to refer generically to any specialization of
sx:streamSink
, sx:fileSink.
sx:streamSource — Abstract element standing for a stream source
Name | Required | Value | Description |
---|---|---|---|
ref | No | QName | This attribute is used to reference the id of a stream source. |
This is an abstract element that allows us to refer generically to any specialization of
sx:streamSource
, such as sx:fileSource.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
url | Yes | SubstitutionExpr | The name of the input url, may contain parameters in the form {$myParam}. |
encoding | No | String | A charset name. If the input is XML, and a charset is not supplied,
the XML parser will use the encoding specified by the XML declaration. If the input is a
flat file, and a charset is not supplied, the default will be the platform's default charset.
|
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
test | Yes | XPath Boolean Expression | An XPath boolean expression applied to the context document. |
sx:attribute — Add an attribute to wrapping elements inside a sx:wrap element
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
attribute | Yes | SubstitutionExpr | The name of an attribute to insert into a parent element. The attribute name may contain a field name within curly braces, which will evaluate to the value of the field. The result must evaluate to a QName. |
select | No | XPath expression | An XPath expression evaluated against an sx:content substitutable child element, or, if none, the default XML document. |
value | No | SubstitutionExpr | Express the attribute value as a literal value, which may contain parameter names and field names enclosed in curly braces. The result must evaluate to a QName. |
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
path | Yes | SAXPath | A SAXPath expression, which identifies subtrees. |
batchSize | Yes | Integer | The number of subtrees in a batch. |
maxFiles | No | Integer | The maximum number of batch files. |
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>
sx:content — Abstract element standing for XML content
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.
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
class | Yes | Java Class | The name of a Java class that implements com.servingxml.io.saxsink.SaxSink . |
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
wrapWith | No | SubstitutionExpr | Wrap all documents in the sequence with this root element. |
Either
or
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.
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>
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
class | Yes | Java Class | The name of a Java class that implements com.servingxml.components.content.dynamic.RequestHandler and, optionally, com.servingxml.components.content.dynamic.Cacheable. |
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>
sx:saxSink — Abstract element standing for a sink of SAX events
This is an abstract element that allows us to refer generically to any specialization of
sx:saxSink
e.g. sx:xsltSerializer.
sx:filter — Deprecated in 1.0.0, use sx:content instead
This is an abstract element that allows us to refer generically to any specialization of
sx:content
, such as sx:xslt.
sx:keyField — Key field
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | No | Name | Reference to the name of a parameter. On a request, the field value will be set to that parameter value. |
sx:outputProperty — Output property for XML serializer
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | Yes | String | The output property name. |
value | Yes | SubstitutionExpr | The output property value. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
path | Yes | SAXPath | A SAXPath expression. |
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.
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | No | QName | The name of the content, used as the document element in default record mappings, defaults to "document". |
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
elements | Yes | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all elements." A namespace prefix followed by a colon followed by the value '*' means all elements belonging to the namespace. |
exceptElements | No | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all elements." A namespace prefix followed by a colon followed by the value '*' means all elements belonging to the namespace. |
attributes | Yes | NameTest list | A space-separated list of element QNames, or wildcards, to include. The value '*' means "all attributes." A namespace prefix followed by a colon followed by the value '*' means all attributes belonging to the namespace. |
exceptAttributes | No | NameTest list | A space-separated list of attribute QNames, or wildcards, to exclude. The value '*' means "all attributes." A namespace prefix followed by a colon followed by the value '*' means all attributes belonging to the namespace. |
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".
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
elements | Yes | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all elements." A namespace prefix followed by a colon followed by the value '*' means all elements belonging to the namespace. |
except | No | NameTest list | Deprecated, use exceptElements
instead. |
exceptElements | No | NameTest list | A space-separated list of QNames or wildcards. The value '*' means "all elements." A namespace prefix followed by a colon followed by the value '*' means all elements belonging to the namespace. |
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
class | Yes | Java Class | The name of a Java class that implements org.xml.sax.XMLFilter. |
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
class | Yes | Java Class | The name of a Java class that implements org.xml.sax.XMLReader. |
systemId | No | SubstitutionExpr | The system id passed to the parse method of the reader.
Defaults to an empty string. |
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(); } }
sx:saxSource — Abstract element standing for a source of SAX events
This is an abstract element that allows us to refer generically to any specialization of
sx:saxSource
, such as sx:saxReader.
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
path | Yes | SAXPath | A SAXPath expression. |
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.
The sx:wrap
instruction wraps the content that
its children write to the default XML sink with containing elements.
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>
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
documentBase | No | SubstitutionExpr | This attribute is used to explicitly set the base for document URI resolution. The base can be relative, in which case it is resolved relative to the location of the resources script. |
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.
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>
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>
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
batchSize | Yes | Number | The batch size. |
recordType | No | NameTest | Count records whose record types match the record type name test. |
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.
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
batchSize | Yes | Number | The batch size. |
recordType | No | NameTest | Count records whose record types match the record type name test. |
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.
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | Yes | SubstitutionExpr | The name of the composite record type. |
repeatingGroup | Yes | QName | The name of the field containing a list of records. |
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to
true |
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to
startTest .
|
compositeRecordType | No | QName | Deprecated in version 0.9.5 - replaced by recordType attribute. |
repeatingGroupField | No | QName | Deprecated in version 0.9.5 - replaced by repeatingGroup attribute. |
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.
Example 44. Grouping records into a composite record.
The input is three records of record type "orderRemarks",
REMTEI | REM |
---|---|
REM | AAAA |
REM | BBB |
REM | CCC |
The XML representation of the "orderRemarks" records is
<orderRemarks><REMTEI>REM</REMTEI><REM>AAAA</REM></orderRemarks> <orderRemarks><REMTEI>REM</REMTEI><REM>BBBB</REM></orderRemarks> <orderRemarks><REMTEI>REM</REMTEI><REM>CCCC</REM></orderRemarks>
The sx: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>
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
class | Yes | Java Class | The name of a Java class that implements com.servingxml.components.recordio.RecordFilter |
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
class | Yes | Java Class | The name of a Java class that implements com.servingxml.components.recordio.RecordFilter |
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); } }
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | Apply discard handling to records of this type. Defaults to records of any type. |
This instruction allows you to write discarded records to file or database.
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | Apply discard handling to records of this type. Defaults to records of any type. |
This instruction allows you to write discarded records to file or database.
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
field | Yes | QName | The name of the field. |
pattern | Yes | Regex | The regular expression to be tested against the value of the field. |
negate | No | true/false | Reverses the restriction. |
sx:fieldValidator — Field validator
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
fieldName | Yes | QName | The name of the field to validate. |
message | Yes | SubstitutionExpr | A message indicating the error if validation fails. |
Any number of sx:valueRestriction elements.
Any number of sx:validator elements (in particular, sx:recordValidator elements for validating subrecords)
sx:fileFilter — File filter
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
pattern | Yes | Regex | The regular expression to be tested against the file name. |
negate | No | true/false | Reverses the restriction. |
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.
sx:log — Log
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
message | No | SubstitutionExpr | A string value that may contain parameters inside curly braces, e.g. "{$message}". |
level | No | error/warning/notice/trace | Defaults to "error". |
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.
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.
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>
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
newRecordType | No | QName | The record type name of the modified record. Defaults to the record type name of the original record. |
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.
sx:newField — Add a field to a record
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | Yes | QName | The name of the field. |
value | No | SubstitutionExpr | A string value that may reference a parameter or field inside curly braces, e.g. "{$my-param}.xml". |
select | No | XPath expression | An XPath expression evaluated against an sx:content substitutable child element, or, if none, the XML representation of the record. |
match | Yes | Regex | The regular expression to be tested against the value of the field. |
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.
sx:newRecord — Create a new record
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | The type of the new record. Defaults to the type of the original record. |
fields | No | NameTest list | A space-separated list of names of fields to be copied to the new record. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to "*". |
except | No | QName list | (deprecated, use exceptFields instead) |
exceptFields | No | QName list | A space-separated list of names of fields not to be copied to the new record. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to the empty string. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | The name of the record type given to the parameters. |
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | Task records of this type. Defaults to records of any type. |
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.
sx:quoteSymbol — Quote symbol
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
value | No | Character | Deprecated - replaced by character
in 0.9.1. |
character | No | Character | The character to optionally enclose field values. Defaults to the double quotation mark. |
escapedBy | No | Character | Deprecated - replaced by escapeCharacter
in 0.9.1.
|
escapeCharacter | No | Character | The escape character used to escape the quote symbol, e.g. the backslash ('\') or the quote symbol itself. |
escapeWith | No | String | Deprecated - replaced by escapeSequence
in 0.9.1.
|
escapeSequence | No | String | The character sequence used to replace the special character, e.g. '\"' or '""' to escape a double quote. |
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | Produce a subset of fields for records of this type, or for all records if no type specified. |
newRecordType | No | QName | The type of the new record. Defaults to the type of the input record. |
fields | No | NameTest list | A space-separated list of names of fields to be copied to the new record. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to "*". |
exceptFields | No | QName list | A space-separated list of names of fields not to be copied to the new record. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to the empty string. |
sx:recordFilter — Abstract element standing for a record filter
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.
sx:recordReader — Abstract element standing for a record reader
This is an abstract element that allows us to refer generically to any
sx:recordReader
specialization, such as sx:flatFileReader
or sx:recordStream.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | The name of the record type. |
test | No | XPath | An XPath boolean expression evaluated against the XML representation of the record. |
negate | No | true/false | Reverses the restriction. |
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.
sx:recordWriter — Abstract element standing for a record writer
Name | Required | Value | Description |
---|---|---|---|
ref | Yes | QName | This attribute is used to reference the id of a record writer. |
This is an abstract element that allows us to refer generically to any specialization of
sx:recordWriter
, such as sx:flatFileWriter.
sx:recordStream — A record stream
└ sx:recordReader, sx:recordFilter, sx:recordWriter, sx:task, sx:stringable
If you want to have additional record writers in a sx:recordStream
element,
use one or more sx:recordTee elements.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | Validate records of this type. |
message | No | SubstitutionExpr | A message indicating the error if validation fails. |
Optionally, any number of sx:parameter elements.
Any number of sx:validator substitutable elements, such as sx:fieldValidator, sx:assert or msv:schemaValidator, for validating the fields of the record.
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | Apply changes to records of this type. Defaults to records of any type. |
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>
sx:replaceRecordFilter — Deprecated in version 1.0.2, replaced by sx:replaceRecord
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | Apply changes to records of this type. Defaults to records of any type. |
sx:restriction — Abstract element standing for a restriction
This is an abstract element that allows us to refer generically to any specialization of
sx:recordFilter
, such as sx:fieldRestriction.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
operator | No | and/or | Deprecated. As of version 0.6.2, replaced by sx:or and sx:and child elements.
The boolean operator to apply to the sx:restriction child elements, "and" or "or". Defaults to "or". |
Optionally, any number of sx:parameter elements.
Any number of specializations of the abstract element sx:restriction, in particular, any number of sx:recordRestriction and sx:fieldRestriction elements.
Optionally, an sx:unmatchedRecord element, containing a record pipeline that will be executed if the record does not match the restrictions. This record pipeline may contain any number of sx:recordFilter and sx:recordWriter elements, and in particular may end with an sx:discard element if you wish to discard an unmatched record.
This instruction allows records to be filtered by applying a regular expression to the value of a field.
sx:unmatchedRecord — A record stream
sx:splitRecord — Decompose a composite record into its constituent subrecords
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | Yes | QName | Decompose records of this type. |
repeatingGroup | Yes | QName | Decompose records of the specified type on this repeating group field. |
subrecordType | No | SubstitutionExpr | The type of the decomposed records. Defaults to the record type of the subrecords in the repeating group. |
compositeRecordType | No | QName | Deprecated in version 0.9.5 - replaced by recordType attribute. |
repeatingGroupField | No | QName | Deprecated in version 0.9.5 - replaced by repeatingGroup attribute. |
ofRecordType | No | QName | Deprecated - use recordType
instead.
|
onField | No | QName | Deprecated - use repeatingGroup
instead. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recurse | No | true|false | Set to "true" to recurse through a directory tree, "false" otherwise. Defaults to "false." (For backwards compatability, yes/no is also supported.) |
maxItems | No | Number | The maximum number of directory items to read. |
directory | Yes | SubstitutionExpr | The root directory. |
Each record will have type
Each record will contain the following fields:
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>
sx:validateField — Deprecated in version 1.0, replaced by sx:fieldValidator
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
fieldName | Yes | QName | The name of the field to validate. |
message | Yes | SubstitutionExpr | A message indicating the error if validation fails. |
Any number of sx:valueRestriction elements.
Any number of sx:validateRecord elements (for validating subrecords)
sx:validateRecord — Deprecated in version 1.0, replaced by sx:recordValidator
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | Validate records of this type. |
message | No | SubstitutionExpr | A message indicating the error if validation fails. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
pattern | Yes | Regex | The regular expression to be tested against the value of the field. |
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.
Literal Element — Literal Element
A literal element
is any element appearing in the content of a sx:recordMapping refsection
that does not belong to the ServingXML
vocabulary. Such elements will be mapped directly to XML.
A literal element
may contain other literal elements
in its content, and in
addition it may contain other mapping elements:
Optionally, any 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.
The content of a sx:cdata
element will be enclosed by a CDATA refsection,
<![CDATA[ ... ]]>
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
fields | Yes | NameTest list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. |
exceptFields | No | QName list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to the empty string. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
fields | Yes | NameTest list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. |
except | No | QName list | Deprecated, use exceptFields
instead. |
exceptFields | No | QName list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to the empty string. |
sx:defaultFieldMapping — Deprecated in version 1.0, aliased to sx:defaultFieldElementMap
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
fields | Yes | NameTest list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. |
except | No | QName list | Deprecated, use exceptFields
instead. |
exceptFields | No | QName list | A space-separated list of names of fields. The value '*' means "all fields." A namespace prefix followed by a colon followed by the value '*' means all fields belonging to the namespace. Defaults to the empty string. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
element | Yes | SubstitutionExpr | The name of an element to insert into the output XML content. The element name may contain a field name within curly braces, which will evaluate to the value of the named field. The result must evaluate to a QName. |
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
attribute | Yes | SubstitutionExpr | The name of an attribute to insert into a parent element. The attribute name may contain a field name within curly braces, which will evaluate to the value of the field. The result must evaluate to a QName. |
field | No | QName | Map this field's value to the attribute value. |
select | No | XPath expression | Apply an XPath expression to the elements in the XML representation of a record that satisfy the conditon of the match pattern.
The expression is evaluated as a string.
|
value | No | SubstitutionExpr | Express the attribute value as a literal value, which may contain parameter names and field names enclosed in curly braces. The result must evaluate to a QName. |
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
element | Yes | SubstitutionExpr | The name of an element to insert into the output XML content. The element name may contain a field name within curly braces, which will evaluate to the value of the named field. The result must evaluate to a QName. |
match | No | XSLT pattern | Define a condition that an element in the XML representation of a record must satisfy in order to be selected by an XPath expression. Defaults to "/*" |
select | No | XPath expression | Apply an XPath expression to the collection of elements in the XML representation of a record that satisfy the conditon of the match pattern.
The expression is evaluated as a string.
|
value | No | SubstitutionExpr | Express the element value as a literal value, which may contain parameter names and field names enclosed in curly braces. |
field | No | QName | Map this field's value to the element value. |
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
element | Yes | SubstitutionExpr | The name of an element to insert into the output XML content. The element name may contain a field name within curly braces, which will evaluate to the value of the named field. The result must evaluate to a QName. |
match | No | XSLT pattern | Define a condition that an element in the XML representation of a record must satisfy in order to be selected by an XPath expression. Defaults to "/*" |
select | No | XPath expression | Apply an XPath expression to the collection of elements in the XML representation of a record that satisfy the conditon of the match pattern.
The expression is evaluated as a string.
|
value | No | SubstitutionExpr | Express the element value as a literal value, which may contain parameter names and field names enclosed in curly braces. |
field | No | QName | Map this field's value to the element value. |
Optionally, if there is no field
,
value
or
select
attribute, any combination of string literals and
inlined sx:stringable
substitutable elements. The string expressions will be evaluated in place,
forming one string. Leading and trailing whitespace will be trimmed.
Optionally, any number of sx:fieldAttributeMap elements.
Optionally, any number of sx:parameter elements.
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | Group applies to fields of this record type. |
fields | Yes | QName | A space separated list of fields to group by. |
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>
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to
true |
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to
startTest .
|
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.
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>
sx:mapXml — Abstract element standing for any element that maps records to XML
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | Records with the specified recordType name will trigger this event processing. If no recordType attribute is specified, all records will be processed. |
test | No | XPath | An XPath boolean expression evaluated against the XML representation of the record. |
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to
true |
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to
startTest .
|
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.
sx:reorderRecords — Reorder records within a group
└ sx:sort
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordTypes | Yes | QName | A space separated list of record types. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
field | Yes | QName | The name of a repeating group field to map (deprecated in 0.9.5, use repeatingGroup instead.) |
repeatingGroup | Yes | QName | The name of a repeating group field to map. |
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
match | No | XSLT pattern | Define a condition that an element in the XML fragment must satisfy in order to be mapped to a record of the specified type. Defaults to "/*" |
recordType | Yes | QName | The record type of the output record. |
sx:inverseRecordMapping — Map XML to records
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.
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 & 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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
path | Yes | SAXPath | A SAXPath expression. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
match | No | XSLT pattern | Define a condition that an element in the XML fragment must satisfy in order to be selected by an XPath expression. Defaults to "/*" |
select | No | XPath expression |
Apply an XPath expression to the collection of elements in the XML fragment that satisfy the conditon of the match pattern.
The expression is evaluated as a string. If the match pattern matches several elements, the XPath expression will be applied to each of them,
evaluating to multiple field values.
|
field | Yes | QName | The name of an output field. |
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.
Flat File Options - Attributes — Flat file options
Name | Required | Value | Description |
---|---|---|---|
flushRecordOnWrite | No | true|false | Indicates whether to flush the output stream every time a record is written. Defaults to false .
|
trim | No | true|false | Indicates whether to trim leading and trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.) |
zeroBased | No | true|false | Indicates whether position indexes are zero-based, defaults to
false , by
default position indexes are one-based.
|
trimLeading | No | true|false | Indicates whether to trim leading whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.) |
trimWithinQuotes | No | true|false | Indicates whether to trim quoted values of leading and trailing
whitespace. Defaults to false .
|
trimLeadingWithinQuotes | No | true|false | Indicates whether to trim quoted values of leading whitespace. Defaults
to false .
|
trimTrailingWithinQuotes | No | true|false | Indicates whether to trim quoted values of trailing whitespace. Defaults
to false .
|
trimQuoted | No | true|false | Deprecated as of version 1.1.0, use trimWithinQuotes
instead.
|
trimTrailing | No | true|false | Indicates whether to trim trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.) |
quote | No | "auto" or "always" or "never" |
Indicates whether a value should be searched for a field delimiter, and if so enclosed in quote marks, or whether a value should
always be enclosed in quote marks. The default is never for
positional files, auto for delimited or mixed files. Previous
versions supported yes/no values, which have been deprecated, but are translated
to "auto" and "never" respectively.
|
omitFinalFieldDelimiter | No | true|false | Defaults to true . (For backwards compatability, "yes"/"no" is also supported.)
|
omitFinalRepeatDelimiter | No | true|false | Defaults to true (For backwards compatability, "yes"/"no" is also supported.)
|
padCharacter | No | Character | The pad character used for formatting values into a field of fixed width, e.g., a space or zero. |
justify | No | "left","right", or "center" | Indicates how to align the data within the field. |
lineDelimited | No | true|false | If set to true , records are expected to end with end-of-line delimiters, otherwise fixed width records are assumed.
Defaults to true . (For backwards compatability, "yes"/"no" is also supported.) |
countPositionsInBytes | No | true|false | If set to true , positions between fields are counted in
bytes, otherwise positons are counted in characters. Defaults to
true if any field is a binary field or if flat file
signatures are specified, otherwise defaults to false .
|
ignoreTrailingEmptyLines | No | true|false | If set to true , lines at the end of files that are empty (apart from space, tab and record delimiter characters) are ignored.
Defaults to true . (For backwards compatability, "yes"/"no" is also supported.) |
ignoreEmptyLines | No | true|false | If set to true , all lines in the files that are empty (apart from space, tab and record delimiter characters) are ignored.
Defaults to false . (For backwards compatability, "yes"/"no" is also supported.) |
Flat File Options - Elements — Flat File Options
Any number of sx:recordDelimiter elements.
Any number of sx:segmentDelimiter elements.
Any number of sx:repeatDelimiter elements.
Any number of sx:fieldDelimiter elements.
Any number of sx:subfieldDelimiter elements.
Any number of sx:nameDelimiter elements.
A sx:quoteSymbol element.
Zero or many sx:commentStarter elements.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | No | QName | The name of the annotation record. |
width | Yes | number | The width of the annotation record. |
justify | No | "left","right", or "center" | Indicates how to align the data within the field. The default is "left". |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | Yes | QName | The name of the field. |
label | No | SubstitutionExpr | A label for the field. |
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field. |
width | Yes | SubstitutionExpr | The width of the field. |
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  and  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>
sx:combinePhysicalRecords — Combine multiple physical records into a composite logical record
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent | |
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to
true |
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to
startTest .
|
suppressRDW | No | true|false | Suppress the 4-byte record descriptor word (RDW) from the front of
the logical record, defaults to false .
|
Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements
One sx:metaRecord element.
sx:commentStarter
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
value | Yes | String | The value of a comment symbol. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent |
Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements
One or more specializations of the abstract sx:flatRecordField element, including sx:positionalField, sx:binaryField, sx:integerField and sx:delimitedField. If positional and delimited fields are mixed, the positional fields should precede the delimited fields.
One sx:combinePhysicalRecords element.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | Yes | QName | The name of the field. |
label | No | SubstitutionExpr | A label for the field. |
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field. |
trim | No | true|false | Indicates whether to trim leading and trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.) |
trimLeading | No | true|false | Indicates whether to trim leading whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.) |
trimTrailing | No | true|false | Indicates whether to trim trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.) |
trimWithinQuotes | No | true|false | Indicates whether to trim quoted values of leading and trailing whitespace. Defaults to the setting at the record level. |
trimLeadingWithinQuotes | No | true|false | Indicates whether to trim quoted values of leading whitespace. Defaults to the setting at the record level. |
trimTrailingWithinQuotes | No | true|false | Indicates whether to trim quoted values of trailing whitespace. Defaults to the setting at the record level. |
quote | No | "auto" or "always" or "never" |
Indicates whether a value should be searched for a field delimiter, and if so enclosed in quote marks, or whether a value should
always be enclosed in quote marks. The default is auto . Previous versions supported yes/no values,
which have been deprecated, but are translated to "auto" and "never" respectively.
|
alwaysQuote | No | "yes" or "no" | Deprecated as of version 0.6.3, use quote="always" instead. |
minLength | No | number | If the length of the field value is less than minLength , it will be padded with the padCharacter .
|
maxLength | No | number | If the length of the field is greater than maxValue , it will be truncated.
|
justify | No | "left","right", or "center" | The alignment rule used for formatting values into a field of fixed width. The default is "left". |
padCharacter | No | Character | The pad character used for formatting values into a field of fixed width, e.g., a space or zero. The default is a space. |
maxWidth | No | number | The maximum field width, including delimiter. If the number of
characters read exceeds the specified width , that will be regarded as the end of this field
and the beginning of the next. Defaults to the record width.
|
width | No | number | Deprecated, use maxWidth instead.
|
omitFinalFieldDelimiter | No | true|false | Defaults to true
(For backwards compatability, "yes"/"no" is also supported.)
|
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.)
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
label | No | SubstitutionExpr | A label for the field. |
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field. |
trim | No | true|false | Indicates whether to trim leading and trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.) |
trimLeading | No | true|false | Indicates whether to trim leading whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.) |
trimTrailing | No | true|false | Indicates whether to trim trailing whitespace. Defaults to the setting at the record level. (For backwards compatability, "yes"/"no" is also supported.) |
minLength | No | number | If the length of the field value is less than minLength , it will be padded with the padCharacter .
|
maxLength | No | number | If the length of the field is greater than maxValue , it will be truncated.
|
justify | No | "left","right", or "center" | The alignment rule used for formatting values into a field of fixed width. The default is "left". |
padCharacter | No | Character | The pad character used for formatting values into a field of fixed width, e.g., a space or zero. The default is a space. |
maxWidth | No | number | The maximum field width, including delimiter. If the number of
characters read exceeds the specified width , that will be regarded as the end of this field
and the beginning of the next. Defaults to the record width.
|
omitFinalFieldDelimiter | No | true|false | Defaults to true
(For backwards compatability, "yes"/"no" is also supported.)
|
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.
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"
sx:fieldDelimiter — Field delimiter
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
value | No | SubstitutionExpr | A string of one or more characters that indicates the end of a field. |
escapeCharacter | No | Character | An escape character used to escape the delimiter. |
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.
You can also use numerical entity references to specify delimiter values, e.g. 	 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.
sx:flatFile — Flat file
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent |
Optionally, any number of flat file option elements, for example, any number of sx:recordDelimiter elements, or any number of sx:commentStarter elements.
Optionally, a sx:flatFileTrailer element.
A sx:flatFileBody element.
Optionally, any number of sx:flatFileSignature elements.
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.
sx:flatFileBody — Flat file body
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent |
Example 71. Using a sx:flatFileBody element.
<sx:flatFile id="tradesFlatFile"> <sx:commentStarter value="#"/> <sx:flatFileBody> <sx:flatRecordTypeChoice> <sx:positionalField name="record_type" width="2"/> <sx:when test="record_type='TR'"> <sx:flatRecordType name="trade"> <sx:positionalField name="record_type" width="2"/> <sx:positionalField name="id" width="4"/> <sx:positionalField name="trade_date" width="10"/> <sx:positionalField name="trade_time" width="8"/> <sx:positionalField name="description" width="30"/> </sx:flatRecordType> </sx:when> <sx:when test="record_type='TN'"> <sx:flatRecordType name="transaction"> <sx:positionalField name="record_type" width="2"/> <sx:positionalField name="id" width="4"/> <sx:positionalField name="reference" width="5"/> <sx:positionalField name="description" width="30"/> </sx:flatRecordType> </sx:when> </sx:flatRecordTypeChoice> </sx:flatFileBody> </sx:flatFile> <sx:recordMapping id="tradesToXmlMapping"> <trades> <sx:onRecord recordType="trade"> <trade> <sx:fieldAttributeMap field="id" attribute="id"/> <sx:fieldElementMap field="description" element="description"/> </trade> </sx:onRecord> <sx:onRecord recordType="transaction"> <transaction> <sx:fieldAttributeMap field="id" attribute="id"/> <sx:fieldElementMap field="reference" element="reference"/> <sx:fieldElementMap field="description" element="description"/> </transaction> </sx:onRecord> </trades> </sx:recordMapping>
sx:flatFileSignature — Flat file signature
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | Yes | QName | Identifies a header or trailer record. |
field | Yes | QName | Identifies a field in a header or trailer record. |
method | Yes | string | Must be one of "crc", "size, or "custom". |
class | No (unless method is "custom") | Java class name | The name of a Java class that implements com.servingxml.components.flatfile.SignatureMethod |
validate | No | true|false | Indicates whether, when reading a file, the computed signature should be validated against the value stored in the header or trailer.
Defaults to true . (For backwards compatability, "yes"/"no" is also supported.) |
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.
sx:flatFileHeader — Flat file header
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
lineCount | No | Number | The number of lines in the header. |
recordLength | No | Integer | The total length of the header records, including record delimiter, if any. |
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent |
Optionally, any number of sx:parameter elements.
Optionally, any number of flat file option elements, for example, any number of sx:recordDelimiter elements, or any number of sx:commentStarter elements.
Optionally, a sx:streamSource element.
Optionally, a sx:flatFile element. Defaults to a file reader that examines the first row of the file for delimited column headings.
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>
sx:flatRecordField — Abstract element standing for any flat record field
This is an abstract element that allows us to refer generically to any specialization of
sx:flatRecordField
, such as sx:delimitedField.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent | |
name | No | SubstitutionExpr | A QName, or an expression that evaluates to a QName. Defaults to "record" |
recordLength | No | SubstitutionExpr | The total length of the record, including record delimiter, if any. |
Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements
One or more specializations of the abstract sx:flatRecordField element, including sx:delimitedField, sx:positionalField, sx:repeatingGroup, and sx:flatRecordType elements. If positional and delimited fields are mixed, the positional fields should precede the delimited fields. Note that you can extend other flat record types by referring to the base sx:flatRecordType elements in the content.
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent |
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.
sx:flatFileTrailer — Flat file trailer
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
lineCount | No | Number | The number of lines in the trailer. |
recordLength | No | Integer | The total length of the header records, including record delimiter, if any. |
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | Yes | QName | The name of the field. |
label | No | SubstitutionExpr | A label for the field. |
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field. |
width | Yes | number | The width of the field, which must be 1, 2, 4, or 8. |
bigEndian | No | true|false | Specifies the byte order, defaults to true .
|
sx:mergePhysicalSegments — Merges a number of physical segments into one logical record.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent | |
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to
true |
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to
startTest .
|
segmentLength | No | SubstitutionExpr | The length of the segment, may be read from a field in the header. |
suppressRDW | No | true|false | Suppress the 4-byte record descriptor word (RDW) from the front of
the logical record, defaults to false .
|
Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements
One sx:metaRecord element.
sx:metaRecord — Meta record
This is an abstract element that allows us to refer generically to any specialization of
sx:metaRecord
, such as sx:flatRecordType.
sx:nameDelimiter — Separate a field name and value
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
value | No | SubstitutionExpr | The character(s) used to separate name/value pairs. |
Value of the character(s) used to separate name/value pairs.
The following special encodings may appear in a delimiter value.
You can also use numerical entity references to specify delimiter values, e.g. 	 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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | Yes | QName | The name of the field. |
label | No | SubstitutionExpr | A label for the field. |
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field. |
width | No | number | The width of the field. Defaults to the width corresponding to the digitCount. |
digitCount | No | number | The total number of digits in the packed decimal number. |
decimalPlaces | No | number | The number of places to the right of the implied decimal. Defaults to 0 .
|
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.)
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent | |
name | Yes | QName | The name of the nonrepeating group field. |
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field. |
Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements
A sx:flatRecordType element, or a sx:flatRecordTypeChoice element.
The sx:segmentDelimiter, if not supplied, defaults to the end of the record.
A nonrepeating group reads at most one record
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | Yes | QName | The name of the field. |
label | No | SubstitutionExpr | A label for the field. |
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field. |
width | Yes | SubstitutionExpr | The width of the field. |
decimalPlaces | No | number | The number of places to the right of the implied decimal. Defaults to 0 .
|
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
name | Yes | QName | The name of the field. |
label | No | SubstitutionExpr | A label for the field. |
start | No | number | The one-based starting position of the field in the record. If it is not specified, it defaults to the end of the previous field. |
width | Yes | SubstitutionExpr | The width of the field. |
trim | No | true|false | Indicates whether to trim leading and trailing whitespace. The default is true |
trimLeading | No | true|false | Indicates whether to trim leading whitespace. The default is true |
trimTrailing | No | true|false | Indicates whether to trim trailing whitespace. The default is true |
justify | No | "left","right", or "center" | The alignment rule used for formatting values into a field of fixed width. The default is "left". |
padCharacter | No | Character | The pad character used for formatting values into a field of fixed width, e.g., a space or zero. The default is a space. |
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>
sx:recordComposition — Deprecated in version 1.1.2, aliased to sx:combinePhysicalRecords
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent | |
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to
true |
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to
startTest .
|
suppressRDW | No | true|false | Suppress the 4-byte record descriptor word (RDW) from the front of
the logical record, defaults to false .
|
Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements
One sx:metaRecord element.
sx:recordDelimiter — Separate records
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
start | No | SubstitutionExpr | A string of one or more characters that identifies the beginning of a record. If omitted, the record begins past the end of the previous record, or the beginning of the file. |
end | No | SubstitutionExpr | A string of one or more characters that identifies the end of a record. |
value | No | SubstitutionExpr | Same as end . |
continuation | No | SubstitutionExpr | A string of one or more characters that indicates a continuation character, which allows a record to be extended onto the next line. |
continuationSequence | No | SubstitutionExpr | The continuation + delimiter. |
escapeCharacter | No | Character | An escape character used to escape the delimiter. |
The record delimiter indicates the end of the record.
The following special encodings may appear in a record delimiter or continuation value.
You can also use numerical entity references to specify delimiter values, e.g. 
 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.
sx:repeatDelimiter — Separate repeating groups within a segment
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
start | No | SubstitutionExpr | A string of one or more characters that identifies the beginning of a segment separated by start-end delimiters. |
end | No | SubstitutionExpr | A string of one or more characters that identifies the end of a segment separated by start-end delimiters. |
value | No | SubstitutionExpr | A string of one or more characters that indicates the end of a segment within a repeating group. |
escapeCharacter | No | Character | An escape character used to escape the delimiter. |
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.
You can also use numerical entity references to specify delimiter values, e.g. 	 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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent | |
count | No | SubstitutionExpr | A fixed number of repeating tagged fields. |
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.
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"
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent | |
name | Yes | QName | The name of the repeating group field. |
start | No | SubstitutionExpr | The (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. |
count | No | SubstitutionExpr | A fixed number of repeating records. |
Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements
A sx:flatRecordType element, or a sx:flatRecordTypeChoice element.
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.
sx:segmentComposition — Deprecated in 1.1.2, aliased to sx:mergePhysicalSegments
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent | |
startTest | No | XPath Boolean Expr | XPath boolean expression to test for start of grouping. Defaults to
true |
endTest | No | XPath Boolean Expr | XPath boolean expression to test for end of grouping. Defaults to
startTest .
|
suppressRDW | No | true|false | Suppress the 4-byte record descriptor word (RDW) from the front of
the logical record, defaults to false .
|
Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements
One sx:metaRecord element.
sx:segmentDelimiter — Separate a record into segments containing repeating groups
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
start | No | SubstitutionExpr | A string of one or more characters that identifies the beginning of a segment separated by start-end delimiters. |
end | No | SubstitutionExpr | A string of one or more characters that identifies the end of a segment separated by start-end delimiters. |
value | No | SubstitutionExpr | A string of one or more characters that indicates the end of a segment. |
escapeCharacter | No | Character | An escape character used to escape the delimiter. |
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.
You can also use numerical entity references to specify delimiter values, e.g. 	 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.
sx:separator — Abstract element standing for any separator
This is an abstract element that allows us to refer generically to any specialization of
sx:separator
, such as sx:whitespaceSeparator.
sx:subfieldDelimiter — Separate values within a field
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
value | No | SubstitutionExpr | A string of one or more characters that indicates the end of a value in a multivalued field. |
escapeCharacter | No | Character | An escape character used to escape the delimiter. |
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.
You can also use numerical entity references to specify delimiter values, e.g. 	 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.
sx:vbsFlatRecordType — Variable Block Segment (VBS) record type
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
flat file option attributes | No | Standard flat file options, may be overriden in a descendent |
Optionally, flat file option elements. These apply to the current and descendent elements, if applicable they may be overriden in descendent elements
One or more specializations of the abstract sx:flatRecordField element, including sx:positionalField, sx:binaryField, sx:integerField and sx:delimitedField. If positional and delimited fields are mixed, the positional fields should precede the delimited fields.
One sx:mergePhysicalSegments element.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
class | Yes | Java class | The name of a Java class that implements com.servingxml.components.sql.JdbcConnectionPool . |
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 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) { } } }
sx:jdbcConnectionPool — Abstract element standing for a JDBC connection pool
Name | Required | Value | Description |
---|---|---|---|
ref | Yes | QName | This attribute is used to reference the id of a JDBC connection pool. |
This is an abstract element that allows us to refer generically to any specialization of
sx:jdbcConnectionPool
, such as sx:sqlConnectionPool.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
batchSize | No | QName | The batch size. Defaults to 100. |
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
driver | Yes | Java class | The class name of the JDBC driver. |
databaseUrl | Yes | URL | The JDBC database URL. |
user | No | String | The database user name. |
password | No | String | The database password. |
minConnections | No | Number | The minimum number of connections to keep in the pool. The default is zero. |
maxConnections | No | Number | The maximum number of connections to keep in the pool. The default is any number. |
testStatement | No | String | A statement to test the liveness of the database before obtaining a connection. |
sx:sqlPrepare — Prepare SQL statement
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}.
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.
sx:sqlQuery — SQL query
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | The record type of the SQL query. Defaults to "record" |
trim | No | true|false | Indicates whether to trim both leading and trailing whitespace from all returned values. Defaults to false .
(For backwards compatability, "yes"/"no" is also supported.)
|
trimLeading | No | true|false | Indicates whether to trim leading whitespace from all returned values. Defaults to false .
(For backwards compatability, "yes"/"no" is also supported.)
|
trimTrailing | No | true|false | Indicates whether to trim trailing whitespace from all returned values. Defaults to false .
(For backwards compatability, "yes"/"no" is also supported.)
|
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.
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.
Note that data values resulting from a SQL query are mapped to XML Schema types according to the rules given in XML Schema types.
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recordType | No | QName | Apply updates to records of this record type. Defaults to all records. |
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.
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>
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.
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>
sx:sqlUpdateDatabase — Abstract element standing for a SQL update
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.
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
field | Yes | QName | The name of a repeating group field whose subrecords are to be written to the database. |
Optionally, any number of sx:parameter elements.
Any number of sx:sqlUpdateDatabase elements.
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>
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.
This instruction validates individual records as they are read in from a flat file or SQL source, and discards records when errors are encountered.
Example 92. Validating individual records in the incoming countries flat file.
<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>
<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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
message | No | SubstitutionExpr | A message indicating the error if validation fails, defaults to the message provided by the MSV validator. |
This instruction validates the XML output as it is produced, and will abort processing if an error is encountered.
Example 93. Validating the countries document.
<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>
<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>
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
mimeType | No | string | The MIME type of the output, which must be a supported FOP MIME type. Defaults to "application/pdf". |
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>
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.
jm:attachment — Attachment
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
filename | No | SubstitutionExpr | The name of the attached file. |
jm:mailAccount — Mail account
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
smtpHost | Yes | host | The smtp host. |
jm:message — Message
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
smtpHost | Yes | host | The smtp host. |
itemizedlist>
jm:part — MIME part
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
type | No | type code | The type of a part. The only allowed value is "alternative" |
jm:sender — Sender
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
displayName | No | String | The display name for the owner of the account. |
emailAddess | Yes | address | The email address of the sender. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
subject | Yes | String | The subject of the message. |
to | Yes | SubstitutionExpr | A comma separated list of email addresses of recipients. |
cc | Yes | SubstitutionExpr | A comma separated list of email addresses of recipients. |
itemizedlist>
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>
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.
edt:ftpClient — FTP client
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
host | Yes | String | Host name. |
port | No | Number | The port number, defaults to 21. |
user | Yes | String | The user name. |
password | No | String | The password. |
remoteSiteCommand | No | String | Optional remote site command. |
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
recurse | No | true|false | Set to true to recurse through a directory tree, false otherwise. Defaults to "false."
(For backwards compatability, yes/no is also supported.) |
maxItems | No | Number | The maximum number of directory items to read. |
directory | No | SubstitutionExpr | The remote directory. Defaults to the current directory on the remote server. |
Each record will have type
Each record will contain the following fields:
Name | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
transferType | No | binary or ascii | The transfer type, defaults to ascii. |
remoteDir | No | SubstitutionExpr | Deprecated - use remoteDirectory instead. |
remoteDirectory | No | SubstitutionExpr | The remote directory. |
remoteFile | SubstitutionExpr | String | The name of the remote output file, may contain parameters in the form {$myParam}. |
localDir | No | SubstitutionExpr | The local directory. |
localFile | No | SubstitutionExpr | The local file to write to before sending it to the remote directory. Defaults to a timestamped temporary file. |
deleteLocalFile | No | true|false | Delete the local file after processing the remote file. Defaults to false .
(For backwards compatability, yes/no is also supported.) |
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
transferType | No | binary or ascii | The transfer type, defaults to ascii. |
remoteDir | No | SubstitutionExpr | Deprecated - use remoteDirectory instead. |
remoteDirectory | No | SubstitutionExpr | The remote directory. |
remoteFile | Yes | SubstitutionExpr | The name of the remote input file, may contain parameters in the form {$myParam}. |
localDir | No | SubstitutionExpr | The local directory. |
localFile | No | SubstitutionExpr | The local file to write to before reading its content. Defaults to a timestamped temporary file. |
deleteLocalFile | No | true|false | Delete the local file after processing the remote file. Defaults to false .
(For backwards compatability, yes/no is also supported.) |
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>
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 | Required | Value | Description |
---|---|---|---|
idref-attributes | No | Common id ref attributes. | |
documentBase | No | SubstitutionExpr | This attribute is used to explicitly set the the static context of the query. The base can be relative, in which case it is resolved relative to xml:base, if in scope, or otherwise the location of the resources script. |
Optionally, an sx:content specialization, such as a sx:document, sx:recordContent or sx:transform element, to specify the initial context item.
Either an sx:streamSource element to load the query, or an sx:stringable element to specify the query inline (usually a sx:preserveMarkup element.)
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.
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>
Comma separated values (CSV).
The Multipurpose Internet Mail Extension (MIME) type, which identifies the type of document.
A qName, or a wildcard (*),or a space separated list of qNames.
NCName stands for "no colon name." An example is "books."
QName stands for "qualified name." An example is "myns:books."
Regular expression.
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.
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']
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}"
A short string that stands for the name or address of a resource.
Table A.1. Supported XML Schema Types
XML Schema Type | |
---|---|
Character types | xs:string |
Numeric types | xs:byte |
xs:integer | |
xs:long | |
xs:float | |
xs:double | |
xs:decimal | |
Date types | xs:dateTime |
xs:date | |
xs:time | |
Bit data types | xs:boolean |
xs:hexBinary |
Table A.2. Supported JDBC Data Type Mappings
JBC Data Type | XML Schema Type | |
---|---|---|
Character types | CHAR | xs:string |
VARCHAR | xs:string | |
LONGVARCHAR | xs:string | |
CLOB | xs:string | |
Numeric types | TINYINT | xs:byte |
SMALLINT | xs:short | |
INTEGER | xs:integer | |
BIGINT | xs:long | |
BIGINT | xs:long | |
FLOAT | xs:float | |
DOUBLE | xs:double | |
BIGINT | xs:long | |
DECIMAL | xs:decimal | |
NUMERIC | xs:decimal | |
Date types | TIMESTAMP | xs:dateTime |
DATE | xs:date | |
TIME | xs:time | |
Bit data types | BIT | xs:boolean |
BINARY | xs:hexBinary | |
VARBINARY | xs:hexBinary | |
LONGVARBINARY | xs:hexBinary |
Table B.1. Deprecated and removed elements
Element | Change | Version changed | Replace with | Comment |
---|---|---|---|---|
sx:composeRecord | Deprecated | 1.1.2 | sx:combineRecords | |
sx:decomposeRecord | Deprecated | 1.1.2 | sx:splitRecord | |
sx:recordComposition | Deprecated | 1.1.2 | sx:combinePhysicalRecords | |
sx:segmentConcatenation | Deprecated | 1.1.2 | sx:mergePhysicalSegments | |
sx:repeatingSegment | Removed | 1.2.0 | sx:repeatingGroup | |
sx:replaceRecordFilter | Deprecated | 1.0.2 | sx:replaceRecord | |
sx:defaultFieldMapping | Deprecated | 1.0.0 | sx:defaultFieldElementMap | |
sx:escapeVariables | Deprecated | 1.0.0 | sx:escapeSubstitutions | |
sx:spannedFlatRecordType | Deprecated | 1.0.0 | sx:vbsFlatRecordType | |
sx:xmlRecordReader | Deprecated | 1.0.0 | sx:subtreeRecordReader | |
sx:validateRecord | Deprecated | 1.0.0 | sx:recordValidator | |
sx:validateField | Deprecated | 1.0.0 | sx:fieldValidator | |
sx:insertContent | Deprecated | 0.9.3 | sx:nestedContent | |
sx:segmentMapping | Deprecated | 0.9.3 | sx:subrecordMapping | |
sx:replace | Deprecated | 0.9.2 | sx:findAndReplace | |
sx:taggedFlatRecordField | Removed | 0.9.0 | sx:flatRecordField | |
sx:tagDelimiter | Deprecated | 0.9.0 | sx:nameDelimiter | |
sx:taggedDelimitedField | Deprecated | 0.9.0 | sx:delimitedNamedField | |
sx:repeatingTaggedField | Deprecated | 0.9.0 | sx:repeatingField | |
sx:repeatingSegment | Deprecated | 0.8.4 | sx:repeatingGroup | |
sx:aggregateRecord | Deprecated | 0.8.3 | sx:combineRecords | |
sx:recordAggregator | Deprecated | 0.8.2 | sx:combineRecords | |
sx:subtreeRecordMap | Deprecated | 0.8.1 | sx:flattenSubtree | |
sx:documentFragment | Deprecated | 0.8.1 | sx:nestedContent | |
sx:removeEmptyElementFilter | Deprecated | 0.8.0 | sx:removeEmptyElements | |
sx:aggregate | Deprecated | 0.8.1 | sx:nestedContent | |
sx:recordTest | Deprecated | 0.8.0 | sx:recordRestriction | |
sx:regexFieldCriteria | Deprecated | 0.8.0 | sx:fieldRestriction | |
sx:startGroup | Deprecated | 0.6.5 | startTest | The test attribute of sx:startGroup"
has the same meaning as the startTest attribute
attribute of sx:innerGroup and sx:outerGroup .
When converting, this value remains the same. |
sx:endGroup | Deprecated | 0.6.5 | endTest attribute | The test attribute of sx:endGroup is applied to the "current" record,
and identifies the last record (inclusive) of a group. Consequently, it usually needs to test the "next" record. The endTest
attribute, by contrast, is applied to the "next" record. When converting, a test against the "current" record must be changed
to a test against the "previous" record, and a test against the "next" record must be changed to a test against the "current" record. |
msv:msvFilter | Deprecated | 0.6.4 | msv:schemaValidator | |
sx:discardFilter | Deprecated | 0.6.2 | sx:discardHandler | sx:discardFilter came before a sequence of filters and writers;
sx:discardHandler comes after a sequence of filters and writers |
sx:date | Deprecated | 0.6.1 | sx:currentDateTime and sx:formatDateTime | |
sx:xmlEmitter | Deprecated | 0.6.1 | sx:xsltSerializer | |
sx:customEmitter | Deprecated | 0.6.1 | sx:customSerializer | |
fop:foEmitter | Removed | 0.6.1 | fop:foSerializer | |
sx:commentSymbol | Deprecated | 0.6.0 | sx:commentStarter | |
sx:restrictRecordType | Deprecated | 0.6.0 | sx:recordRestriction | |
sx:restrictField | Deprecated | 0.6.0 | sx:fieldRestriction | |
sx:subtreeFilter | Deprecated | 0.6.0 | sx:processSubtree | |
sx:processRecordFilter | Deprecated | 0.6.0 | sx:processRecord | |
sx:crcFlatFileSignature | Deprecated | 0.5.5 | sx:flatFileSignature | |
sx:sizeFlatFileSignature | Deprecated | 0.5.5 | sx:flatFileSignature | |
sx:processRecords | Deprecated | 0.5.3 | sx:recordStream | |
sx:msvRecordFilter | Deprecated | 0.5.2 | msv:recordValidator | |
sx:recordSubtreeMap | Deprecated | 0.5.0 | sx:transformRecord | |
sx:writeRecords | Deprecated | 0.5.0 | sx:recordStream | |
sx:documentSubtreeMap | Deprecated | 0.5.0 | sx:onSubtree | |
sx:style | Deprecated | 0.5.0 | sx:xslt | |
Record filter children of record reader | Removed | 0.4.2 | Record filter siblings of record reader | Discouraged since 0.4.0. Examples were changed except for sx:directoryReader examples (now updated.) |
sx:flatFileContent | Removed | 0.4.2 | sx:recordContent and sx:flatFileReader | Deprecated since 0.1.3. |
sx:processFragmentFilter | Deprecated | 0.3.4 | sx:processSubtree | |
sx:documentFragmentContentMap | Deprecated | 0.3.4 | sx:onSubtree | |
sx:documentFragmentRecordMap | Deprecated | 0.3.4 | sx:flattenSubtree | |
sx:documentFragmentFieldMap | Deprecated | 0.3.4 | sx:subtreeFieldMap | |
sx:documentRecordMap | Removed | 0.1.8 | sx:onSubtree | |
sx:element | Deprecated | 0.3.2 | sx:elementMap | |
sx:fieldSetElementMap | Deprecated | 0.3.2 | sx:defaultFieldElementMap | |
sx:flowFilter | Deprecated | 0.3.2 | sx:processSubtree | |
sx:flowRecordFilter | Deprecated | 0.3.2 | sx:processRecord | |
sx:subrecordFilter | Deprecated | 0.3.0 | See the edi example | |
sx:taskRunnerFilter | Deprecated | 0.3.0 | sx:processSubtree | |
sx:taskRunnerRecordFilter | Deprecated | 0.3.0 | sx:processRecord | |
sx:flatFileRecordType | Deprecated | 0.2.5 | sx:flatRecordType | |
sx:chooseGroup | Deprecated | 0.2.5 | sx:groupChoice | |
sx:transformerSettings | Deprecated | 0.2.5 | sx:xsltConfiguration | |
sx:subtaskFilter | Deprecated | 0.2.4 | sx:processSubtree | |
sx:subtaskRecordFilter | Deprecated | 0.2.4 | sx:processRecord | |
sx:processDocument | Removed | 0.3.0 | Omit, sx:transform is okay. | |
sx:currentRecordFilter | Deprecated | 0.2.0 | sx:processRecord | |
sx:documentFragmentFilter | Deprecated | 0.2.0 | sx:processSubtree | |
sx:jaxpConfiguration | Deprecated | 0.2.0 | sx:xsltConfiguration | |
sx:documentFragmentFilter | Deprecated | 0.1.8 | sx:processSubtree | |
sx:pathFieldMap | Removed | 0.1.8 | sx:subtreeFieldMap | |
sx:expirySettings | Removed | 0.1.8 | sx:expiryOptions | |
sx:pathRecordMap | Removed | 0.1.8 | sx:onSubtree | |
sx:customSerializer | Removed | 0.1.7 | sx:customSerializer | |
fop:fopSerializer | Removed | 0.1.7 | fop:foSerializer | |
sx:customProperty | Deprecated | 0.1.7 | sx:property | |
sx:taskRecordFilter | Deprecated | 0.1.7 | sx:processRecord | |
sx:saxParser | Deprecated | 0.1.7 | sx:saxReader | |
sx:removeEmptyElements | Deprecated | 0.1.6 | sx:removeEmptyElements | |
sx:customXmlFilter | Deprecated | 0.1.6 | sx:saxFilter | |
sx:emptyContent | Deprecated | 0.1.6 | sx:emptyDocument | |
sx:flatFileLayout | Deprecated | 0.1.6 | sx:flatFile | |
sx:jdbcConnectionPool | Made abstract | 0.1.6 | sx:sqlConnectionPool | Old version still supported. |
sx:mailOutput | Removed | 0.1.6 | jm:sendMail | |
sx:readerWriterRecordFilter | Removed | 0.1.6 | sx:processRecord | |
sx:recordOutput | Deprecated | 0.1.6 | sx:writeRecords | |
sx:restrictFieldFilter | Deprecated | 0.1.6 | sx:fieldRestriction | |
sx:streamContent | Deprecated | 0.1.6 | sx:document | |
sx:streamOutput | Deprecated | 0.1.6 | sx:serialize | |
sx:suppressEmptyElementFilter | Deprecated | 0.1.6 | sx:removeEmptyElements | |
sx:delimitedFieldType | Deprecated | 0.1.4 | sx:delimitedField | |
sx:flatFileRecord | Deprecated | 0.1.4 | sx:flatFileBody | |
sx:positionalFieldType | Deprecated | 0.1.4 | sx:positionalField | |
sx:field | Deprecated | 0.1.3 | sx:positionalField or sx:delimitedField | |
sx:flatFileContent | Deprecated | 0.1.3 | sx:recordContent | Use a sx:flatFileReader child element. |
sx:sqlContent | Removed | 0.1.3 | sx:recordContent | Use a sx:sqlReader child element |
Table B.2. Deprecated and removed attributes
Element | Attribute | Change | Version changed | Replace with |
---|---|---|---|---|
sx:customJdbcConnectionPool | className | Deprecated | 0.1.6 | class |
sx:customRecordFilter | className | Deprecated | 0.1.6 | class |
sx:saxFilter (saxFilter) | className | Deprecated | 0.1.6 | class |
sx:dynamicContent | className | Deprecated | 0.1.6 | class |
sx:customRecordFilter | classHandler | Deprecated | 0.1.5 | class |
sx:saxFilter (sx:saxFilter) | classHandler | Deprecated | 0.1.5 | class |
sx:dynamicContent | classHandler | Deprecated | 0.1.5 | class |