etl.dtd: Elements - Entities - Source | Intro - Index
FRAMES / NO FRAMES

Scriptella ETL File DTD

Usage: <!DOCTYPE etl SYSTEM "http://scriptella.javaforge.com/dtd/etl.dtd">

 Copyright 2006-2012 The Scriptella Project Team.

 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

      http://www.apache.org/licenses/LICENSE-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.



<etl> Root element

Root element of Scriptella XML file.

Example:
A simple example of the script file with only one connection obtained via JNDI bound datasource.

<etl>
    <connection driver="jndi" url="java:projectDS"/>
    <script>
        INSERT INTO Test VALUES (1, "One")
    </script>
</etl>

<etl>'s children
NameCardinality
connectionAny number
descriptionOne or none
propertiesOne or none
queryAny number
scriptAny number
Element's model:

(description?, properties?, connection*, (script*, query*)*)


<description> Child of etl

Contains description of ETL file.


<properties> Child of etl

The properties element contains a set of properties available for script elements. The content of this element conforms to format supported by java.util.Properties. This element may contain plain text or includes.

Example:

<properties>
    #standard properties syntax
    table.size=10
    tmp=c\:\\temp\\
    #including content from external properties file
    <include href="etl.properties"/>
</properties>

<properties>'s children
NameCardinality
includeAny number
Element's model:

(#PCDATA | include)*


<connection> Child of etl

The connection element specifies connection to a database or other system. This element may contain properties as plain text with includes.

Example:

<connection id="in" driver="com.octetstring.jdbcLdap.sql.JdbcLdapDriver"
            url="jdbc:ldap://localhost:389/dc=scriptella"
            user="cn=root,dc=scriptella" password="secret">
    SEARCH_SCOPE=subTreeScope
    ignore_transactions=true
</connection>

<connection driver="hsqldb"
            url="jdbc:hsqldb:file:db"
            user="sa" classpath="hsqldb.jar"/>

<connection>'s children
NameCardinality
includeAny number
<connection>'s attributes
NameValuesDefault
catalog
classpath
driverauto
idMatch the ID rules.
lazy-inittrue, falsefalse
password
schema
url
user
Element's model:

(#PCDATA | include)*


@id Attribute of connection

connection identifier. Connection is referenced by id in scripts and queries. For single connection ETL files this attribute is optional.

Possible values: Match the ID rules.


@driver Attribute of connection

driver class name or alias. The default value is "auto", in this case a target driver is guessed from an url attribute.

Default value: auto


@url Attribute of connection

connection url.


@user Attribute of connection

database login


@password Attribute of connection

database password


@catalog Attribute of connection

catalog


@schema Attribute of connection

schema


@classpath Attribute of connection

the classpath to use when loading the driver. Paths are colon/semicolon separated and resolved relative to a directory where ETL file resides. Absolute URLs are also supported, e.g. ftp://server/lib.jar


@lazy-init Attribute of connection

true if connection initialization should be deferred until it is actually used. The default value of false means that connection is initialized on ETL startup.

Possible values: true, false - Default value: false


<fallback> Child of include

The fallback element contains alternate content to be used if the requested resource cannot be found. This element may contain plain text or includes.

Example:

<include href="http://no-such-url/file.txt">
    <fallback> //First fallback
        <include href="localFile.txt>
            <fallback> //If alternative location also failed
                Failed to retrieve full text
            </fallback>
        </include>
    </fallback>
</include>

<fallback>'s children
NameCardinality
includeAny number
Element's model:

(#PCDATA | include)*


<include> Child of query, dialect, properties, connection, script, onerror, fallback

The include element specifies content to include. Concept similar to XInclude.

Examples:

<include href="http://host/file.sql"><fallback>SHUTDOWN</fallback></include>
<include href="db/schema.sql"/>

<include>'s children
NameCardinality
fallbackOne or none
<include>'s attributes
NameValuesDefault
encoding
href
Element's model:

(fallback?)


@href Attribute of include

contains an URI pointing to the file to include. URIs are resolved relative to ETL file.

Required


@encoding Attribute of include

Included text encoding name.


<dialect> Child of query, script, onerror

The dialect element defines a vendor specific script. Scripting elements may contain any number of nested dialects. This element may contain plain text or includes. Example:

<dialect name="oracle" version="10\.">
    //Statements executed only for Oracle 10.x
</dialect>
<dialect name="oracle" exclude="true">
    //Statements executed for any datasource except Oracle
</dialect>

<dialect>'s children
NameCardinality
includeAny number
<dialect>'s attributes
NameValuesDefault
excludetrue, falsefalse
name
version
Element's model:

(#PCDATA | include)*


@name Attribute of dialect

case insensitive regular expression to match vendor name, e.g. .*oracle.*


@version Attribute of dialect

case insensitive regular expression to match vendor version, e.g. 1\.0


@exclude Attribute of dialect

optional attribute to invert the name/version matching. Use exclude="true" to skip content for dialects with specified name and version.

Possible values: true, false - Default value: false


<onerror> Child of script

The onerror element defines fallback script to execute if error occurs. This element may contain plain text or includes.

Example:

<onerror type="SQLException">
    DROP TABLE MYTABLE
</onerror>

Note: Attributes are applied using AND condition, so if you specified

<onerror type="ProviderException" codes="100,200">

so only exceptions with class name *.ProviderException having 100 and/or 200 error code are handled.

<onerror>'s children
NameCardinality
dialectAny number
includeAny number
<onerror>'s attributes
NameValuesDefault
codes
connection-idMatch the IDREF rules.
message
retrytrue, falsefalse
type
Element's model:

(#PCDATA | include | dialect)*


@type Attribute of onerror

Regular expression pattern to match exception type. Partial matching is allowed.


@codes Attribute of onerror

Comma-separated list of vendor codes/sql states. Triggered if any of these codes matches one of the codes reported by driver.


@message Attribute of onerror

Regular expression pattern to match exception message. Partial matching is allowed.


@retry Attribute of onerror

true if statement which caused a problem should be retried after this handler completes.

Possible values: true, false - Default value: false


@connection-id Attribute of onerror

optional connection ID. If omitted, the error handling code will be executed in the context of the current connection.

Possible values: Match the IDREF rules.


<query> Child of etl

The query element is used to specify a query producing a result set. This element may contain queries, scripts, plain text, includes and dialects.

Example:
Queries a table and writes the result into CSV file

<query connection-id="in">
   SELECT * FROM Test WHERE id=?id
   <script connection-id="csv">
        $id,$value
   </script>
</query>

<query>'s children
NameCardinality
dialectAny number
includeAny number
queryAny number
scriptAny number
<query>'s attributes
NameValuesDefault
connection-idMatch the IDREF rules.
idMatch the ID rules.
if
Element's model:

(#PCDATA | include | dialect | query | script)*


@connection-id Attribute of query

references connection by identifier. The value of this attribute is inherited for nested elements. For single connection ETL files the connection-id is optional.

Possible values: Match the IDREF rules.


@if Attribute of query

expression to test. If result of evaluation is true - the element is evaluated, otherwise skipped. Use JEXL syntax for expressions.


@id Attribute of query

script identifier(name).

Possible values: Match the ID rules.


<script> Child of query, etl

The script element is used to specify a script. This element may contain plain text,onerror handlers, includes and dialects.

Example:
Inserts a row into Test table if id>0

<script if="id>0">
    INSERT INTO Test VALUES(?id, ?name)
</script>

<script>'s children
NameCardinality
dialectAny number
includeAny number
onerrorAny number
<script>'s attributes
NameValuesDefault
connection-idMatch the IDREF rules.
idMatch the ID rules.
if
new-txtrue, falsefalse
Element's model:

(#PCDATA | include | dialect | onerror)*


@connection-id Attribute of script

references connection by identifier. The value of this attribute is inherited for nested elements. For single connection ETL files the connection-id is optional.

Possible values: Match the IDREF rules.


@new-tx Attribute of script

true if a new transaction(and extra connection) is required for this element.

Possible values: true, false - Default value: false


@if Attribute of script

expression to test. If result of evaluation is true - the element is evaluated, otherwise skipped. Use JEXL syntax for expressions.


@id Attribute of script

script identifier(name).

Possible values: Match the ID rules.