You are viewing a plain text version of this content. The canonical link for it is here.
Posted to ddlutils-dev@db.apache.org by to...@apache.org on 2006/11/06 08:20:19 UTC
svn commit: r471653 - in /db/ddlutils/trunk: ./ src/antdoc/
src/antdoc/templates/ src/antdoc/templates/html/
src/java/org/apache/ddlutils/task/
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.*">
<link href="http://java.sun.com/j2se/1.4.2/docs/api/"/>
@@ -191,6 +191,32 @@
<mkdir dir="${build.schemadoc.dir}"/>
<dtddoc destdir="${build.schemadoc.dir}" sourcedir="${src.java.dir}" includes="*.dtd"/>
+ </target>
+
+ <!-- ================================================================== -->
+ <!-- Builds the documentation for the Ant tasks -->
+ <!-- ================================================================== -->
+ <target name="antdoc"
+ description="Builds the documentation for the Ant tasks">
+ <available classname="com.neuroning.antdoclet.AntDoclet"
+ classpathref="compilation-classpath"
+ property="antdoc.available"/>
+ <fail unless="antdoc.available" message="For building the Ant task documentaion, you'll need AntDoc which can be downloaded from http://antdoclet.neuroning.com/. Please make the AntDoc libraries available in the classpath."/>
+ <mkdir dir="${build.antdoc.dir}"/>
+ <javadoc sourcepath="${src.java.dir}"
+ classpathref="compilation-classpath"
+ destdir="${build.antdoc.dir}"
+ doctitle="${antdoc.title}"
+ protected="true"
+ author="false"
+ version="true"
+ packagenames="org.apache.ddlutils.task">
+ <doclet name="com.neuroning.antdoclet.AntDoclet"
+ pathref="compilation-classpath">
+ <param name="-templatesdir" value="${antdoc.templates.dir}"/>
+ <param name="-templates" value="html/main.vm" />
+ </doclet>
+ </javadoc>
</target>
<!-- ================================================================== -->
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 @@
+<?xml version="1.0" encoding="UTF8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN">
+
+<html>
+<head>
+ <title>Ant Tasks Documentation </title>
+ </head>
+
+<frameset cols="30,70">
+
+ <frameset rows="20,80">
+ <frame name="libindex" src="libindex.html"/>
+ <frame name="taskindex" src="index.all.html"/>
+ </frameset>
+ <frame name="task" src="overview.html" />
+
+</frameset>
+
+</html>
+
+
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+##
+## 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)
+##
+<html>
+<head>
+ <title>$title Ant Libraries</title>
+ <link rel="stylesheet" type="text/css" href="style.css" />
+</head>
+<body>
+
+<div id="navigation">
+
+ <a href="overview.html" target="task">
+ <h2>$title Ant Libs</h2>
+ </a>
+ <p>
+## Iterate through the Categories
+#foreach( $category in $antroot.getCategories() )
+ <a href="index.${category}.html" target="taskindex">
+ $category
+ </a><br />
+#end
+ </p>
+
+ <a href="index.all.html" target="taskindex">
+ <i>all</i>
+ </a><br />
+</div>
+</body>
+</html>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head>
+ <title>$title</title>
+<style type="text/css">
+ /* */
+ @import "skin/tigris.css";
+ @import "skin/quirks.css";
+ @import "skin/inst.css";
+ /* */
+ </style>
+<link media="print" href="skin/print.css" type="text/css" rel="stylesheet">
+<link href="skin/forrest.css" type="text/css" rel="stylesheet">
+
+</head>
+<body>
+
+<h1>$title - Documentation</h1>
+
+<p>
+DdlUtils comes with two <a href="http://ant.apache.org/">Ant</a> 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.
+</p>
+
+<h3>Using the Tasks</h3>
+
+<p>
+Lets see examples for how to use them:
+</p>
+<pre class="code">
+<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></pre>
+<p>
+This snippet essentially uses the <code>DdlToDatabaseTask</code> task to create the a PostgreSQL
+database at <code>//localhost/test</code>, establish the database structure (tables etc.)
+defined in the file <code>src/schema/project-schema.xml</code> in this database, and then
+inserts the data defined in <code>src/data/data.xml</code>.
+</p>
+<p>
+Required for this to work is that both DdlUtils and the JDBC driver are available
+in the path specified by <code>runtime-classpath</code>. In the above snippet, this path
+contains all JARs and ZIPs in sub-directory <code>lib</code>.
+</p>
+<div class="infomessage">
+<p>
+<strong>Note</strong>
+</p>
+<p>
+Not every database platform supports creation of new databases via JDBC. Please refer to the
+documentation of the support for the individual databases <a href="database-support.html">here</a>.
+</p>
+</div>
+<p>
+The opposite direction is achieved via the <code>DatabaseToDdlTask</code> task:
+</p>
+<pre class="code">
+<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></pre>
+<p>
+Here, the database schema is retrieved via the specified JDBC driver and written
+to the file <code>db-schema.xml</code>. Likewise, the data in the database is written
+to the file <code>data.xml</code>.
+</p>
+
+
+<h3>Requirements</h3>
+<p>The DdlUtils tasks require Ant version 1.5 or newer.</p>
+
+<h3>Reference</h3>
+<p>The tasks reference documentation can be found <a href="index.all.html">here</a>.</p>
+
+<div class="copyright">
+ <hr />
+ <br />
+ <em>Copyright © 2005-2006 Apache Software Foundation. All Rights Reserved.</em>
+</div>
+
+
+</body>
+</html>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+##
+## 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)
+##
+##
+<html>
+<head>
+<title><$taskDoc.getAntName()></title>
+<link rel="stylesheet" type="text/css" href="style.css" />
+</head>
+<body>
+<h2>#if( $taskDoc.getAnyCategory().length() > 0 ) $!taskDoc.getAntCategory() : #end $taskDoc.getAntName()</h2>
+<h3>Type</h3>
+<p>$taskDoc.getFullClassName()</p>
+<h3>Description</h3>
+<p>$taskDoc.getComment()</p>
+<h3><a name="attributes"><strong>Parameters</strong></a></h3>
+#foreach ($attr in $taskDoc.attributes )
+ <h4>$attr</h4>
+ <table>
+ <tr>
+ <td><b>Type</b></td>
+ <td>$taskDoc.getAttributeType($attr)</td>
+ </tr>
+ <tr>
+ <td><b>Required?</b></td>
+ <td>
+ #if ($taskDoc.getAttributeRequired($attr))
+ <b>Yes</b> $taskDoc.getAttributeRequired($attr)
+ #elseif ($taskDoc.getAttributeNotRequired($attr))
+ <b>No</b> $taskDoc.getAttributeNotRequired($attr)
+ #else
+ <i>unknown</i>
+ #end
+ </td>
+ </tr>
+ </table>
+ <p>$taskDoc.getAttributeComment($attr)</p>
+#end
+<h3>Nested elements</h3>
+#if ($taskDoc.isTaskContainer())
+<p>This Task is a Container (it accepts nested Tasks).</p>
+#end
+#if ($taskDoc.supportsCharacters())
+<p>This Task accepts text in its element body.</p>
+#end
+#foreach ($element in $taskDoc.getNestedElements())
+ #set ($elementDoc = $taskDoc.getElementDoc($element))
+ #if ($elementDoc.sourceIncluded() && $elementDoc.isTagged())
+ <h4><a href="${elementDoc.getFullClassName()}.html"><strong><$element> ...</strong></a></h4>
+ #else
+ <h4><strong><$element></strong>#if (!$elementDoc.sourceIncluded()) (Of type ${elementDoc.getAntName()}) #end </h4>
+ #if($elementDoc.getComment())
+ <p>$elementDoc.getComment()</p>
+ #end
+ <strong>Parameters</strong>
+ #foreach ($attr in $elementDoc.attributes )
+ <h5>$attr</h5>
+ <table>
+ <tr>
+ <td><b>Type</b></td>
+ <td>$elementDoc.getAttributeType($attr)</td>
+ </tr>
+ <tr>
+ <td><b>Required?</b></td>
+ <td>
+ #if ($elementDoc.getAttributeRequired($attr))
+ <b>Yes</b> $elementDoc.getAttributeRequired($attr)
+ #elseif ($elementDoc.getAttributeNotRequired($attr))
+ <b>No</b> $elementDoc.getAttributeNotRequired($attr)
+ #else
+ <i>unknown</i>
+ #end
+ </td>
+ </tr>
+ </table>
+ #if($elementDoc.getAttributeComment($attr))
+ <p>$elementDoc.getAttributeComment($attr)</p>
+ #end
+ #end
+ #end
+#end
+ </div>
+ <br />
+ <hr />
+
+ <div class="copyright"><em>Generated with <a href="http://antdoclet.neuroning.com">AntDoclet</a></em></div>
+
+</body>
+</html>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+##
+## 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)
+##
+<html>
+<head>
+ <title>$title Ant Tasks</title>
+ <link rel="stylesheet" type="text/css" href="style.css" />
+
+</head>
+<body>
+
+<div id="navigation">
+
+ ## Tasks
+<h2>$category Tasks</h2>
+
+ #foreach( $taskDoc in $antroot.getTasksByCategory($category) )
+ #if($taskDoc && !$taskDoc.isInnerClass())
+
+<p><a href="${taskDoc.getFullClassName()}.html" target="task">
+ Task <${taskDoc.getAntName()}>
+ </a>
+</p>
+ <div class="description">
+ #if($taskDoc.getShortComment())
+ $taskDoc.getShortComment()
+ #else
+ <i>No comment available</i>
+ #end
+</div>
+ #end
+ #end
+
+
+ ## Types
+<h2>$category Types</h2>
+
+ #foreach( $taskDoc in $antroot.getTypesByCategory($category) )
+ #if($taskDoc && !$taskDoc.isInnerClass() && $taskDoc.isTagged())
+<p><a href="${taskDoc.getFullClassName()}.html" target="task">
+ Type <${taskDoc.getAntName()}>
+ </a>
+</p>
+
+<div class="description">
+ #if($taskDoc.getShortComment())
+ $taskDoc.getShortComment()
+ #else
+ <i>No comment available</i>
+ #end
+</div>
+
+ #end
+ #end
+</div>
+</body>
+</html>
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 <a href="database-support.html">here</a> for details on which platforms support this.<br/>
+ * This sub task does not require schema files. Therefore the <code>fileset</code> subelement and
+ * the <code>schemaFile</code> 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 <code>true</code> if the execution stops in case of an error
+ * @param failOnError <code>true</code> 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.<br/>
+ * Valid values are currently: <code>axion, cloudscape, db2, derby, firebird, hsqldb, interbase,
+ * maxdb, mckoi, mssql, mysql, mysql5, oracle, oracle9, oracle10, postgresql, sapdb, sybase</code>
*
* @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.<br/>
+ * 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 <code>true</code> if delimited SQL identifiers shall be used
+ * @ant.not-required Default is <code>false</code>.
*/
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
+ * (<code>useDelimitedSqlIdentifiers</code> is set to <code>true</code>).
*
* @param sortForeignKeys <code>true</code> if the foreign keys shall be sorted
+ * @ant.not-required Default is <code>false</code>.
*/
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 <code>true</code> if the database shall be shut down
+ * @ant.not-required Default is <code>false</code>.
*/
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
+ * <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/DatabaseMetaData.html#getTables(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String[])">java.sql.DatabaseMetaData#getTables</a>.
+ * The special pattern <code>'%'</code> 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
+ * <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/DatabaseMetaData.html#getTables(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String[])">java.sql.DatabaseMetaData#getTables</a>.
+ * The special pattern <code>'%'</code> 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
+ * <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/DatabaseMetaData.html#getTables(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String[])">java.sql.DatabaseMetaData#getTables</a>.
*
* @param tableTypes The table types as a comma-separated list
+ * @ant.not-required By default, only tables of type <code>TABLE</code> are read.
*/
public void setTableTypes(String tableTypes)
{
@@ -73,10 +86,12 @@
}
/**
- * Sets the name that the model read from the database shall have.
- * Use <code>null</code> 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 <code>writeSchemaToFile</code> sub-task is used.
*
- * @param modelName The model name
+ * @param modelName The model name. Use <code>null</code> or an empty string for the default name
+ * @ant.not-required By default, DldUtils uses the schema name returned from the database
+ * or <code>default</code> 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 <code>http://db.apache.org/torque/dtd/database.dtd</code>). This is useful for
+ * instance for environments where no web access is possible.
*
* @param useInternalDtd <code>true</code> if input files are to be validated against the internal DTD
+ * @ant.not-required Default is <code>true</code>.
*/
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 <code>true</code> if input files are to be validated
+ * @ant.not-required Default is <code>false</code>.
*/
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
+ * <code>fileset</code> 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 <a href="database-support.html">here</a> for details on which platforms support this.<br/>
+ * This sub task does not require schema files. Therefore the <code>fileset</code> subelement and
+ * the <code>schemaFile</code> 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, <code>UTF-8</code> 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 <code>%</code>).
*/
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 <code>%</code>).
*/
public void setSchemaPattern(String schemaPattern)
{
@@ -129,9 +134,11 @@
}
/**
- * Sets the table pattern.
+ * Specifies the table to be processed. For details see
+ * <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/DatabaseMetaData.html#getTables(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String[])">java.sql.DatabaseMetaData#getTables</a>.
*
* @param tablePattern The table pattern
+ * @ant.not-required By default, all tables are read (value <code>%</code>).
*/
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
+ * <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/DatabaseMetaData.html#getProcedures(java.lang.String,%20java.lang.String,%20java.lang.String)">java.sql.DatabaseMetaData#getProcedures</a>.
*
* @param procedurePattern The procedure pattern
+ * @ant.not-required By default, all procedures are read (value <code>%</code>).
*/
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
+ * <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/DatabaseMetaData.html#getColumns(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String[])">java.sql.DatabaseMetaData#getColumns</a>.
*
* @param columnPattern The column pattern
+ * @ant.not-required By default, all columns are read (value <code>%</code>).
*/
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
+ * <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/DatabaseMetaData.html#getTables(java.lang.String,%20java.lang.String,%20java.lang.String,%20java.lang.String[])">java.sql.DatabaseMetaData#getTables</a>.
*
- * @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 <code>true</code> 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 <code>true</code> 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 <a href="database-support.html">here</a>
+ * for the parameters supported by the individual platforms.</td>
*
* @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, <code>null</code> 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 <code>databaseType</code> 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 <code>table</code> 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 <code>tables</code> 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.<br/>
+ * 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
+ * <code>ensureForeignKeyOrder</code> attribute.<br/>
+ * 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.<br/>
+ * This value is only used if <code>useBatchMode</code> is <code>true</code>.
*
* @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 <code>true</code> 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 <code>true</code> 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 <code>UTF-8</code>.
*/
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.<br/>
+ * This sub task does not require a database connection, so the <code>dataSource</code>
+ * 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
+ * <code>databaseType</code> 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 <code>true</code> 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 <code>alterDatabase</code> is <code>false</code>.
*
* @param doDrops <code>true</code> 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 <code>true</code> 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 <code>alterDatabase</code> is <code>false</code>.
*
* @param doDrops <code>true</code> 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)
{