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

Scriptella ETL File DTD

Usage: <!DOCTYPE etl SYSTEM "http://scriptella.org/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.

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 Name Cardinality connection Any number description One or none properties One or none query Any number script Any number

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

Contains description of ETL file.

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 Name Cardinality include Any number

(#PCDATA | include)*

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 Name Cardinality include Any number

<connection>'s attributes Name Values Default catalog classpath driver auto id Match the ID rules. lazy-init true, false false password schema url user

(#PCDATA | include)*

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 class name or alias. The default value is "auto", in this case a target driver is guessed from an url attribute.

Default value: auto

connection url.

database login

database password

catalog

schema

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

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

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 Name Cardinality include Any number

(#PCDATA | include)*

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 Name Cardinality fallback One or none

<include>'s attributes Name Values Default encoding href

(fallback?)

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

Required

Included text encoding name.

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 Name Cardinality include Any number

<dialect>'s attributes Name Values Default exclude true, false false name version

(#PCDATA | include)*

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

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

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

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 Name Cardinality dialect Any number include Any number

<onerror>'s attributes Name Values Default codes connection-id Match the IDREF rules. message retry true, false false type

(#PCDATA | include | dialect)*

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

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

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

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

Possible values: true, false - Default value: false

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.

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 Name Cardinality dialect Any number include Any number query Any number script Any number

<query>'s attributes Name Values Default connection-id Match the IDREF rules. id Match the ID rules. if

(#PCDATA | include | dialect | query | 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.

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

script identifier(name).

Possible values: Match the ID rules.

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 Name Cardinality dialect Any number include Any number onerror Any number

<script>'s attributes Name Values Default connection-id Match the IDREF rules. id Match the ID rules. if new-tx true, false false

(#PCDATA | include | dialect | onerror)*

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.

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

Possible values: true, false - Default value: false

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

script identifier(name).

Possible values: Match the ID rules.