From ddlutils-dev-return-1207-apmail-db-ddlutils-dev-archive=db.apache.org@db.apache.org Mon Nov 06 07:20:50 2006 Return-Path: Delivered-To: apmail-db-ddlutils-dev-archive@www.apache.org Received: (qmail 77767 invoked from network); 6 Nov 2006 07:20:49 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 6 Nov 2006 07:20:49 -0000 Received: (qmail 20651 invoked by uid 500); 6 Nov 2006 07:21:01 -0000 Delivered-To: apmail-db-ddlutils-dev-archive@db.apache.org Received: (qmail 20592 invoked by uid 500); 6 Nov 2006 07:21:00 -0000 Mailing-List: contact ddlutils-dev-help@db.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: ddlutils-dev@db.apache.org Delivered-To: mailing list ddlutils-dev@db.apache.org Received: (qmail 20581 invoked by uid 500); 6 Nov 2006 07:21:00 -0000 Delivered-To: apmail-db-ddlutils-commits@db.apache.org Received: (qmail 20578 invoked by uid 99); 6 Nov 2006 07:21:00 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 05 Nov 2006 23:21:00 -0800 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 05 Nov 2006 23:20:46 -0800 Received: by eris.apache.org (Postfix, from userid 65534) id 8EFEC1A9846; Sun, 5 Nov 2006 23:20:20 -0800 (PST) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r471653 - in /db/ddlutils/trunk: ./ src/antdoc/ src/antdoc/templates/ src/antdoc/templates/html/ src/java/org/apache/ddlutils/task/ Date: Mon, 06 Nov 2006 07:20:19 -0000 To: ddlutils-commits@db.apache.org From: tomdz@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20061106072020.8EFEC1A9846@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: tomdz Date: Sun Nov 5 23:20:18 2006 New Revision: 471653 URL: http://svn.apache.org/viewvc?view=rev&rev=471653 Log: Started work on better Ant task documentation Added: db/ddlutils/trunk/src/antdoc/ db/ddlutils/trunk/src/antdoc/templates/ db/ddlutils/trunk/src/antdoc/templates/html/ db/ddlutils/trunk/src/antdoc/templates/html/index.html db/ddlutils/trunk/src/antdoc/templates/html/libindex.vm db/ddlutils/trunk/src/antdoc/templates/html/main.vm db/ddlutils/trunk/src/antdoc/templates/html/overview.vm db/ddlutils/trunk/src/antdoc/templates/html/style.css db/ddlutils/trunk/src/antdoc/templates/html/task.vm db/ddlutils/trunk/src/antdoc/templates/html/taskindex.vm Modified: db/ddlutils/trunk/build.properties db/ddlutils/trunk/build.xml db/ddlutils/trunk/src/java/org/apache/ddlutils/task/Command.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/ConvertingDatabaseCommand.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/CreateDatabaseCommand.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseCommand.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseCommandWithCreationParameters.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseTaskBase.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseToDdlTask.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DdlToDatabaseTask.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DropDatabaseCommand.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DumpMetadataTask.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/Parameter.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/PlatformConfiguration.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/TableSpecificParameter.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDataToDatabaseCommand.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDataToFileCommand.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDtdToFileCommand.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaSqlToFileCommand.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaToDatabaseCommand.java db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaToFileCommand.java Modified: db/ddlutils/trunk/build.properties URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/build.properties?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/build.properties (original) +++ db/ddlutils/trunk/build.properties Sun Nov 5 23:20:18 2006 @@ -19,11 +19,13 @@ src.test.dir=${src.dir}/test src.resources.dir=${src.dir}/resources src.doc.dir=${src.dir}/doc +src.antdoc.dir=${src.dir}/antdoc src.check.dir=${src.dir}/check build.dir=target build.java.dir=${build.dir}/classes build.test.dir=${build.dir}/test +build.antdoc.dir=${build.dir}/antdoc build.javadoc.dir=${build.dir}/javadoc build.schemadoc.dir=${build.dir}/schemadoc build.doc.dir=${build.dir}/doc @@ -40,15 +42,19 @@ checkstyle.author.pattern=\\S checkstyle.license.file=${src.check.dir}/license-check.txt - test.profile.directory=src/test-profiles + # # Documentation properties # javadoc.title=${project-name} ${version} API Documentation -javadoc.footer=Copyright © 2005 Apache Software Foundation. All Rights Reserved. +javadoc.footer=Copyright © 2005-2006 Apache Software Foundation. All Rights Reserved. + +antdoc.title=${project-name} ${version} Ant Tasks +antdoc.templates.dir=${src.antdoc.dir}/templates +forrest.antdoc.destdir=${build.doc.dir}/src/documentation/content/ant forrest.javadoc.destdir=${build.doc.dir}/src/documentation/content/api forrest.schemadoc.destdir=${build.doc.dir}/src/documentation/content/schema forrest.output.dir=${build.doc.dir}/build/site Modified: db/ddlutils/trunk/build.xml URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/build.xml?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/build.xml (original) +++ db/ddlutils/trunk/build.xml Sun Nov 5 23:20:18 2006 @@ -162,10 +162,10 @@ classpathref="compilation-classpath" destdir="${build.javadoc.dir}" doctitle="${javadoc.title}" - windowtitle="${javadoc.title} API documentation" + windowtitle="${javadoc.title}" bottom="${javadoc.footer}" protected="true" - author="true" + author="false" version="true" packagenames="org.*"> @@ -191,6 +191,32 @@ + + + + + + + + + + + + + + + Added: db/ddlutils/trunk/src/antdoc/templates/html/index.html URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/antdoc/templates/html/index.html?view=auto&rev=471653 ============================================================================== --- db/ddlutils/trunk/src/antdoc/templates/html/index.html (added) +++ db/ddlutils/trunk/src/antdoc/templates/html/index.html Sun Nov 5 23:20:18 2006 @@ -0,0 +1,21 @@ + + + + + + Ant Tasks Documentation + + + + + + + + + + + + + + + Added: db/ddlutils/trunk/src/antdoc/templates/html/libindex.vm URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/antdoc/templates/html/libindex.vm?view=auto&rev=471653 ============================================================================== --- db/ddlutils/trunk/src/antdoc/templates/html/libindex.vm (added) +++ db/ddlutils/trunk/src/antdoc/templates/html/libindex.vm Sun Nov 5 23:20:18 2006 @@ -0,0 +1,38 @@ + + +## +## This is an Velocity template for generating an HTML index +## of the Ant "categories" (antlibs) +## +## Objects expected in context: +## +## $title - Project title (of type String) +## $antroot - (of type AntRoot) +## + + + $title Ant Libraries + + + + + + + Added: db/ddlutils/trunk/src/antdoc/templates/html/main.vm URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/antdoc/templates/html/main.vm?view=auto&rev=471653 ============================================================================== --- db/ddlutils/trunk/src/antdoc/templates/html/main.vm (added) +++ db/ddlutils/trunk/src/antdoc/templates/html/main.vm Sun Nov 5 23:20:18 2006 @@ -0,0 +1,37 @@ +## +## This template is the entry point for calling other templates. +## The output of this template goes to stdout. +## +## Objects available in context: +## +## $velocity - Helper object for processing other templates (of type VelocityFacade) +## $antroot - Contains all the Ant tasks/types (of type AntRoot) +## $title - Project title (of type String) +## + +AntDoclet - Running project $title + +- Generating Task and Types documentation... +## +#foreach( $taskDoc in $antroot.getAll() ) ## + #if ( ! $taskDoc.isIgnored() ) + +- Processing $taskDoc.antName ## + $velocity.eval( "html/task.vm", "${taskDoc.getFullClassName()}.html" ) ## + #else ## +- Ignoring $taskDoc.fullClassName()## + #end ## +#end ## + + +- Generating Navigation indexes... +## Now, generate an "index" file for the categories, and one for each category +$velocity.eval( "html/libindex.vm", "libindex.html" ) +$velocity.eval( "html/overview.vm", "overview.html" ) +#foreach( $category in $antroot.getCategories() ) + $velocity.eval( "html/taskindex.vm", "index.${category}.html" ) +#end +#set($category = "all") +$velocity.eval( "html/taskindex.vm", "index.${category}.html" ) + +- Done Added: db/ddlutils/trunk/src/antdoc/templates/html/overview.vm URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/antdoc/templates/html/overview.vm?view=auto&rev=471653 ============================================================================== --- db/ddlutils/trunk/src/antdoc/templates/html/overview.vm (added) +++ db/ddlutils/trunk/src/antdoc/templates/html/overview.vm Sun Nov 5 23:20:18 2006 @@ -0,0 +1,134 @@ + + + + + $title + + + + + + + +

$title - Documentation

+ +

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

+ +

Using the Tasks

+ +

+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 structure and inserts data into the database">
+  <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 here. +

+
+

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

+ + +

Requirements

+

The DdlUtils tasks require Ant version 1.5 or newer.

+ +

Reference

+

The tasks reference documentation can be found here.

+ +
+
+
+ Copyright © 2005-2006 Apache Software Foundation. All Rights Reserved. +
+ + + + Added: db/ddlutils/trunk/src/antdoc/templates/html/style.css URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/antdoc/templates/html/style.css?view=auto&rev=471653 ============================================================================== --- db/ddlutils/trunk/src/antdoc/templates/html/style.css (added) +++ db/ddlutils/trunk/src/antdoc/templates/html/style.css Sun Nov 5 23:20:18 2006 @@ -0,0 +1,87 @@ + + +body { + font-family: verdana, arial,helvetica,sanserif; + font-size: 90%; +} + +h2 { + font-size: 110%; + text-align: left; +} + +div#navigation h2 { + text-align: left; + background-color: #CCCCFF; + font-variant: small-caps; + margin-bottom: 0; + padding-left: 5%; +} + +h3 { + font-size: 100%; + text-align: left; + background-color: #CCCCFF; + margin-bottom: 0; +} + +h4 { + font-size: 90%; + margin-top: 5%; +} + +div#navigation { + float: left; +} + +#navigation div.description { + margin-left: 5%; + font-size: small; +} + +div.description { + margin: 5%; + font-size: medium; +} + +pre { + border: solid 1px black; + background-color: #FFFFCC; + font-size: smaller; + font-family: monospace; +} + +code { + font-size: smaller; + font-family: monospace; +} + +table { + font-family: arial,helvetica,sanserif; + font-size: 80%; + margin: 5%; + padding: 0px; + +// border: solid 1px black; + border-spacing: 0px; + border-collapse: collapse; +} + +tr:first-child { + background-color: #DDDDFF; +} + +td { + margin: 0px; + padding: 2px; + border: solid 1px black; + border-spacing: 0px; + border-collapse: collapse; +} + + +.copyright { + color: #999999; + font-size: 60%; + text-align: center; +} Added: db/ddlutils/trunk/src/antdoc/templates/html/task.vm URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/antdoc/templates/html/task.vm?view=auto&rev=471653 ============================================================================== --- db/ddlutils/trunk/src/antdoc/templates/html/task.vm (added) +++ db/ddlutils/trunk/src/antdoc/templates/html/task.vm Sun Nov 5 23:20:18 2006 @@ -0,0 +1,96 @@ + + +## +## This is a Velocity template for generating an HTML +## document describing an Ant Task/Type +## +## Objects expected in context: +## +## $taskDoc - Describes an Ant Task/Type (of type AntDoc) +## +## + + +<$taskDoc.getAntName()> + + + +

#if( $taskDoc.getAnyCategory().length() > 0 ) $!taskDoc.getAntCategory() : #end $taskDoc.getAntName()

+

Type

+

$taskDoc.getFullClassName()

+

Description

+

$taskDoc.getComment()

+

Parameters

+#foreach ($attr in $taskDoc.attributes ) +

$attr

+ + + + + + + + + +
Type$taskDoc.getAttributeType($attr)
Required? + #if ($taskDoc.getAttributeRequired($attr)) + Yes $taskDoc.getAttributeRequired($attr) + #elseif ($taskDoc.getAttributeNotRequired($attr)) + No $taskDoc.getAttributeNotRequired($attr) + #else + unknown + #end +
+

$taskDoc.getAttributeComment($attr)

+#end +

Nested elements

+#if ($taskDoc.isTaskContainer()) +

This Task is a Container (it accepts nested Tasks).

+#end +#if ($taskDoc.supportsCharacters()) +

This Task accepts text in its element body.

+#end +#foreach ($element in $taskDoc.getNestedElements()) + #set ($elementDoc = $taskDoc.getElementDoc($element)) + #if ($elementDoc.sourceIncluded() && $elementDoc.isTagged()) +

<$element> ...

+ #else +

<$element>#if (!$elementDoc.sourceIncluded()) (Of type ${elementDoc.getAntName()}) #end

+ #if($elementDoc.getComment()) +

$elementDoc.getComment()

+ #end + Parameters + #foreach ($attr in $elementDoc.attributes ) +
$attr
+ + + + + + + + + +
Type$elementDoc.getAttributeType($attr)
Required? + #if ($elementDoc.getAttributeRequired($attr)) + Yes $elementDoc.getAttributeRequired($attr) + #elseif ($elementDoc.getAttributeNotRequired($attr)) + No $elementDoc.getAttributeNotRequired($attr) + #else + unknown + #end +
+ #if($elementDoc.getAttributeComment($attr)) +

$elementDoc.getAttributeComment($attr)

+ #end + #end + #end +#end + +
+
+ +
Generated with AntDoclet
+ + + Added: db/ddlutils/trunk/src/antdoc/templates/html/taskindex.vm URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/antdoc/templates/html/taskindex.vm?view=auto&rev=471653 ============================================================================== --- db/ddlutils/trunk/src/antdoc/templates/html/taskindex.vm (added) +++ db/ddlutils/trunk/src/antdoc/templates/html/taskindex.vm Sun Nov 5 23:20:18 2006 @@ -0,0 +1,65 @@ + + +## +## This is an Velocity template for generating an HTML index +## of the Ant Task/Types +## +## Objects expected in context: +## +## $title - Project title (of type String) +## $antroot - (of type AntRoot) +## + + + $title Ant Tasks + + + + + + + + Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/Command.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/Command.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/Command.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/Command.java Sun Nov 5 23:20:18 2006 @@ -27,6 +27,7 @@ * Base interface for commands that work with a model. * * @version $Revision: 289996 $ + * @ant.type ignore="true" */ public interface Command { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/ConvertingDatabaseCommand.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/ConvertingDatabaseCommand.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/ConvertingDatabaseCommand.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/ConvertingDatabaseCommand.java Sun Nov 5 23:20:18 2006 @@ -30,6 +30,7 @@ * Base type for database commands that use converters. * * @version $Revision: 289996 $ + * @ant.type ignore="true" */ public abstract class ConvertingDatabaseCommand extends DatabaseCommand { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/CreateDatabaseCommand.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/CreateDatabaseCommand.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/CreateDatabaseCommand.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/CreateDatabaseCommand.java Sun Nov 5 23:20:18 2006 @@ -31,9 +31,13 @@ import org.apache.tools.ant.Task; /** - * Command for creating a database. + * The sub task for creating the target database. Note that this is only supported on some database + * platforms. See here for details on which platforms support this.
+ * This sub task does not require schema files. Therefore the fileset subelement and + * the schemaFile attribute of the task can be omitted. * * @version $Revision: 231306 $ + * @ant.task name="createDatabase" */ public class CreateDatabaseCommand extends DatabaseCommand { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseCommand.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseCommand.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseCommand.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseCommand.java Sun Nov 5 23:20:18 2006 @@ -27,6 +27,7 @@ * Base type for commands that have the database info embedded. * * @version $Revision: 289996 $ + * @ant.type ignore="true" */ public abstract class DatabaseCommand implements Command { @@ -97,9 +98,10 @@ } /** - * Specifies whether the command execution will be stopped upon an error. + * Specifies whether the execution shall stop if an error has occurred while the task runs. * - * @param failOnError true if the execution stops in case of an error + * @param failOnError true if the execution shall stop in case of an error + * @ant.not-required By default, execution will be stopped when an error is encountered. */ public void setFailOnError(boolean failOnError) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseCommandWithCreationParameters.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseCommandWithCreationParameters.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseCommandWithCreationParameters.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseCommandWithCreationParameters.java Sun Nov 5 23:20:18 2006 @@ -30,6 +30,7 @@ * Base type for database commands that use creation parameters. * * @version $Revision: 289996 $ + * @ant.type ignore="true" */ public abstract class DatabaseCommandWithCreationParameters extends DatabaseCommand { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseTaskBase.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseTaskBase.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseTaskBase.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseTaskBase.java Sun Nov 5 23:20:18 2006 @@ -34,6 +34,7 @@ * Base class for DdlUtils Ant tasks that operate on a database. * * @version $Revision: 289996 $ + * @ant.task ignore="true" */ public abstract class DatabaseTaskBase extends Task { @@ -53,9 +54,15 @@ } /** - * Sets the database type. + * Specifies 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.
+ * Valid values are currently: axion, cloudscape, db2, derby, firebird, hsqldb, interbase, + * maxdb, mckoi, mssql, mysql, mysql5, oracle, oracle9, oracle10, postgresql, sapdb, sybase * * @param type The database type + * @ant.not-required Per default, DdlUtils tries to determine the database type via JDBC. */ public void setDatabaseType(String type) { @@ -86,9 +93,10 @@ } /** - * Sets the catalog pattern. + * Sets the catalog pattern used when accessing the database. * * @param catalogPattern The catalog pattern + * @ant.not-required Per default, no specific catalog is used. */ public void setCatalogPattern(String catalogPattern) { @@ -99,9 +107,10 @@ } /** - * Sets the schema pattern. + * Sets the schema pattern used when accessing the database. * * @param schemaPattern The schema pattern + * @ant.not-required Per default, no specific schema is used. */ public void setSchemaPattern(String schemaPattern) { @@ -122,9 +131,16 @@ } /** - * Specifies whether delimited SQL identifiers shall be used. + * Specifies 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. * * @param useDelimitedSqlIdentifiers true if delimited SQL identifiers shall be used + * @ant.not-required Default is false. */ public void setUseDelimitedSqlIdentifiers(boolean useDelimitedSqlIdentifiers) { @@ -143,10 +159,13 @@ } /** - * Specifies whether a table's foreign keys read from a live database - * shall be sorted alphabetically. + * Specifies whether a table's foreign keys read from a live database shall be sorted + * alphabetically or left 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). * * @param sortForeignKeys true if the foreign keys shall be sorted + * @ant.not-required Default is false. */ public void setSortForeignKeys(boolean sortForeignKeys) { @@ -165,8 +184,10 @@ /** * Specifies whether the database shall be shut down after the task has finished. + * This is mostly usefule for embedded databases. * * @param shutdownDatabase true if the database shall be shut down + * @ant.not-required Default is false. */ public void setShutdownDatabase(boolean shutdownDatabase) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseToDdlTask.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseToDdlTask.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseToDdlTask.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseToDdlTask.java Sun Nov 5 23:20:18 2006 @@ -26,10 +26,13 @@ import org.apache.tools.ant.BuildException; /** - * Ant task for working with a database, e.g. retrieving the schema from a - * database, dumping data, etc. + * 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, etc. They also + * create DTDs for these data files, and dump the SQL for creating a schema in the database + * to a file. * * @version $Revision: 289996 $ + * @ant.task name="databaseToDdl" */ public class DatabaseToDdlTask extends DatabaseTaskBase { @@ -43,9 +46,13 @@ private String _modelName; /** - * Sets the database schema to access. + * Specifies the table schema(s) to access. This is only necessary for some databases. The + * pattern is that of + * java.sql.DatabaseMetaData#getTables. + * The special pattern '%' indicates that every table schema shall be used. * * @param schema The schema + * @ant.not-required No schema is used by default. */ public void setSchema(String schema) { @@ -53,9 +60,13 @@ } /** - * Sets the database catalog to access. + * Specifies the catalog(s) to access. This is only necessary for some databases. The pattern + * is that of + * java.sql.DatabaseMetaData#getTables. + * The special pattern '%' indicates that every catalog shall be used. * * @param catalog The catalog + * @ant.not-required No catalog is used by default. */ public void setCatalog(String catalog) { @@ -63,9 +74,11 @@ } /** - * Sets the table types ro recognize. + * Specifies the table types to be processed. For details and typical table types see + * java.sql.DatabaseMetaData#getTables. * * @param tableTypes The table types as a comma-separated list + * @ant.not-required By default, only tables of type TABLE are read. */ public void setTableTypes(String tableTypes) { @@ -73,10 +86,12 @@ } /** - * Sets the name that the model read from the database shall have. - * Use null or an empty string for the default name. + * Specifies the name of the model, e.g. the value of the name attribute in the XML if + * the writeSchemaToFile sub-task is used. * - * @param modelName The model name + * @param modelName The model name. Use null or an empty string for the default name + * @ant.not-required By default, DldUtils uses the schema name returned from the database + * or default if none was returned. */ public void setModelName(String modelName) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DdlToDatabaseTask.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DdlToDatabaseTask.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DdlToDatabaseTask.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DdlToDatabaseTask.java Sun Nov 5 23:20:18 2006 @@ -31,9 +31,13 @@ import org.apache.tools.ant.types.FileSet; /** - * Ant task for working with DDL, e.g. generating the database from a schema, inserting data. + * This is the container for sub tasks that operate in the direction file -> database, e.g. + * 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. * * @version $Revision: 289996 $ + * @ant.task name="ddlToDatabase" */ public class DdlToDatabaseTask extends DatabaseTaskBase { @@ -47,9 +51,12 @@ private boolean _validateXml = false; /** - * Specifies whether XML input files are validated against the internal or an external DTD. + * Specifies 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. * * @param useInternalDtd true if input files are to be validated against the internal DTD + * @ant.not-required Default is true. */ public void setUseInternalDtd(boolean useInternalDtd) { @@ -57,9 +64,10 @@ } /** - * Specifies whether XML input files are validated at all. + * Specifies whether XML input files should be validated against the DTD. * * @param validateXml true if input files are to be validated + * @ant.not-required Default is false. */ public void setValidateXml(boolean validateXml) { @@ -77,9 +85,11 @@ } /** - * Set the xml schema describing the application model. + * The single file that contains the database file. You can use this instead of embedded + * fileset elements if you only have one schema file. * * @param schemaFile The schema + * @ant.not-required Use either this or one or more embedded fileset elements. */ public void setSchemaFile(File schemaFile) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DropDatabaseCommand.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DropDatabaseCommand.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DropDatabaseCommand.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DropDatabaseCommand.java Sun Nov 5 23:20:18 2006 @@ -27,9 +27,13 @@ import org.apache.tools.ant.Task; /** - * Command for dropping a database. + * The sub task for dropping the target database. Note that this is only supported on some database + * platforms. See here for details on which platforms support this.
+ * This sub task does not require schema files. Therefore the fileset subelement and + * the schemaFile attribute of the task can be omitted. * * @version $Revision: 289996 $ + * @ant.task name="dropDatabase" */ public class DropDatabaseCommand extends DatabaseCommand { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DumpMetadataTask.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DumpMetadataTask.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DumpMetadataTask.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DumpMetadataTask.java Sun Nov 5 23:20:18 2006 @@ -46,9 +46,10 @@ import org.dom4j.io.XMLWriter; /** - * A simple task that dumps information about a database. + * A simple helper task that dumps information about a database using JDBC. * * @version $Revision: 289996 $ + * @ant.task name="dumpMetadata" */ public class DumpMetadataTask extends Task { @@ -89,9 +90,10 @@ } /** - * Set the output file. + * Specifies the output file to which the database metadata is written to. * * @param outputFile The output file + * @ant.required */ public void setOutputFile(File outputFile) { @@ -99,9 +101,10 @@ } /** - * Set the encoding of the output file. + * Specifies the encoding of the output file. * * @param encoding The encoding + * @ant.not-required Per default, UTF-8 is used. */ public void setOutputEncoding(String encoding) { @@ -109,9 +112,10 @@ } /** - * Sets the catalog pattern. + * Sets the catalog pattern used when accessing the database. * * @param catalogPattern The catalog pattern + * @ant.not-required Per default, no specific catalog is used (value %). */ public void setCatalogPattern(String catalogPattern) { @@ -119,9 +123,10 @@ } /** - * Sets the schema pattern. + * Sets the schema pattern used when accessing the database. * * @param schemaPattern The schema pattern + * @ant.not-required Per default, no specific schema is used (value %). */ public void setSchemaPattern(String schemaPattern) { @@ -129,9 +134,11 @@ } /** - * Sets the table pattern. + * Specifies the table to be processed. For details see + * java.sql.DatabaseMetaData#getTables. * * @param tablePattern The table pattern + * @ant.not-required By default, all tables are read (value %). */ public void setTablePattern(String tablePattern) { @@ -139,9 +146,11 @@ } /** - * Sets the procedure pattern. + * Specifies the procedures to be processed. For details and typical table types see + * java.sql.DatabaseMetaData#getProcedures. * * @param procedurePattern The procedure pattern + * @ant.not-required By default, all procedures are read (value %). */ public void setProcedurePattern(String procedurePattern) { @@ -149,9 +158,11 @@ } /** - * Sets the column pattern. + * Specifies the columns to be processed. For details and typical table types see + * java.sql.DatabaseMetaData#getColumns. * * @param columnPattern The column pattern + * @ant.not-required By default, all columns are read (value %). */ public void setColumnPattern(String columnPattern) { @@ -159,9 +170,11 @@ } /** - * Sets the table types as a comma-separated list. + * Specifies the table types to be processed. For details and typical table types see + * java.sql.DatabaseMetaData#getTables. * - * @param tableTypes The table types + * @param tablePattern The table pattern + * @ant.not-required By default, all types of tables are read. */ public void setTableTypes(String tableTypes) { @@ -188,6 +201,7 @@ * Specifies whether procedures shall be read from the database. * * @param readProcedures true if procedures shall be read + * @ant.not-required By default, procedures are read. */ public void setDumpProcedures(boolean readProcedures) { @@ -198,6 +212,7 @@ * Specifies whether tables shall be read from the database. * * @param readTables true if tables shall be read + * @ant.not-required By default, tables are read. */ public void setDumpTables(boolean readTables) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/Parameter.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/Parameter.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/Parameter.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/Parameter.java Sun Nov 5 23:20:18 2006 @@ -25,10 +25,12 @@ import org.apache.ddlutils.PlatformFactory; /** - * A parameter which consists of a name-value pair and an optional list of platforms - * for which the parameter is applicable. + * Specifies a parameter for the creation of the database. These are usually platform specific. + * A parameter consists of a name-value pair and an optional list of platforms for which the + * parameter shall be used. * * @version $Revision: 231306 $ + * @ant.type name="parameter" */ public class Parameter { @@ -50,9 +52,11 @@ } /** - * Sets the name. + * Specifies the name of the parameter. See here + * for the parameters supported by the individual platforms. * * @param name The name + * @ant.required */ public void setName(String name) { @@ -70,9 +74,10 @@ } /** - * Sets the value. + * Specifies the parameter value. * * @param value The value + * @ant.not-required If none is given, null is used. */ public void setValue(String value) { @@ -80,9 +85,12 @@ } /** - * Sets the platforms - a comma-separated list of platform names - for which this parameter shall be used. + * Specifies the platforms - a comma-separated list of platform names - for which this parameter + * shall be used (see the databaseType attribute of the tasks possible values). + * For every platform not in this list, the parameter is ignored. * * @param platforms The platforms + * @ant.not-required If not specified then the parameter is processed for every platform. */ public void setPlatforms(String platforms) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/PlatformConfiguration.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/PlatformConfiguration.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/PlatformConfiguration.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/PlatformConfiguration.java Sun Nov 5 23:20:18 2006 @@ -29,6 +29,7 @@ * Encloses the platform configuration for the Ant tasks. * * @version $Revision: 329426 $ + * @ant.type ignore="true" */ public class PlatformConfiguration { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/TableSpecificParameter.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/TableSpecificParameter.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/TableSpecificParameter.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/TableSpecificParameter.java Sun Nov 5 23:20:18 2006 @@ -26,21 +26,26 @@ import org.apache.ddlutils.model.Table; /** - * A {@link org.apache.ddlutils.task.Parameter} intended for specific tables. - * - * TODO: Some wildcard/regular expression mechanism would be useful + * Specifies a parameter for the creation of the tables. These are usually platform specific. + * Note that parameters are only applied when creating new tables, not when altering existing ones. + * Note that if no table name is specified, the parameter is applied to all tables. * * @version $Revision: 231306 $ + * @ant.type name="tableParameter" */ public class TableSpecificParameter extends Parameter { + // TODO: Some wildcard/regular expression mechanism would be useful + /** The tables for which this parameter is applicable. */ private ArrayList _tables = new ArrayList(); /** - * Sets the tables as a comma-separated list. + * Specifies the comma-separated list of table names where this parameter shall be applied. * * @param tableList The tables + * @ant.not-required Use this or the table parameter. If neiter is specified, + * the parameter is applied to all tables. */ public void setTables(String tableList) { @@ -56,9 +61,11 @@ } /** - * Sets the single table. + * Specifies the name of the table where this parameter shall be applied. * * @param tableName The table + * @ant.not-required Use this or the tables parameter. If neiter is specified, + * the parameter is applied to all tables. */ public void setTable(String tableName) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDataToDatabaseCommand.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDataToDatabaseCommand.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDataToDatabaseCommand.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDataToDatabaseCommand.java Sun Nov 5 23:20:18 2006 @@ -35,9 +35,19 @@ import org.apache.tools.ant.types.FileSet; /** - * Command for inserting data into a database. + * 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. * * @version $Revision: 289996 $ + * @ant.task name="writeDataToDatabase" */ public class WriteDataToDatabaseCommand extends ConvertingDatabaseCommand { @@ -63,9 +73,10 @@ } /** - * Set the xml data file. + * Specifies the name of the single XML file that contains the data to insert into the database. * * @param dataFile The data file + * @ant.not-required If not specified, no data is inserted into the database upon creation. */ public void setDataFile(File dataFile) { @@ -73,9 +84,12 @@ } /** - * Sets the maximum number of objects to insert in one batch. + * 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. * * @param batchSize The number of objects + * @ant.not-required The default value is 1 */ public void setBatchSize(int batchSize) { @@ -83,9 +97,14 @@ } /** - * Specifies whether batch mode shall be used. + * Specifies whether batch mode shall be used 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. * * @param useBatchMode true if batch mode shall be used + * @ant.not-required Per default, batch mode is not used */ public void setUseBatchMode(boolean useBatchMode) { @@ -93,10 +112,14 @@ } /** - * Specifies whether the foreign key order shall be honored when inserted - * data into the database. + * Specifies whether the foreign key order shall be honored when inserted data into the database. + * Otherwise, DdlUtils will simply assume that the entry order is ok. Note that execution will + * be slower when DdlUtils has to ensured in the inserted data, so if you know that the data is + * specified in foreign key order (i.e. referenced rows come before referencing rows), then + * turn this off. * * @param ensureFKOrder true if the foreign key order shall be followed + * @ant.not-required Per default, foreign key order is honored */ public void setEnsureForeignKeyOrder(boolean ensureFKOrder) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDataToFileCommand.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDataToFileCommand.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDataToFileCommand.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDataToFileCommand.java Sun Nov 5 23:20:18 2006 @@ -30,9 +30,10 @@ import org.apache.tools.ant.Task; /** - * Command to dump data from the database into an XML file. + * Generates an XML file containing the data currently stored in the database. * * @version $Revision: 289996 $ + * @ant.task name="writeDataToFile" */ public class WriteDataToFileCommand extends ConvertingDatabaseCommand { @@ -42,9 +43,10 @@ private String _encoding; /** - * Sets the file to output the data to. + * Specifies the file to write the data XML to. * * @param outputFile The output file + * @ant.required */ public void setOutputFile(File outputFile) { @@ -52,9 +54,10 @@ } /** - * Sets the output encoding. + * Specifies the encoding of the XML file. * * @param encoding The encoding + * @ant.not-required The default encoding is UTF-8. */ public void setEncoding(String encoding) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDtdToFileCommand.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDtdToFileCommand.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDtdToFileCommand.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteDtdToFileCommand.java Sun Nov 5 23:20:18 2006 @@ -29,9 +29,12 @@ import org.apache.tools.ant.Task; /** - * The command for creating a data DTD for a given database model. + * Creates a DTD that specifies the layout for data XML files.
+ * This sub task does not require a database connection, so the dataSource + * subelement of the task can be omitted. * * @version $Revision: 289996 $ + * @ant.task name="writeDtdToFile" */ public class WriteDtdToFileCommand implements Command { @@ -39,9 +42,10 @@ private File _outputFile; /** - * Sets the file to output the DTD to. + * Specifies the name of the file to write the DTD to. * * @param outputFile The output file + * @ant.required */ public void setOutputFile(File outputFile) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaSqlToFileCommand.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaSqlToFileCommand.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaSqlToFileCommand.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaSqlToFileCommand.java Sun Nov 5 23:20:18 2006 @@ -32,9 +32,13 @@ import org.apache.tools.ant.Task; /** - * Creates the SQL for a schema and writes it to a file. + * 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. * * @version $Revision: 289996 $ + * @ant.task name="writeSchemaSqlToFile" */ public class WriteSchemaSqlToFileCommand extends DatabaseCommandWithCreationParameters { @@ -46,9 +50,10 @@ private boolean _doDrops = true; /** - * Sets the file to output the sql to. + * Specifies the name of the file to write the SQL commands to. * * @param outputFile The output file + * @ant.required */ public void setOutputFile(File outputFile) { @@ -66,9 +71,11 @@ } /** - * Specifies whether to alter the database if it already exists, or re-set it. + * Specifies whether DdlUtils shall alter an existing database rather than clearing it and + * creating it new. * * @param alterTheDb true if to alter the database + * @ant.not-required Per default, SQL for altering the database is created */ public void setAlterDatabase(boolean alterTheDb) { @@ -86,9 +93,11 @@ } /** - * Specifies whether to drop tables and the associated constraints if necessary. + * Specifies whether SQL for dropping tables, external constraints, etc. is created if necessary. + * Note that this is only relevant when alterDatabase is false. * * @param doDrops true if drops shall be performed if necessary + * @ant.not-required Per default, drop SQL statements are created */ public void setDoDrops(boolean doDrops) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaToDatabaseCommand.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaToDatabaseCommand.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaToDatabaseCommand.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaToDatabaseCommand.java Sun Nov 5 23:20:18 2006 @@ -27,9 +27,11 @@ import org.apache.tools.ant.Task; /** - * Command for writing a database schema into the database. + * Creates the schema in the database that is described by the schema XML files specified for + * the enclosing task. * * @version $Revision: 289996 $ + * @ant.task name="writeSchemaToDatabase" */ public class WriteSchemaToDatabaseCommand extends DatabaseCommandWithCreationParameters { @@ -49,9 +51,11 @@ } /** - * Specifies whether to alter the database if it already exists, or re-set it. + * Specifies whether DdlUtils shall alter an existing database rather than clearing it and + * creating it new. * * @param alterTheDb true if to alter the database + * @ant.not-required Per default, an existing database is altered */ public void setAlterDatabase(boolean alterTheDb) { @@ -69,9 +73,11 @@ } /** - * Specifies whether to drop tables and the associated constraints if necessary. + * Specifies whether tables, external constraints, etc. can be dropped if necessary. + * Note that this is only relevant when alterDatabase is false. * * @param doDrops true if drops shall be performed + * @ant.not-required Per default, database structures are dropped if necessary */ public void setDoDrops(boolean doDrops) { Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaToFileCommand.java URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaToFileCommand.java?view=diff&rev=471653&r1=471652&r2=471653 ============================================================================== --- db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaToFileCommand.java (original) +++ db/ddlutils/trunk/src/java/org/apache/ddlutils/task/WriteSchemaToFileCommand.java Sun Nov 5 23:20:18 2006 @@ -29,9 +29,10 @@ import org.apache.tools.ant.Task; /** - * Command for writing the database schema to a file. + * Dumps the schema in the live database specified in the enclosing task, to a schema XML file. * * @version $Revision: 289996 $ + * @ant.task name="writeSchemaToFile" */ public class WriteSchemaToFileCommand implements Command { @@ -39,9 +40,10 @@ private File _outputFile; /** - * Sets the file to output the schema to. + * Specifries the name of the file to write the schema XML to. * * @param outputFile The output file + * @ant.required */ public void setOutputFile(File outputFile) {