Starting to rewrite documentation in sphinx
git-svn-id: https://svn.apache.org/repos/asf/db/ddlutils/trunk@1132524 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/pom.xml b/pom.xml
index 997dc65..817a412 100644
--- a/pom.xml
+++ b/pom.xml
@@ -25,7 +25,7 @@
<parent>
<groupId>org.apache</groupId>
<artifactId>apache</artifactId>
- <version>8</version>
+ <version>9</version>
</parent>
<groupId>org.apache.ddlutils</groupId>
<artifactId>ddlutils</artifactId>
@@ -278,4 +278,25 @@
</build>
</profile>
</profiles>
+
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-project-info-reports-plugin</artifactId>
+ <version>2.4</version>
+ <reportSets>
+ <reportSet>
+ <reports>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ <plugin>
+ <groupId>org.tomdz.maven</groupId>
+ <artifactId>sphinx-maven-plugin</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ </plugin>
+ </plugins>
+ </reporting>
</project>
diff --git a/src/site/sphinx/_theme/ddlutils/globaltoc.html b/src/site/sphinx/_theme/ddlutils/globaltoc.html
new file mode 100644
index 0000000..c27569a
--- /dev/null
+++ b/src/site/sphinx/_theme/ddlutils/globaltoc.html
@@ -0,0 +1,11 @@
+{#
+ basic/globaltoc.html
+ ~~~~~~~~~~~~~~~~~~~~
+
+ Sphinx sidebar template: global table of contents.
+
+ :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+ :license: BSD, see LICENSE for details.
+#}
+<h3>{{ _('All Topics') }}</h3>
+{{ toctree() }}
diff --git a/src/site/sphinx/_theme/ddlutils/static/ddlutils.css_t b/src/site/sphinx/_theme/ddlutils/static/ddlutils.css_t
new file mode 100644
index 0000000..5077995
--- /dev/null
+++ b/src/site/sphinx/_theme/ddlutils/static/ddlutils.css_t
@@ -0,0 +1,402 @@
+/*
+ * ddlutils.css_t
+ * ~~~~~~~~~~~~
+ *
+ * Adapted from celery's CSS at https://github.com/ask/celery
+ * :copyright: Copyright 2010 by Armin Ronacher.
+ * :license: BSD, see LICENSE for details.
+ */
+
+{% set page_width = 940 %}
+{% set sidebar_width = 220 %}
+{% set body_font_stack = "'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', 'Verdana', sans-serif" %}
+{% set headline_font_stack = "'Ubuntu', " ~ font_family %}
+{% set code_font_stack = "'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace" %}
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+ font-family: {{ body_font_stack }};
+ font-size: 17px;
+ background-color: white;
+ color: #000;
+ margin: 30px 0 0 0;
+ padding: 0;
+}
+
+div.document {
+ width: {{ page_width }}px;
+ margin: 0 auto;
+}
+
+div.deck {
+ font-size: 18px;
+}
+
+p.developmentversion {
+ color: red;
+}
+
+div.related {
+ width: {{ page_width - 20 }}px;
+ padding: 5px 10px;
+ background: #F2FCEE;
+ margin: 15px auto 15px auto;
+}
+
+div.documentwrapper {
+ float: left;
+ width: 100%;
+}
+
+div.bodywrapper {
+ margin: 0 0 0 {{ sidebar_width }}px;
+}
+
+div.sphinxsidebar {
+ width: {{ sidebar_width }}px;
+}
+
+hr {
+ border: 1px solid #B1B4B6;
+}
+
+div.body {
+ background-color: #ffffff;
+ color: #3E4349;
+ padding: 0 30px 0 30px;
+}
+
+img.celerylogo {
+ padding: 0 0 10px 10px;
+ float: right;
+}
+
+div.footer {
+ width: {{ page_width - 15 }}px;
+ margin: 10px auto 30px auto;
+ padding-right: 15px;
+ font-size: 14px;
+ color: #888;
+ text-align: right;
+}
+
+div.footer a {
+ color: #888;
+}
+
+div.sphinxsidebar a {
+ color: #444;
+ text-decoration: none;
+ border-bottom: 1px dashed #DCF0D5;
+}
+
+div.sphinxsidebar a:hover {
+ border-bottom: 1px solid #999;
+}
+
+div.sphinxsidebar {
+ font-size: 14px;
+ line-height: 1.5;
+}
+
+div.sphinxsidebarwrapper {
+ padding: 7px 10px;
+}
+
+div.sphinxsidebarwrapper p.logo {
+ padding: 0 0 20px 0;
+ margin: 0;
+}
+
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+ font-family: {{ headline_font_stack }};
+ color: #444;
+ font-size: 24px;
+ font-weight: normal;
+ margin: 0 0 5px 0;
+ padding: 0;
+}
+
+div.sphinxsidebar h4 {
+ font-size: 20px;
+}
+
+div.sphinxsidebar h3 a {
+ color: #444;
+}
+
+div.sphinxsidebar p.logo a,
+div.sphinxsidebar h3 a,
+div.sphinxsidebar p.logo a:hover,
+div.sphinxsidebar h3 a:hover {
+ border: none;
+}
+
+div.sphinxsidebar p {
+ color: #555;
+ margin: 10px 0;
+}
+
+div.sphinxsidebar ul {
+ margin: 10px 0;
+ padding: 0;
+ color: #000;
+}
+
+div.sphinxsidebar input {
+ border: 1px solid #ccc;
+ font-family: {{ body_font_stack }};
+ font-size: 1em;
+}
+
+/* -- body styles ----------------------------------------------------------- */
+
+a {
+ color: #348613;
+ text-decoration: underline;
+}
+
+a:hover {
+ color: #59B833;
+ text-decoration: underline;
+}
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+ font-family: {{ headline_font_stack }};
+ font-weight: normal;
+ margin: 30px 0px 10px 0px;
+ padding: 0;
+}
+
+div.body h1 { margin-top: 0; padding-top: 0; font-size: 200%; }
+div.body h2 { font-size: 180%; }
+div.body h3 { font-size: 150%; }
+div.body h4 { font-size: 130%; }
+div.body h5 { font-size: 100%; }
+div.body h6 { font-size: 100%; }
+
+div.body h1 a.toc-backref,
+div.body h2 a.toc-backref,
+div.body h3 a.toc-backref,
+div.body h4 a.toc-backref,
+div.body h5 a.toc-backref,
+div.body h6 a.toc-backref {
+ color: inherit!important;
+ text-decoration: none;
+}
+
+a.headerlink {
+ color: #ddd;
+ padding: 0 4px;
+ text-decoration: none;
+}
+
+a.headerlink:hover {
+ color: #444;
+ background: #eaeaea;
+}
+
+div.body p, div.body dd, div.body li {
+ line-height: 1.4em;
+}
+
+div.admonition {
+ background: #fafafa;
+ margin: 20px -30px;
+ padding: 10px 30px;
+ border-top: 1px solid #ccc;
+ border-bottom: 1px solid #ccc;
+}
+
+div.admonition p.admonition-title {
+ font-family: {{ headline_font_stack }};
+ font-weight: normal;
+ font-size: 24px;
+ margin: 0 0 10px 0;
+ padding: 0;
+ line-height: 1;
+}
+
+div.admonition p.last {
+ margin-bottom: 0;
+}
+
+div.highlight{
+ background-color: white;
+}
+
+dt:target, .highlight {
+ background: #FAF3E8;
+}
+
+div.note {
+ background-color: #eee;
+ border: 1px solid #ccc;
+}
+
+div.seealso {
+ background-color: #ffc;
+ border: 1px solid #ff6;
+}
+
+div.topic {
+ background-color: #eee;
+}
+
+div.warning {
+ background-color: #ffe4e4;
+ border: 1px solid #f66;
+}
+
+p.admonition-title {
+ display: inline;
+}
+
+p.admonition-title:after {
+ content: ":";
+}
+
+pre, tt {
+ font-family: {{ code_font_stack }};
+ font-size: 0.9em;
+}
+
+img.screenshot {
+}
+
+tt.descname, tt.descclassname {
+ font-size: 0.95em;
+}
+
+tt.descname {
+ padding-right: 0.08em;
+}
+
+img.screenshot {
+ -moz-box-shadow: 2px 2px 4px #eee;
+ -webkit-box-shadow: 2px 2px 4px #eee;
+ box-shadow: 2px 2px 4px #eee;
+}
+
+table.docutils {
+ border: 1px solid #888;
+ -moz-box-shadow: 2px 2px 4px #eee;
+ -webkit-box-shadow: 2px 2px 4px #eee;
+ box-shadow: 2px 2px 4px #eee;
+}
+
+table.docutils td, table.docutils th {
+ border: 1px solid #888;
+ padding: 0.25em 0.7em;
+}
+
+table.field-list, table.footnote {
+ border: none;
+ -moz-box-shadow: none;
+ -webkit-box-shadow: none;
+ box-shadow: none;
+}
+
+table.footnote {
+ margin: 15px 0;
+ width: 100%;
+ border: 1px solid #eee;
+ background: #fdfdfd;
+ font-size: 0.9em;
+}
+
+table.footnote + table.footnote {
+ margin-top: -15px;
+ border-top: none;
+}
+
+table.field-list th {
+ padding: 0 0.8em 0 0;
+}
+
+table.field-list td {
+ padding: 0;
+}
+
+table.footnote td.label {
+ width: 0px;
+ padding: 0.3em 0 0.3em 0.5em;
+}
+
+table.footnote td {
+ padding: 0.3em 0.5em;
+}
+
+dl {
+ margin: 0;
+ padding: 0;
+}
+
+dl dd {
+ margin-left: 30px;
+}
+
+blockquote {
+ margin: 0 0 0 30px;
+ padding: 0;
+}
+
+ul {
+ margin: 10px 0 10px 30px;
+ padding: 0;
+}
+
+pre {
+ background: #F0FFEB;
+ padding: 7px 10px;
+ margin: 15px 0;
+ border: 1px solid #C7ECB8;
+ border-radius: 2px;
+ -moz-border-radius: 2px;
+ -webkit-border-radius: 2px;
+ line-height: 1.3em;
+}
+
+tt {
+ background: #F0FFEB;
+ color: #222;
+ /* padding: 1px 2px; */
+}
+
+tt.xref, a tt {
+ background: #F0FFEB;
+ border-bottom: 1px solid white;
+}
+
+a.reference {
+ text-decoration: none;
+ border-bottom: 1px dashed #DCF0D5;
+}
+
+a.reference:hover {
+ border-bottom: 1px solid #6D4100;
+}
+
+a.footnote-reference {
+ text-decoration: none;
+ font-size: 0.7em;
+ vertical-align: top;
+ border-bottom: 1px dashed #DCF0D5;
+}
+
+a.footnote-reference:hover {
+ border-bottom: 1px solid #6D4100;
+}
+
+a:hover tt {
+ background: #EEE;
+}
\ No newline at end of file
diff --git a/src/site/sphinx/_theme/ddlutils/theme.conf b/src/site/sphinx/_theme/ddlutils/theme.conf
new file mode 100644
index 0000000..4db9e99
--- /dev/null
+++ b/src/site/sphinx/_theme/ddlutils/theme.conf
@@ -0,0 +1,6 @@
+[theme]
+inherit = basic
+stylesheet = ddlutils.css
+
+[options]
+nosidebar = false
\ No newline at end of file
diff --git a/src/site/sphinx/ant-tasks.rst b/src/site/sphinx/ant-tasks.rst
new file mode 100644
index 0000000..833598d
--- /dev/null
+++ b/src/site/sphinx/ant-tasks.rst
@@ -0,0 +1,103 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+.. _`Ant`: http://ant.apache.org/
+
+Ant tasks
+=========
+
+DdlUtils comes with two `Ant`_ tasks that allow you to manipulate the
+database structure, insert data into the database, and to dump the database structure and
+data contained in it, to XML.
+
+Lets see examples for how to use them::
+
+ <path id="runtime-classpath">
+ <fileset dir="lib">
+ <include name="**/*.jar"/>
+ <include name="**/*.zip"/>
+ </fileset>
+ </path>
+
+ <target name="database-setup"
+ description="Creates the database and inserts data">
+ <taskdef name="ddlToDatabase"
+ classname="org.apache.ddlutils.task.DdlToDatabaseTask">
+ <classpath refid="runtime-classpath"/>
+ </taskdef>
+ <ddlToDatabase>
+ <database url="jdbc:postgresql://localhost/test"
+ driverClassName="org.postgresql.Driver"
+ username="someuser"
+ password="somepassword"/>
+ <fileset dir="src/schema">
+ <include name="project-schema.xml"/>
+ </fileset>
+
+ <createDatabase failonerror="false"/>
+ <writeSchemaToDatabase/>
+ <writeDataToDatabase datafile="src/data/data.xml"/>
+ </ddlToDatabase>
+ </target>
+
+This snippet essentially uses the ``DdlToDatabaseTask`` task to create the a PostgreSQL
+database at ``//localhost/test``, establish the database structure (tables etc.)
+defined in the file ``src/schema/project-schema.xml`` in this database, and then
+inserts the data defined in ``src/data/data.xml``.
+
+Required for this to work is that both DdlUtils and the JDBC driver are available
+in the path specified by ``runtime-classpath``. In the above snippet, this path
+contains all JARs and ZIPs in sub-directory ``lib``.
+
+.. note:: Not every database platform supports creation of new databases via JDBC. Please refer to the
+ documentation of the support for the individual databases :doc:`here <database-support>`.
+
+The opposite direction is achieved via the ``DatabaseToDdlTask`` task::
+
+ <path id="runtime-classpath">
+ <fileset dir="lib">
+ <include name="**/*.jar"/>
+ <include name="**/*.zip"/>
+ </fileset>
+ </path>
+
+ <target name="database-dump" description="Dumps the database structure">
+ <taskdef name="databaseToDdl"
+ classname="org.apache.ddlutils.task.DatabaseToDdlTask">
+ <classpath refid="runtime-classpath"/>
+ </taskdef>
+ <databaseToDdl modelName="MyModel">
+ <database url="jdbc:derby:ddlutils"
+ driverClassName="org.apache.derby.jdbc.EmbeddedDriver"
+ username=""
+ password=""/>
+
+ <writeSchemaToFile outputFile="db-schema.xml"/>
+ <writeDataToFile outputFile="data.xml"/>
+ </databaseToDdl>
+ </target>
+
+Here, the database schema is retrieved via the specified JDBC driver and written
+to the file ``db-schema.xml``. Likewise, the data in the database is written
+to the file ``data.xml``.
+
+.. toctree::
+ :maxdepth: 1
+
+ ddl-to-database-task
+ database-to-ddl-task
+
\ No newline at end of file
diff --git a/src/site/sphinx/api-usage.rst b/src/site/sphinx/api-usage.rst
new file mode 100644
index 0000000..a8e4f97
--- /dev/null
+++ b/src/site/sphinx/api-usage.rst
@@ -0,0 +1,269 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+.. _`Javadoc`: /javadoc/model/
+.. _`DynaBeans`: http://jakarta.apache.org/commons/beanutils/apidocs/index.html?org/apache/commons/beanutils/DynaBean.html
+
+Java API
+========
+
+The model
+---------
+
+At the core of DdlUtils lies the database model in package
+``org.apache.ddlutils.model``. It consists of classes that
+represent the database schema:
+
+.. image:: images/model.png
+ :alt: UML diagram of the database model
+
+Using the appropriate methods on these classes, you can build the
+database model manually, or you read it from XML or from the database
+(see the next paragraphs for details). More info about the classes
+can be found in the `Javadoc`_.
+
+Reading from XML
+----------------
+
+Most of the time you have a schema in an XML file, and you want to
+read it into memory in order to do something with it. This is quite easily
+accomplished with a few lines of code::
+
+ import org.apache.ddlutils.io.DatabaseIO;
+ import org.apache.ddlutils.model.Database;
+
+ ...
+
+ public Database readDatabaseFromXML(String fileName)
+ {
+ return new DatabaseIO().read(fileName);
+ }
+
+Writing to XML
+--------------
+
+Writing a model to XML is just as easy as reading from XML::
+
+ import org.apache.ddlutils.io.DatabaseIO;
+ import org.apache.ddlutils.model.Database;
+
+ ...
+
+ public void writeDatabaseToXML(Database db, String fileName)
+ {
+ new DatabaseIO().write(db, fileName);
+ }
+
+Reading the model from a live database
+--------------------------------------
+
+Reading the database model from a live database is only slightly more involved
+because we first need to create a platform instance via the data source pointing
+to the database::
+
+ import javax.sql.DataSource;
+ import org.apache.ddlutils.Platform;
+ import org.apache.ddlutils.PlatformFactory;
+ import org.apache.ddlutils.model.Database;
+
+ ...
+
+ public Database readDatabase(DataSource dataSource)
+ {
+ Platform platform = PlatformFactory.createNewPlatformInstance(dataSource);
+
+ return platform.readModelFromDatabase("model");
+ }
+
+Changing a database
+-------------------
+
+Changing a database essentially means one of two things: resetting a database to the
+schema defined by the model, or altering the database to have the same model. The key
+difference is that with the latter, data in the database is retained as much as
+possible. Only major changes to the table structure or type-incompatible alterations of
+columns will result in loss of data, most changes will simply retain the data.
+
+.. note:: Whether a change of e.g. a column type affects the data contained in the table, depends
+ on the database that you use. Most databases are able to convert between different
+ datatypes and will apply these conversions when the column type is changed.
+
+Both types of modification differ only in how the SQL is created, the general procedure
+is the same: create the sql and execute it::
+
+ import javax.sql.DataSource;
+ import org.apache.ddlutils.Platform;
+ import org.apache.ddlutils.PlatformFactory;
+ import org.apache.ddlutils.model.Database;
+
+ ...
+
+ public void changeDatabase(DataSource dataSource,
+ Database targetModel,
+ boolean alterDb)
+ {
+ Platform platform = PlatformFactory.createNewPlatformInstance(dataSource);
+
+ if (alterDb)
+ {
+ platform.alterTables(targetModel, false);
+ }
+ else
+ {
+ platform.createTables(targetModel, true, false);
+ }
+ }
+
+.. note:: Databases like Oracle allow for more than one separate schema in one database. To cater
+ for these databases, there are variants of these methods where you can specify the
+ catalog and schema.
+
+Inserting data into a database
+------------------------------
+
+DdlUtils provides a simple way to insert data into the database. For this it uses
+`DynaBeans`_ which are essentially dynamically created beans with variable properties.
+For each table defined by the database model, a so-called dyna class is created that
+represents the table with its columns. Of this dyna class, instances - the dyna beans -
+are then created which can be inserted by DdlUtils into the database::
+
+ import javax.sql.DataSource;
+ import org.apache.commons.beanutils.DynaBean;
+ import org.apache.ddlutils.Platform;
+ import org.apache.ddlutils.PlatformFactory;
+ import org.apache.ddlutils.model.Database;
+
+ ...
+
+ public void insertData(DataSource dataSource,
+ Database database)
+ {
+ Platform platform = PlatformFactory.createNewPlatformInstance(dataSource);
+
+ // "author" is a table of the model
+ DynaBean author = database.createDynaBeanFor("author", false);
+
+ // "name" and "whatever" are columns of table "author"
+ author.set("name", "James");
+ author.set("whatever", new Integer(1234));
+
+ platform.insert(database, author);
+ }
+
+Getting data from a database
+----------------------------
+
+In the same way as inserting data into a database, DdlUtils uses dyna beans
+for retrieving data from the database. You issue a SQL select against the
+database and get dyna beans back. This means that the table that the select
+goes against, has to be part of the database model used by DdlUtils.
+
+In the following sample, the titles of all books in the database are printed
+to stdout::
+
+ import java.util.ArrayList;
+ import java.util.Iterator;
+ import javax.sql.DataSource;
+ import org.apache.commons.beanutils.DynaBean;
+ import org.apache.ddlutils.Platform;
+ import org.apache.ddlutils.PlatformFactory;
+ import org.apache.ddlutils.model.Database;
+ import org.apache.ddlutils.model.Table;
+
+ ...
+
+ public void dumpBooks(DataSource dataSource,
+ Database database)
+ {
+ Platform platform = PlatformFactory.createNewPlatformInstance(dataSource);
+ ArrayList params = new ArrayList();
+
+ params.add("Some title");
+
+ Iterator it = platform.query(database,
+ "select * from book where title = ?",
+ params,
+ new Table[] { database.findTable("book") });
+
+ while (it.hasNext())
+ {
+ DynaBean book = (DynaBean)it.next();
+
+ System.out.println(book.get("title"));
+ }
+ }
+
+There are two things to note in this sample code:
+
+First, we specified so-called query hints in the call to the ``query``. Query hints
+are an array of tables whose columns are used by the query statement. The reason why they
+should be used is that not all databases provide sufficient information in the JDBC result set
+object to determine the table to which a column belongs to. Since this info is need by
+DdlUtils to properly extract the value and convert it to the corresponding Java type, it is
+safer to specify these hints. What DdlUtils does in this case, is to search for a column
+of that name within the specified tables and use the mapping for this column. This of course
+can fail if you use aliases in the query statement (and the JDBC driver handles them in
+a strange way), or if more than one table has a column of this name. But in most cases you'll
+get the expected results.
+
+The other thing to note is that DdlUtils does not parse the query statement. This means that
+if you use delimited identifier mode (i.e. identifiers can contain whitespaces, non-alphanumeric
+characters etc., but they also need to be enclosed in double quotes), then you'll have to
+specify the query statement accordingly - DdlUtils won't do that for you. If you'd like to be
+on the safe side, then you could write the above statement like this::
+
+ import java.util.ArrayList;
+ import java.util.Iterator;
+ import javax.sql.DataSource;
+ import org.apache.commons.beanutils.DynaBean;
+ import org.apache.ddlutils.Platform;
+ import org.apache.ddlutils.PlatformFactory;
+ import org.apache.ddlutils.model.Database;
+ import org.apache.ddlutils.model.Table;
+
+ ...
+
+ public void dumpBooks(DataSource dataSource,
+ Database database)
+ {
+ Platform platform = PlatformFactory.createNewPlatformInstance(dataSource);
+ ArrayList params = new ArrayList();
+ String sql;
+
+ params.add("Some title");
+
+ if (platform.isDelimitedIdentifierModeOn())
+ {
+ sql = "select * from \"book\" where \"title\" = ?";
+ }
+ else
+ {
+ sql = "select * from book where title = ?";
+ }
+
+ Iterator it = platform.query(database,
+ sql,
+ params,
+ new Table[] { database.findTable("book") });
+
+ while (it.hasNext())
+ {
+ DynaBean book = (DynaBean)it.next();
+
+ System.out.println(book.get("title"));
+ }
+ }
diff --git a/src/site/sphinx/conf.py b/src/site/sphinx/conf.py
new file mode 100644
index 0000000..fc17909
--- /dev/null
+++ b/src/site/sphinx/conf.py
@@ -0,0 +1,65 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you 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.
+
+# -*- coding: utf-8 -*-
+
+import sys, os
+
+needs_sphinx = '1.0'
+
+extensions = []
+
+templates_path = ['_templates']
+
+source_suffix = '.rst'
+
+source_encoding = 'utf-8-sig'
+
+master_doc = 'index'
+
+project = u'DdlUtils'
+copyright = u'2011, Thomas Dudziak'
+
+version = '1.1'
+release = '1.1-SNAPSHOT'
+
+exclude_trees = ['.build']
+
+add_function_parentheses = True
+
+pygments_style = 'trac'
+
+master_doc = 'index'
+
+# -- Options for HTML output ---------------------------------------------------
+
+html_theme = 'ddlutils'
+
+html_theme_path = ["_theme"]
+
+html_static_path = ['_static']
+
+html_use_smartypants = True
+
+html_use_index = True
+
+htmlhelp_basename = 'ddlutilsdoc'
+
+html_sidebars = {
+ 'index': ['globaltoc.html', 'relations.html', 'searchbox.html'],
+ '**': ['globaltoc.html', 'relations.html', 'searchbox.html']
+}
\ No newline at end of file
diff --git a/src/site/sphinx/create-database-subtask.rst b/src/site/sphinx/create-database-subtask.rst
new file mode 100644
index 0000000..f9f3afd
--- /dev/null
+++ b/src/site/sphinx/create-database-subtask.rst
@@ -0,0 +1,64 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+createDatabase
+==============
+
+This is the sub task for creating the target database. Note that this is only supported on some database
+platforms. See :doc:`here <database-support>` for details on which platforms support this.
+
+This sub task does not require schema files. Therefore the ``fileset`` subelement and the
+``schemaFile`` attributes can be omitted.
+
+Attributes
+----------
+
+``failOnError``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Specifies whether the execution shall stop if an error has occurred while the task runs.
+
+Subelements
+-----------
+
+``parameter``
+ Specifies a parameter for the creation of the database. These are usually platform specific.
+
+ *Attributes*
+
+ ``name``
+ :Required: yes
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the name of the parameter. See :doc:`the database support documentation <database-support>`
+ for the parameters supported by the individual platforms.
+
+ ``platforms``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: Comma-separated list of platforms where the parameter shall be processed (see
+ ``databaseType`` attribute above for the possible values). For every platform
+ not in this list, the parameter is ignored. If none is given, then the parameter
+ is processed for every platform.
+
+ ``value``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: The parameter value. If none is given, ``null`` is used.
diff --git a/src/site/sphinx/database-support.rst b/src/site/sphinx/database-support.rst
new file mode 100644
index 0000000..f5465e4
--- /dev/null
+++ b/src/site/sphinx/database-support.rst
@@ -0,0 +1,128 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+.. _`JDBC specification`: http://www.oracle.com/technetwork/java/javase/jdbc/index.html
+.. _`Chapter 9: Mapping SQL and Java Types`: http://download.oracle.com/javase/1.4.2/docs/guide/jdbc/getstart/mapping.html#996857
+.. _`JDBC Technology Guide: Getting Started`: http://java.sun.com/j2se/1.4.2/docs/guide/jdbc/getstart/GettingStartedTOC.fm.html
+
+Database support
+================
+
+DdlUtils accesses databases via JDBC, esp. the metadata that JDBC provides, as well as by
+accessing database specific tables and performing database specific SQL. The details of the
+latter can be found in the support documentation for the individual databases.
+
+The main source of information about JDBC is the `JDBC Specification`_, currently for JDBC
+version 3. General information about the JDBC datatypes can also be found in
+`Chapter 9: Mapping SQL and Java Types`_ of the
+`JDBC Technology Guide: Getting Started`_. Please also note that some JDBC types are only
+available in recent versions of the Java platform, e.g. the ``BOOLEAN`` type is only
+available since J2SE version 1.4. These will be usable with DdlUtils only if you're running
+the respective Java version or a newer one.
+
+Here is a short summary of the information about the JDBC data types:
+
+``ARRAY``
+ Represents an array
+
+``BIGINT``
+ 64 bit signed integer (-9223372036854775808 to 9223372036854775807)
+
+``BINARY``
+ Binary data, 254 bytes max
+
+``BIT``
+ 0 or 1
+
+``BLOB``
+ Binary data
+
+``BOOLEAN``
+ Boolean type (``true``, ``false``) in Java 1.4 and above
+
+``CHAR``
+ Fixed length character data, 254 bytes of 8-bit characters max
+
+``CLOB``
+ Character data
+
+``DATALINK``
+ References a file outside of the database but that is managed by it. Maps to ``java.net.URL``.
+ Only available in Java 1.4 and above.
+
+``DATE``
+ Year, month, day
+
+``DECIMAL``
+ Fixed point number, 15 bits for precision (total number of digits) and for scale (number of digits after the decimal point)
+
+``DISTINCT``
+ Represents a distinct value, totally database/JDBC driver dependent
+
+``DOUBLE``
+ Floating point number, 15 bits of mantissa (fractional part)
+
+``FLOAT``
+ Floating point number, 15 bits of mantissa (fractional part)
+
+``INTEGER``
+ 32 bit signed integer (-2147483648 to 2147483647)
+
+``JAVA_OBJECT``
+ Represents an java object, usually a serialized one
+
+``LONGVARBINARY``
+ Binary data, up to 1 GB
+
+``LONGVARCHAR``
+ Character data, up to 1 GB (8-bit characters)
+
+``NULL``
+ Is not specified in detail
+
+``NUMERIC``
+ Usually the same as ``DECIMAL``
+
+``OTHER``
+ Entirely database-specific type
+
+``REAL``
+ Floating point number, 7 bits of mantissa (fractional part)
+
+``REF``
+ Represents a reference to an instance of a SQL structured type. Maps to ``java.sql.Ref``.
+
+``SMALLINT``
+ 16 bit signed integer (-32768 to 32767)
+
+``STRUCT``
+ Represents a structured type, usually created via CREATE TYPE. Maps to ``java.sql.Struct``.
+
+``TIME``
+ Hours, minutes, seconds
+
+``TIMESTAMP``
+ Year, month, day, hours, minutes, seconds, nanoseconds
+
+``TINYINT``
+ 8 bit signed or unsigned integer, -128 to 127 (8 bit signed) or 0 to 254 (8 bit unsigned)
+
+``VARBINARY``
+ Binary data, up to 254 bytes
+
+``VARCHAR``
+ Character data, up to 254 bytes (8-bit characters)
diff --git a/src/site/sphinx/database-to-ddl-task.rst b/src/site/sphinx/database-to-ddl-task.rst
new file mode 100644
index 0000000..1ac70fa
--- /dev/null
+++ b/src/site/sphinx/database-to-ddl-task.rst
@@ -0,0 +1,122 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+.. _`DatabaseMetaData Javadoc`: http://download.oracle.com/javase/1.4.2/docs/api/java/sql/DatabaseMetaData.html#getTables(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String[])
+.. _`Commons DBCP Javadoc`: http://commons.apache.org/dbcp/api-1.4/index.html
+
+DatabaseToDdlTask reference
+===========================
+
+:Class: ``org.apache.ddlutils.task.DatabaseToDdlTask``
+
+This is the container for sub tasks that operate in the direction database -> file, eg.
+that create/drop a schema in the database, insert data into the database. They also
+create DTDs for these data files, and dump the SQL for creating a schema in the database
+to a file.
+
+Attributes
+----------
+
+``catalog``
+ :Required: no
+ :Allowed:
+ :Default: Depends on the database
+ :Meaning: Specifies the catalog(s) to access. This is only necessary for some databases.
+ The pattern is described in the ``getTables`` method in the `DatabaseMetaData Javadoc`_.
+ The special pattern '%' indicates that every catalog shall be used.
+
+``databaseType``
+ :Required: no
+ :Allowed: ``axion``, ``cloudscape``, ``db2``, ``derby``, ``firebird``, ``hsqldb``, ``interbase``,
+ ``maxdb``, ``mckoi``, ``mssql``, ``mysql``, ``mysql5``, ``oracle``, ``oracle9``,
+ ``oracle10``, ``postgresql``, ``sapdb``, ``sybase``
+ :Default:
+ :Meaning: The database type. You should only need to specify this if DdlUtils is not able to
+ derive the setting from the name of the used jdbc driver or the jdbc connection url.
+ If you need to specify this, please post your jdbc driver and connection url combo
+ to the user mailing list so that DdlUtils can be enhanced to support this combo.
+
+``modelName``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the name of the model, e.g. the value of the name attribute in the XML if
+ the ``writeSchemaToFile`` sub-task is used. If none is given, DdlUtils
+ will use the schema name as returned by the database, or ``default`` if
+ the database returned no schema name.
+
+``schema``
+ :Required: no
+ :Allowed:
+ :Default: Depends on the database
+ :Meaning: Specifies the table schema(s) to access. This is only necessary for some databases.
+ The pattern is described in the ``getTables`` method in the `DatabaseMetaData Javadoc`_.
+ The special pattern '%' indicates that every table schema shall be used.
+
+``sortForeignKeys``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``false``
+ :Meaning: Whether DdlUtils shall sort (alphabetically) the foreign keys of a table read from a live
+ database or leave them in the order that they are returned by the database. Note that
+ the sort is case sensitive only if delimied identifier mode is on
+ (``useDelimitedSqlIdentifiers`` is set to ``true``).
+
+``tableTypes``
+ :Required: no
+ :Allowed:
+ :Default: ``TABLE``
+ :Meaning: Specifies the table types to processed. For details and typical table types see
+ the ``getTables`` method in the `DatabaseMetaData Javadoc`_. By default, only tables of type
+ ``TABLE``, eg. user tables, are processed.
+
+``useDelimitedSqlIdentifiers``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``false``
+ :Meaning: Whether DdlUtils shall use delimited (quoted) identifiers (table names, column names etc.)
+ In most databases, undelimited identifiers will be converted to uppercase by the database,
+ and the case of the identifier is ignored when performing any SQL command. Undelimited
+ identifiers can contain only alphanumerical characters and the underscore. Also, no reserved
+ words can be used as such identifiers.
+
+ The limitations do not exist for delimited identifiers. However case of the identifier will be
+ important in every SQL command executed against the database.
+
+Subelements
+-----------
+
+``dataSource``
+ Specifies the connection to the database. This is basically a ``org.apache.commons.dbcp.BasicDataSource``.
+ See the `Commons DBCP Javadoc`_ for the supported properties. Usually you only need to specify
+
+ :``url``: The jdbc connection url
+ :``driverClassName``: The fully qualified class name of the jdbc driver (which must be in the classpath that you used to define the DdlToDatabaseTask task)
+ :``username``: The username
+ :``password``: The password
+
+Subtasks
+--------
+
+.. toctree::
+ :maxdepth: 1
+
+ write-dtd-to-file-subtask
+ write-schema-to-file-subtask
+ write-database-schema-sql-to-file-subtask
+ write-data-to-database-subtask
+ write-data-to-file-subtask
diff --git a/src/site/sphinx/ddl-to-database-task.rst b/src/site/sphinx/ddl-to-database-task.rst
new file mode 100644
index 0000000..eb6e96d
--- /dev/null
+++ b/src/site/sphinx/ddl-to-database-task.rst
@@ -0,0 +1,112 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+.. _`fileset section`: http://ant.apache.org/manual/coretypes/fileset
+.. _`Commons DBCP Javadoc`: http://commons.apache.org/dbcp/api-1.4/index.html
+
+DdlToDatabaseTask reference
+===========================
+
+:Class: ``org.apache.ddlutils.task.DdlToDatabaseTask``
+
+This is the container for sub tasks that operate in the direction file -> database, eg.
+that create/drop a schema in the database, insert data into the database. They also
+create DTDs for these data files, and dump the SQL for creating a schema in the database
+to a file.
+
+Attributes
+----------
+
+``databaseType``
+ :Required: no
+ :Allowed: ``axion``, ``cloudscape``, ``db2``, ``derby``, ``firebird``, ``hsqldb``, ``interbase``,
+ ``maxdb``, ``mckoi``, ``mssql``, ``mysql``, ``mysql5``, ``oracle``, ``oracle9``,
+ ``oracle10``, ``postgresql``, ``sapdb``, ``sybase``
+ :Default:
+ :Meaning: The database type. You should only need to specify this if DdlUtils is not able to derive the setting
+ from the name of the used jdbc driver or the jdbc connection url. If you need to specify this, please
+ post your jdbc driver and connection url combo to the user mailing list so that DdlUtils can be
+ enhanced to support this combo.
+
+``schemaFile``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: The single file that contains the database file. Use this instead of an embedded ``fileset`` if you
+ only have one schema file.
+
+``sortForeignKeys``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``false``
+ :Meaning: Whether DdlUtils shall sort (alphabetically) the foreign keys of a table read from a live database or
+ leave them in the order that they are returned by the database. Note that the sort is case sensitive
+ only if delimited identifier mode is on (``useDelimitedSqlIdentifiers`` is set to ``true``).
+
+``useDelimitedSqlIdentifiers``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``false``
+ :Meaning: Whether DdlUtils shall use delimited (quoted) identifiers (table names, column names etc.) In most
+ databases, undelimited identifiers will be converted to uppercase by the database, and the case of the
+ identifier is ignored when performing any SQL command. Undelimited identifiers can contain only
+ alphanumerical characters and the underscore. Also, no reserved words can be used as such identifiers.
+ The limitations do not exist for delimited identifiers. However case of the identifier will be
+ important in every SQL command executed against the database.
+
+``useInternalDtd``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Whether DdlUtils shall use the embedded DTD for validating the schema XML (if it matches
+ ``http://db.apache.org/torque/dtd/database.dtd``). This is useful for instance for environments where
+ no web access is possible.
+
+``validateXml``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``false``
+ :Meaning: Whether DdlUtils shall validate the schema XML against the DTD.
+
+Subelements
+-----------
+
+``fileset``
+ Specifies the schema files to operate with. For details see the `fileset section`_ in the Ant manual.
+
+``dataSource``
+ Specifies the connection to the database. This is basically a ``org.apache.commons.dbcp.BasicDataSource``.
+ See the `Commons DBCP Javadoc`_ for the supported properties. Usually you only need to specify
+
+ :``url``: The jdbc connection url
+ :``driverClassName``: The fully qualified class name of the jdbc driver (which must be in the classpath that you used to define the DdlToDatabaseTask task)
+ :``username``: The username
+ :``password``: The password
+
+Subtasks
+--------
+
+.. toctree::
+ :maxdepth: 1
+
+ create-database-subtask
+ drop-database-subtask
+ write-dtd-to-file-subtask
+ write-file-schema-to-database-subtask
+ write-schema-sql-to-file-subtask
+ write-data-to-database-subtask
+ write-data-to-file-subtask
diff --git a/src/site/sphinx/download.rst b/src/site/sphinx/download.rst
new file mode 100644
index 0000000..1d07653
--- /dev/null
+++ b/src/site/sphinx/download.rst
@@ -0,0 +1,77 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+.. _`Apache Subversion`: http://subversion.apache.org
+.. _`TortoiseSVN`: http://tortoisesvn.tigris.org
+
+Downloading DdlUtils
+====================
+
+Binary distribution
+-------------------
+
+These are the currently released versions:
+
+`DdlUtils 1.0 <http://www.apache.org/dyn/closer.cgi/db/ddlutils/ddlutils-1.0/>`_
+
+* `Binary ZIP file <http://www.apache.org/dyn/closer.cgi/db/ddlutils/ddlutils-1.0/binaries/DdlUtils-1.0-bin.zip>`_
+ (`Signature <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/binaries/DdlUtils-1.0-bin.zip.asc>`_, `MD5 <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/binaries/DdlUtils-1.0-bin.zip.md5>`_, `SHA1 <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/binaries/DdlUtils-1.0-bin.zip.sha>`_)
+* `JAR file <http://www.apache.org/dyn/closer.cgi/db/ddlutils/ddlutils-1.0/binaries/DdlUtils-1.0.jar>`_
+ (`Signature <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/binaries/DdlUtils-1.0.jar.asc>`_, `MD5 <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/binaries/DdlUtils-1.0.jar.md5>`_, `SHA1 <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/binaries/DdlUtils-1.0.jar.sha>`_)
+* `Source ZIP file <http://www.apache.org/dyn/closer.cgi/db/ddlutils/ddlutils-1.0/source/DdlUtils-1.0-src.zip>`_
+ (`Signature <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/source/DdlUtils-1.0-src.zip.asc>`_, `MD5 <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/source/DdlUtils-1.0-src.zip.md5>`_, `SHA1 <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/source/DdlUtils-1.0-src.zip.sha>`_)
+* `Documentation ZIP <http://www.apache.org/dyn/closer.cgi/db/ddlutils/ddlutils-1.0/doc/DdlUtils-1.0-doc.zip>`_
+ (`Signature <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/doc/DdlUtils-1.0-doc.zip.asc>`_, `MD5 <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/doc/DdlUtils-1.0-doc.zip.md5>`_, `SHA1 <http://www.apache.org/dist/db/ddlutils/ddlutils-1.0/doc/DdlUtils-1.0-doc.zip.sha>`_)
+
+You can find the KEYS file containing the public keys for verifying the signature
+`here <http://www.apache.org/dist/db/ddlutils/KEYS>`_.
+
+Source code
+-----------
+
+DdlUtils uses `Apache Subversion`_ as its source repository. To access it
+you need a SVN client.
+
+The ``svn`` command is usually readily available in these systems. Here all
+you need to do is to change to a directory where you want to put DdlUtils into, and
+then issue this command:
+
+ svn co http://svn.apache.org/repos/asf/db/ddlutils/trunk ddlutils
+
+This will checkout the current development version of DdlUtils in read-only mode.
+This means you can play around with the source without fear for breaking anything
+as the changes cannot be checked back in.
+
+.. note::
+ If you're a committer, you'll have to replace the ``http`` with ``https``.
+
+For Windows systems, one of the available SVN clients is
+`TortoiseSVN`_ which is a Windows Explorer extension.
+After you've installed it and rebooted you computer (which is necessary
+because of it nature as an Explorer extension), you'll have additional
+options in the context menu in Explorer. Change to a directory where you
+want to checkout DdlUtils, and choose the "SVN Checkout ..." option
+from the context menu. You'll get this dialog:
+
+.. image:: images/tortoisesvn-checkout-dlg.png
+ :alt: TortoiseSVN checkout dialog
+
+After you clicked OK, TortoiseSVN will checkout to the designated place. Once it
+has finished you can start using DdlUtils:
+
+.. image:: images/tortoisesvn-checkout-finished.png
+ :alt: TortoiseSVN checkout finished
diff --git a/src/site/sphinx/drop-database-subtask.rst b/src/site/sphinx/drop-database-subtask.rst
new file mode 100644
index 0000000..d3f90ed
--- /dev/null
+++ b/src/site/sphinx/drop-database-subtask.rst
@@ -0,0 +1,34 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+dropDatabase
+============
+
+The sub task for dropping the target database. Note that this is only supported on some database
+platforms. See :doc:`here <database-support>` for details on which platforms support this.
+
+This sub task does not require schema files. Therefore the ``fileset`` subelement and
+the ``schemaFile`` attributes can be omitted.
+
+Attributes
+----------
+
+``failOnError``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Specifies whether the execution shall stop if an error has occurred while the task runs.
diff --git a/src/site/sphinx/images/ant.gif b/src/site/sphinx/images/ant.gif
new file mode 100644
index 0000000..44bc07f
--- /dev/null
+++ b/src/site/sphinx/images/ant.gif
Binary files differ
diff --git a/src/site/sphinx/images/db-logo.png b/src/site/sphinx/images/db-logo.png
new file mode 100644
index 0000000..ff7da25
--- /dev/null
+++ b/src/site/sphinx/images/db-logo.png
Binary files differ
diff --git a/src/site/sphinx/images/junit.gif b/src/site/sphinx/images/junit.gif
new file mode 100644
index 0000000..d0e1547
--- /dev/null
+++ b/src/site/sphinx/images/junit.gif
Binary files differ
diff --git a/src/site/sphinx/images/model.png b/src/site/sphinx/images/model.png
new file mode 100644
index 0000000..b35c400
--- /dev/null
+++ b/src/site/sphinx/images/model.png
Binary files differ
diff --git a/src/site/sphinx/images/tortoisesvn-checkout-dlg.png b/src/site/sphinx/images/tortoisesvn-checkout-dlg.png
new file mode 100644
index 0000000..2acbb23
--- /dev/null
+++ b/src/site/sphinx/images/tortoisesvn-checkout-dlg.png
Binary files differ
diff --git a/src/site/sphinx/images/tortoisesvn-checkout-finished.png b/src/site/sphinx/images/tortoisesvn-checkout-finished.png
new file mode 100644
index 0000000..3ab4b05
--- /dev/null
+++ b/src/site/sphinx/images/tortoisesvn-checkout-finished.png
Binary files differ
diff --git a/src/site/sphinx/index.rst b/src/site/sphinx/index.rst
new file mode 100644
index 0000000..582d330
--- /dev/null
+++ b/src/site/sphinx/index.rst
@@ -0,0 +1,29 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+DdlUtils documentation
+======================
+
+.. toctree::
+ :maxdepth: 2
+
+ welcome
+ download
+ api-usage
+ ant-tasks
+ database-support
+ schema
\ No newline at end of file
diff --git a/src/site/sphinx/schema.rst b/src/site/sphinx/schema.rst
new file mode 100644
index 0000000..100d6ef
--- /dev/null
+++ b/src/site/sphinx/schema.rst
@@ -0,0 +1,125 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+Data schema
+===========
+
+DdlUtils uses a dynamic XML schema for representing data that tries to use table and column names as
+much as possible.
+
+Table rules
+-----------
+
+It follows the following rules for choosing the tags and attributes to represent the
+table of a given row:
+
+* If the table name is a valid XML tag, then it will be used as the XML element for the row. E.g.::
+
+ <MyTable ...>...</MyTable>
+
+* If the table name is not a valid XML tag, but it is shorter than 255 characters and does not contain
+ characters that would be illegal for an XML attribute, then the XML element will be ``table`` with an
+ attribute ``table-name`` containing the name of the table. E.g.::
+
+ <table table-name="My Table" ...>...</table>
+
+ If the table name contains characters like the ampersand, then these will be escaped in the standard
+ XML fashion (via entities)::
+
+ <table table-name="Bread&Butter" ...>...</table>
+
+* If the table name is not a valid XML tag (not a valid tag or longer than 255 characters) and does not
+ contain characters that would be illegal for an XML attribute, then the XML element will be ``table``
+ with a sub element ``table-name`` containing the name of the table. E.g.::
+
+ <table ...>
+ <table-name>My Really Long Table Name ...</table-name>
+ ...
+ </table>
+
+* If the table name contains characters that are illegal in XML, then the same format as above is used,
+ but the value is also Base-64 encoded. An additional attribute ``base64`` with the value ``true``
+ signifies that the value is Base-64 encoded. E.g.::
+
+ <table ...>
+ <table-name base64="true">TXlUYWJsZQ==</table-name>
+ ...
+ </table>
+
+Column rules
+------------
+
+The rules for the columns are similar to the table rules:
+
+* If the column name is a valid XML attribute name and not equal to ``table-name`` or ``base64``, and
+ the value is shorter than 255 characters and does not contain any characters invalid in XML, then an XML
+ attribute will be used for the column. This is true regardless of whether the table name is a valid tag::
+
+ <MyTable myColumn="..." ...>...</MyTable>
+
+ or not::
+
+ <table table-name="My Table" myColumn="..." ...>...</table>
+
+* If the column name is a valid XML attribute name and not equal to ``table-name`` or ``base64``, but the
+ value is not shorter than 255 characters or it contains characters that are not allowed in XML documents,
+ then instead a sub element will be used with the column name as the tag name::
+
+ <MyTable ...>
+ <myColumn>...</myColumn>
+ ...
+ </MyTable>
+
+ or::
+
+ <MyTable ...>
+ <myColumn base64="true">...</myColumn>
+ ...
+ </MyTable>
+
+ if the value needs to be Base-64 encoded because of illegal characters.
+
+* If the column name is not a valid XML attribute name and it is shorter than 255 characters and does not
+ contain characters that would be illegal for an XML attribute, or if the column name is equal to
+ ``column-name`` or ``base64``, then instead a sub element will be used for the column name which will have
+ an attribute ``column-name`` for the column name and the value as text content. E.g.::
+
+ <MyTable ...>
+ <column column-name="the column">...</column>
+ ...
+ </MyTable>
+
+ or::
+
+ <MyTable ...>
+ <column column-name="the column" base64="true">...</column>
+ ...
+ </MyTable>
+
+ if the value needs to be Base-64 encoded.
+
+* If the column name is not a valid XML attribute name or it is longer than 255 characters or it contains
+ illegal characters, then instead a ``column-name`` sub element is used with the column name as the text
+ content (base 64 encoded if necessary). The value will be in a corresponding ``column-value`` sub element::
+
+ <MyTable ...>
+ <column>
+ <column-name>...</column-name>
+ <column-value>...</column-value>
+ </column>
+ ...
+ </MyTable>
diff --git a/src/site/sphinx/welcome.rst b/src/site/sphinx/welcome.rst
new file mode 100644
index 0000000..636aa97
--- /dev/null
+++ b/src/site/sphinx/welcome.rst
@@ -0,0 +1,103 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+.. _`Turbine XML format`: http://db.apache.org/torque/dtd/database.dtd
+.. _`Torque`: http://db.apache.org/torque/
+.. _`OJB`: http://db.apache.org/ojb/
+.. _`Ant`: http://ant.apache.org/
+
+.. _contents:
+
+What is DdlUtils
+================
+
+**DdlUtils** is a small, easy-to-use component for working with Database Definition
+(DDL) files. These are XML files that contain the definition of a database schema, e.g. tables
+and columns. These files can be fed into DdlUtils via its Ant task or programmatically in order to
+create the corresponding database or alter it so that it corresponds to the DDL. Likewise, DdlUtils
+can generate a DDL file for an existing database.
+
+DdlUtils uses the `Turbine XML format`_, which is shared by `Torque`_ and `OJB`_. This format expresses
+the database schema in a database-independent way by using JDBC datatypes instead of raw SQL
+datatypes which are inherently database specific. An example of such a file is::
+
+ <?xml version="1.0"?>
+ <!DOCTYPE database SYSTEM "http://db.apache.org/torque/dtd/database.dtd">
+ <database name="testdb">
+ <table name="author">
+ <column name="author_id"
+ type="INTEGER"
+ primaryKey="true"
+ required="true"/>
+ <column name="name"
+ type="VARCHAR"
+ size="50"
+ required="true"/>
+ <column name="organisation"
+ type="VARCHAR"
+ size="50"
+ required="false"/>
+ </table>
+
+ <table name="book">
+ <column name="book_id"
+ type="INTEGER"
+ required="true"
+ primaryKey="true"
+ autoIncrement="true"/>
+ <column name="isbn"
+ type="VARCHAR"
+ size="15"
+ required="true"/>
+ <column name="author_id"
+ type="INTEGER"
+ required="true"/>
+ <column name="title"
+ type="VARCHAR"
+ size="255"
+ defaultValue="N/A"
+ required="true"/>
+
+ <foreign-key foreignTable="author">
+ <reference local="author_id" foreign="author_id"/>
+ </foreign-key>
+
+ <index name="book_isbn">
+ <index-column name="isbn"/>
+ </index>
+ </table>
+ </database>
+
+Learning more
+-------------
+
+There are essentially two ways to use DdlUtils:
+
+* In an `Ant`_ build script via the task provided by DdlUtils. You can learn more about it in the
+ :doc:`Ant task documentation <ant-tasks>`.
+* From within your Java program, about which you can learn more in the :doc:`API documentation <api-usage>`.
+
+You're also welcome to join one of the two DdlUtils' mailing lists:
+
+* User mailing list ``ddlutils-user <at> db.apache.org``
+
+ `Subscribe <mailto:ddlutils-user-subscribe@db.apache.org>`_, `Unsubscribe <mailto:ddlutils-user-unsubscribe@db.apache.org>`_, `Archive <http://mail-archives.apache.org/mod_mbox/db-ddlutils-user/>`_
+
+* Developer mailing list ``ddlutils-dev <at> db.apache.org``
+
+ `Subscribe <mailto:ddlutils-dev-subscribe@db.apache.org>`_, `Unsubscribe <mailto:ddlutils-dev-unsubscribe@db.apache.org>`_, `Archive <http://mail-archives.apache.org/mod_mbox/db-ddlutils-dev/>`_
+
diff --git a/src/site/sphinx/write-data-to-database-subtask.rst b/src/site/sphinx/write-data-to-database-subtask.rst
new file mode 100644
index 0000000..186583e
--- /dev/null
+++ b/src/site/sphinx/write-data-to-database-subtask.rst
@@ -0,0 +1,114 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+.. _`fileset section`: http://ant.apache.org/manual/coretypes/fileset
+.. _`SqlTypeConverter`: /api/org/apache/ddlutils/io/converters/SqlTypeConverter.html
+
+writeDataToDatabase
+===================
+
+Inserts the data defined by the data XML file(s) into the database. This requires the schema
+in the database to match the schema defined by the XML files specified at the enclosing task.
+
+DdlUtils will honor the order imposed by the foreign keys. Ie. first all required entries are
+inserted, then the dependent ones. Obviously this requires that no circular references exist
+in the schema (DdlUtils currently does not check this). Also, the referenced entries must be
+present in the data, otherwise the task will fail. This behavior can be turned off via the
+``ensureForeignKeyOrder`` attribute.
+
+In order to define data for foreign key dependencies that use auto-incrementing primary keys,
+simply use unique values for their columns. DdlUtils will automatically use the real primary
+key values. Note though that not every database supports the retrieval of auto-increment values.
+
+Attributes
+----------
+
+``batchSize``
+ :Required: no
+ :Allowed:
+ :Default: 1
+ :Meaning: The maximum number of insert statements to combine in one batch. The number typically
+ depends on the JDBC driver and the amount of available memory.
+ This value is only used if ``useBatchMode`` is ``true``.
+
+``dataFile``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: The name of the single XML file that contains the data to insert into the database.</td>
+
+``ensureForeignKeyOrder``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Whether DdlUtils shall honor the foreign key order or simply assume that the entry
+ order is ok.
+
+``failOnError``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Specifies whether the execution shall stop if an error has occurred while the task runs.
+
+``useBatchMode``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``false``
+ :Meaning: Whether DdlUtils shall use batch-mode for inserting the data. In this mode, insert statements
+ for the same table are bundled together and executed as one statement which can be a lot
+ faster than single insert statements. To achieve the highest performance, you should group
+ the data in the XML file according to the tables because a batch insert only works for one
+ table which means when the table changes the batch is executed and a new one will be started.
+
+Subelements
+-----------
+
+``fileset``
+ Specifies the XML files that contain the data to insert. DdlUtils processes them in the
+ order that they appear in the fileset(s). For details on the `fileset section`_ in the Ant manual.
+
+``converter``
+ Defines a class that is able to convert between the Java type corresponding to a SQL type
+ (e.g. ``java.sql.Date``, ``java.lang.String``) and strings to be used in XML files.
+
+ *Attributes*
+
+ ``className``
+ :Required: yes
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the fully qualified class name of the converter. Note that the class is
+ required to implement the `SqlTypeConverter`_ interface.
+
+ ``column``
+ :Required: Either this together with ``table`` or ``jdbcType``
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the column for which this converter shall be used.
+
+ ``jdbcType``
+ :Required: Either this or ``table`` + ``column``
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the JDBC type for which this converter shall be used. Note that converters
+ specified for a specific column override converters defined for types.
+
+ ``table``
+ :Required: Either this together with ``column`` or ``jdbcType``
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the table for which this converter shall be used.
diff --git a/src/site/sphinx/write-data-to-file-subtask.rst b/src/site/sphinx/write-data-to-file-subtask.rst
new file mode 100644
index 0000000..4262f7e
--- /dev/null
+++ b/src/site/sphinx/write-data-to-file-subtask.rst
@@ -0,0 +1,79 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+.. _`SqlTypeConverter`: /api/org/apache/ddlutils/io/converters/SqlTypeConverter.html
+
+writeDataToFile
+===============
+
+Generates an XML file containing the data currently stored in the database.
+
+Attributes
+----------
+
+``encoding``
+ :Required: no
+ :Allowed:
+ :Default: UTF-8
+ :Meaning: The desired encoding of the XML file.
+
+``failOnError``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Specifies whether the execution shall stop if an error has occurred while the task runs.
+
+``outputFile``
+ :Required: yes
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the XML file to write the data to.
+
+Subelements
+-----------
+
+``converter``
+ Defines a class that is able to convert between the Java type corresponding to a SQL type
+ (e.g. ``java.sql.Date``, ``java.lang.String``) and strings to be used in XML files.
+
+ *Attributes*
+
+ ``className``
+ :Required: yes
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the fully qualified class name of the converter. Note that the class is
+ required to implement the `SqlTypeConverter`_ interface.
+
+ ``column``
+ :Required: Either this together with ``table`` or ``jdbcType``
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the column for which this converter shall be used.
+
+ ``jdbcType``
+ :Required: Either this or ``table`` + ``column``
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the JDBC type for which this converter shall be used. Note that converters
+ specified for a specific column override converters defined for types.
+
+ ``table``
+ :Required: Either this together with ``column`` or ``jdbcType``
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the table for which this converter shall be used.
diff --git a/src/site/sphinx/write-database-schema-sql-to-file-subtask.rst b/src/site/sphinx/write-database-schema-sql-to-file-subtask.rst
new file mode 100644
index 0000000..ec4228f
--- /dev/null
+++ b/src/site/sphinx/write-database-schema-sql-to-file-subtask.rst
@@ -0,0 +1,55 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+writeSchemaSqlToFile
+====================
+
+Creates the SQL commands necessary to re-create the schema in the database. In contrast to the
+sub task of the same name in the :doc:`DdlToDatabaseTask <ddl-to-database-task>`, this sub task
+operates on the schema in the database.
+
+Attributes
+----------
+
+``alterDatabase``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Specifies whether DdlUtils shall alter existing tables rather than dropping them and
+ creating them new.
+
+``doDrops``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Whether tables and external constraints can be dropped if necessary. Note that this is also
+ relevant when ``alterDatabase`` is ``true``. For instance, a table has a
+ foreign key constraint in the database but not in the schema. If ``doDrops`` = ``true``
+ then DdlUtils will drop the constraint, otherwise it will be unchanged thus possibly leading
+ to unexpected errors.
+
+``failOnError``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Specifies whether the execution shall stop if an error has occurred while the task runs.
+
+``outputFile``
+ :Required: yes
+ :Allowed:
+ :Default:
+ :Meaning: The name of the file to write the SQL commands to.
diff --git a/src/site/sphinx/write-dtd-to-file-subtask.rst b/src/site/sphinx/write-dtd-to-file-subtask.rst
new file mode 100644
index 0000000..bd058d4
--- /dev/null
+++ b/src/site/sphinx/write-dtd-to-file-subtask.rst
@@ -0,0 +1,38 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+writeDtdToFile
+==============
+
+Creates a DTD that specifies the layout for data XML files.
+
+This sub task does not require a database connection, so the ``dataSource`` subelement can be omitted.
+
+Attributes
+----------
+
+``failOnError``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Specifies whether the execution shall stop if an error has occurred while the task runs.
+
+``outputFile``
+ :Required: yes
+ :Allowed:
+ :Default:
+ :Meaning: The name of the file to write the DTD to.
diff --git a/src/site/sphinx/write-file-schema-sql-to-file-subtask.rst b/src/site/sphinx/write-file-schema-sql-to-file-subtask.rst
new file mode 100644
index 0000000..201a607
--- /dev/null
+++ b/src/site/sphinx/write-file-schema-sql-to-file-subtask.rst
@@ -0,0 +1,101 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+writeSchemaSqlToFile
+====================
+
+Creates the SQL commands necessary to create the schema in the database that is described by
+the schema XML files specified for the enclosing task. Note that this subtask requires either
+the specification of the data source in the enclosing task, or the use of the
+``databaseType`` attribute at the enclosing task.
+
+Attributes
+----------
+
+``alterDatabase``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Specifies whether DdlUtils shall alter existing tables rather than dropping them and
+ creating them new.
+
+``doDrops``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Whether tables and external constraints can be dropped if necessary. Note that this is also
+ relevant when ``alterDatabase`` is ``true``. For instance, a table has a
+ foreign key constraint in the database but not in the schema. If ``doDrops`` = ``true``
+ then DdlUtils will drop the constraint, otherwise it will be unchanged thus possibly leading
+ to unexpected errors.
+
+``failOnError``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Specifies whether the execution shall stop if an error has occurred while the task runs.
+
+``outputFile``
+ :Required: yes
+ :Allowed:
+ :Default:
+ :Meaning: The name of the file to write the SQL commands to.
+
+Subelements
+-----------
+
+``parameter``
+ Specifies a parameter for the creation of the database. These are usually platform specific.
+ If no table name is specified, the parameter is applied to all tables.
+
+ Parameters are only applied when creating new tables, not when altering existing ones.
+
+ *Attributes*
+
+ ``name``
+ :Required: yes
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the name of the parameter. See :doc:`the database support documentation <database-support>`
+ for the parameters supported by the individual platforms.
+
+ ``platforms``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: Comma-separated list of platforms where the parameter shall be processed (see
+ ``databaseType`` attribute above for the possible values). For every platform
+ not in this list, the parameter is ignored. If none is given, then the parameter
+ is processed for every platform.
+
+ ``table``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the name of the table where this parameter shall be applied.
+
+ ``tables``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the comma-separated list of table names where this parameter shall be applied.
+
+ ``value``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: The parameter value. If none is given, ``null`` is used.
diff --git a/src/site/sphinx/write-schema-to-database-subtask.rst b/src/site/sphinx/write-schema-to-database-subtask.rst
new file mode 100644
index 0000000..169db46
--- /dev/null
+++ b/src/site/sphinx/write-schema-to-database-subtask.rst
@@ -0,0 +1,93 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+writeSchemaToDatabase
+=====================
+
+Creates the schema in the database that is described by the schema XML files specified for
+the enclosing task.
+
+Attributes
+----------
+
+``alterDatabase``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Specifies whether DdlUtils shall alter existing tables rather than dropping them and
+ creating them new.
+
+``doDrops``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Whether tables and external constraints can be dropped if necessary. Note that this is also
+ relevant when ``alterDatabase`` is ``true``. For instance, a table has a
+ foreign key constraint in the database but not in the schema. If ``doDrops`` = ``true``
+ then DdlUtils will drop the constraint, otherwise it will be unchanged thus possibly leading
+ to unexpected errors.
+
+``failOnError``
+ :Required: no
+ :Allowed: ``true``, ``false``
+ :Default: ``true``
+ :Meaning: Specifies whether the execution shall stop if an error has occurred while the task runs.
+
+Subelements
+-----------
+
+``parameter``
+ Specifies a parameter for the creation of the database. These are usually platform specific.
+ If no table name is specified, the parameter is applied to all tables.
+
+ Parameters are only applied when creating new tables, not when altering existing ones.
+
+ *Attributes*
+
+ ``name``
+ :Required: yes
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the name of the parameter. See :doc:`the database support documentation <database-support>`
+ for the parameters supported by the individual platforms.
+
+ ``platforms``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: Comma-separated list of platforms where the parameter shall be processed (see
+ ``databaseType`` attribute above for the possible values). For every platform
+ not in this list, the parameter is ignored. If none is given, then the parameter
+ is processed for every platform.
+
+ ``table``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the name of the table where this parameter shall be applied.
+
+ ``tables``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: Specifies the comma-separated list of table names where this parameter shall be applied.
+
+ ``value``
+ :Required: no
+ :Allowed:
+ :Default:
+ :Meaning: The parameter value. If none is given, ``null`` is used.
diff --git a/src/site/sphinx/write-schema-to-file-subtask.rst b/src/site/sphinx/write-schema-to-file-subtask.rst
new file mode 100644
index 0000000..8be90c5
--- /dev/null
+++ b/src/site/sphinx/write-schema-to-file-subtask.rst
@@ -0,0 +1,30 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+writeSchemaToFile
+=================
+
+Dumps the schema in the database to a schema XML file.
+
+Attributes
+----------
+
+``outputFile``
+ :Required: yes
+ :Allowed:
+ :Default:
+ :Meaning: The name of the file to write the schema XML to.
