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/12 09:40:46 UTC
svn commit: r473907 - in /db/ddlutils/trunk: ./ src/antdoc/
src/antdoc/templates/html/ src/java/org/apache/ddlutils/task/
Author: tomdz
Date: Sun Nov 12 00:40:45 2006
New Revision: 473907
URL: http://svn.apache.org/viewvc?view=rev&rev=473907
Log:
Enhancements to the Ant task documentation
Removed:
db/ddlutils/trunk/src/antdoc/templates/html/style.css
Modified:
db/ddlutils/trunk/build.xml
db/ddlutils/trunk/dump-metadata.xml
db/ddlutils/trunk/src/antdoc/styles.css
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/overview.vm
db/ddlutils/trunk/src/antdoc/templates/html/task.vm
db/ddlutils/trunk/src/antdoc/templates/html/taskindex.vm
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/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/Parameter.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.xml
URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/build.xml?view=diff&rev=473907&r1=473906&r2=473907
==============================================================================
--- db/ddlutils/trunk/build.xml (original)
+++ db/ddlutils/trunk/build.xml Sun Nov 12 00:40:45 2006
@@ -219,6 +219,7 @@
</javadoc>
<copy todir="${build.antdoc.dir}">
<fileset dir="${src.antdoc.dir}" includes="*.css,*.js"/>
+ <fileset dir="${antdoc.templates.dir}/html" includes="*.htm*"/>
</copy>
</target>
Modified: db/ddlutils/trunk/dump-metadata.xml
URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/dump-metadata.xml?view=diff&rev=473907&r1=473906&r2=473907
==============================================================================
--- db/ddlutils/trunk/dump-metadata.xml (original)
+++ db/ddlutils/trunk/dump-metadata.xml Sun Nov 12 00:40:45 2006
@@ -78,8 +78,8 @@
description="Dumps the database model using the connection properties from the file specified via the jdbc.properties.file environment variable">
<databaseToDdl databasetype="${ddlutils.platform}"
tabletypes="${tabletypes}"
- catalog="${catalogpattern}"
- schema="${schemapattern}"
+ catalogpattern="${catalogpattern}"
+ schemapattern="${schemapattern}"
modelname="${modelname}">
<database driverclassname="${datasource.driverClassName}"
url="${datasource.url}"
Modified: db/ddlutils/trunk/src/antdoc/styles.css
URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/antdoc/styles.css?view=diff&rev=473907&r1=473906&r2=473907
==============================================================================
--- db/ddlutils/trunk/src/antdoc/styles.css (original)
+++ db/ddlutils/trunk/src/antdoc/styles.css Sun Nov 12 00:40:45 2006
@@ -1,9 +1,15 @@
body {
- width: 780px;
- margin-left: 20px;
+ width: 760px;
+ padding-left: 10px;
font: normal 14px/18px Tahoma,Verdana,Helvetica,Arial,sans-serif;
color: #000;
}
+body.index {
+ width: 200px;
+ padding-left: 0px;
+ padding-right: 10px;
+ overflow: hidden;
+}
a:link,
a:visited,
a:hover {
@@ -40,6 +46,12 @@
border: 1px solid #ddd;
padding: 10px;
}
+.taskDescription pre {
+ margin: 20px;
+}
+.taskShortDescription {
+ padding-left: 10px;
+}
fieldset.taskDescription,
fieldset.taskParameters,
fieldset.taskNestedElements {
@@ -82,6 +94,8 @@
margin-right: 20px;
}
.copyright {
- margin-top: 20px;
+ border-top: 1px solid #777;
+ margin-top: 10px;
+ padding-top: 10px;
font-size: 0.7em;
}
Modified: 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=diff&rev=473907&r1=473906&r2=473907
==============================================================================
--- db/ddlutils/trunk/src/antdoc/templates/html/index.html (original)
+++ db/ddlutils/trunk/src/antdoc/templates/html/index.html Sun Nov 12 00:40:45 2006
@@ -1,21 +1,16 @@
<?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" />
-
+<title>DdlUtils' Ant Tasks Documentation </title>
+</head>
+<frameset cols="210px, *">
+<frameset rows="25%, *">
+<frame name="libindex" src="libindex.html"/>
+<frame name="taskindex" src="index.all.html"/>
+</frameset>
+<frame name="task" src="overview.html" />
</frameset>
-
</html>
Modified: 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=diff&rev=473907&r1=473906&r2=473907
==============================================================================
--- db/ddlutils/trunk/src/antdoc/templates/html/libindex.vm (original)
+++ db/ddlutils/trunk/src/antdoc/templates/html/libindex.vm Sun Nov 12 00:40:45 2006
@@ -6,33 +6,26 @@
##
## Objects expected in context:
##
-## $title - Project title (of type String)
+## $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" />
+<title>$title</title>
+<link href="styles.css" type="text/css" rel="stylesheet">
</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 />
+<body class="index">
+<div>
+<h3>$title</h3>
+<p>
+<a href="overview.html" target="task">Overview</a>
+</p>
+<p>
+<a href="index.all.html" target="taskindex"><i>Core Tasks</i></a><br />
+#foreach ($category in $antroot.getCategories())
+<a href="index.${category}.html" target="taskindex">$category Tasks</a><br/>
#end
- </p>
-
- <a href="index.all.html" target="taskindex">
- <i>all</i>
- </a><br />
+</p>
</div>
</body>
</html>
Modified: 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=diff&rev=473907&r1=473906&r2=473907
==============================================================================
--- db/ddlutils/trunk/src/antdoc/templates/html/overview.vm (original)
+++ db/ddlutils/trunk/src/antdoc/templates/html/overview.vm Sun Nov 12 00:40:45 2006
@@ -6,11 +6,11 @@
<link href="styles.css" type="text/css" rel="stylesheet">
</head>
<body>
-<h1>$title - Documentation</h1>
+<h2>$title - Documentation</h2>
<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.
+database structure, insert data into the database, dump the database structure and data contained in it,
+to XML, etc.
</p>
<h3>Using the Tasks</h3>
<p>
@@ -49,13 +49,13 @@
</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>.
+This snippet essentially uses the <code>DdlToDatabaseTask</code> task to create a PostgreSQL
+database at <code>//localhost/test</code>, establish the database structure (tables, foreign keys
+etc.) defined in the file <code>src/schema/project-schema.xml</code> in this new database,
+and then insert the data contained 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 order for this to work, both DdlUtils and the JDBC driver have to be 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>
@@ -63,7 +63,8 @@
<legend>Note</legend>
<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>.
+documentation <a href="database-support.html">here</a> for details of what is supported
+with individual databases.
</p>
</fieldset>
<p>
@@ -96,18 +97,13 @@
</target></pre>
<p>
-Here, the database schema is retrieved via the specified JDBC driver and written
+Here, the database schema is retrieved using the specified JDBC driver, and then 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>
+<p>The reference documentation for the Ant tasks can be found <a href="index.all.html">here</a>.</p>
</body>
</html>
Modified: 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=diff&rev=473907&r1=473906&r2=473907
==============================================================================
--- db/ddlutils/trunk/src/antdoc/templates/html/task.vm (original)
+++ db/ddlutils/trunk/src/antdoc/templates/html/task.vm Sun Nov 12 00:40:45 2006
@@ -11,11 +11,11 @@
##
<html>
<head>
-<title><$taskDoc.getAntName()></title>
+<title>$taskDoc.getAntName()</title>
<link href="styles.css" type="text/css" rel="stylesheet">
</head>
<body>
-<h2>#if( $taskDoc.getAnyCategory().length() > 0 ) $!taskDoc.getAntCategory() : #end $taskDoc.getAntName()</h2>
+<h2>#if ($taskDoc.getAnyCategory().length() > 0) $!taskDoc.getAntCategory() : #end $taskDoc.getAntName()</h2>
<fieldset class="taskDescription">
<legend><a class="anchor" name="description">Description</a></legend>
<p>Java type: <a href="../javadoc/${taskDoc.getFullClassName().replace(".", "/")}.html"><code>$taskDoc.getFullClassName()</code></a></p>
@@ -68,6 +68,5 @@
#end
#end
</fieldset>
-<div class="copyright">Copyright © 2005-2006 The Apache Software Foundation. All rights reserved.</div>
</body>
</html>
Modified: 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=diff&rev=473907&r1=473906&r2=473907
==============================================================================
--- db/ddlutils/trunk/src/antdoc/templates/html/taskindex.vm (original)
+++ db/ddlutils/trunk/src/antdoc/templates/html/taskindex.vm Sun Nov 12 00:40:45 2006
@@ -6,60 +6,25 @@
##
## Objects expected in context:
##
-## $title - Project title (of type String)
+## $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" />
-
+<title>$title</title>
+<link href="styles.css" type="text/css" rel="stylesheet">
</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>
-
+<body class="index">
+<div>
+<h3>#if ($category == 'all') Core #else $category #end Tasks</h3>
+#foreach( $taskDoc in $antroot.getTasksByCategory($category) )
+ #if ($taskDoc && !$taskDoc.isInnerClass())
+<p><a href="${taskDoc.getFullClassName()}.html" target="task">Task <code>${taskDoc.getAntName()}</code></a></p>
+ #if ($taskDoc.getShortComment())
+<p class="taskShortDescription">$taskDoc.getShortComment()</p>
#end
#end
+#end
</div>
</body>
</html>
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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -32,9 +32,9 @@
/**
* 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.
+ * 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 enclosing task can be omitted.
*
* @version $Revision: 231306 $
* @ant.task name="createDatabase"
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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -98,10 +98,10 @@
}
/**
- * Specifies whether the execution shall stop if an error has occurred while the task runs.
+ * Specifies whether the execution shall stop if an error has occurred during the task runs.
*
* @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.
+ * @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/DatabaseTaskBase.java
URL: http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/task/DatabaseTaskBase.java?view=diff&rev=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -54,11 +54,11 @@
}
/**
- * Specifies the database type. You should only need to specify this if DdlUtils is not able to
+ * Specifies the database type. You should only need to set 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
+ * If you have 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,
+ * Valid values are currently:<br/><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
@@ -93,10 +93,12 @@
}
/**
- * Sets the catalog pattern used when accessing the database.
+ * Specifies a pattern that defines which database catalogs to use. For some
+ * more info on catalog patterns and JDBC, see
+ * <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/DatabaseMetaData.html">java.sql.DatabaseMetaData</a>.
*
* @param catalogPattern The catalog pattern
- * @ant.not-required Per default, no specific catalog is used.
+ * @ant.not-required Per default no specific catalog is used.
*/
public void setCatalogPattern(String catalogPattern)
{
@@ -107,10 +109,12 @@
}
/**
- * Sets the schema pattern used when accessing the database.
+ * Specifies a pattern that defines which database schemas to use. For some
+ * more info on schema patterns and JDBC, see
+ * <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/DatabaseMetaData.html">java.sql.DatabaseMetaData</a>.
*
* @param schemaPattern The schema pattern
- * @ant.not-required Per default, no specific schema is used.
+ * @ant.not-required Per default no specific schema is used.
*/
public void setSchemaPattern(String schemaPattern)
{
@@ -131,13 +135,15 @@
}
/**
- * 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.
+ * Specifies whether DdlUtils shall use delimited (quoted) identifiers (such as table and column
+ * names). Most databases convert undelimited identifiers to uppercase and ignore the case of
+ * identifiers when performing any SQL command. Undelimited identifiers also cannot be reserved
+ * words and can only contain alphanumerical characters and the underscore.<br/>
+ * These limitations do not exist for delimited identifiers where identifiers have to be enclosed
+ * in double quotes. Delimited identifiers can contain unicode characters, and even reserved
+ * words can be used as identifiers. Please be aware though, that they always have to enclosed
+ * in double quotes, and that the 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>.
@@ -159,9 +165,9 @@
}
/**
- * 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
+ * Specifies whether DdlUtils shall sort the foreign keys of a table read from a live database or
+ * leave them in the order in which they are returned by the database/JDBC driver. Note that
+ * the sort is case sensitive only if delimited 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
@@ -183,8 +189,8 @@
}
/**
- * Specifies whether the database shall be shut down after the task has finished.
- * This is mostly usefule for embedded databases.
+ * Specifies whether DdlUtils shall shut down the database after the task has finished.
+ * This is mostly useful for embedded databases.
*
* @param shutdownDatabase <code>true</code> if the database shall be shut down
* @ant.not-required Default is <code>false</code>.
@@ -223,7 +229,17 @@
{
return _commands.iterator();
}
-
+
+ /**
+ * Creates the platform configuration.
+ *
+ * @return The platform configuration
+ */
+ protected PlatformConfiguration getPlatformConfiguration()
+ {
+ return _platformConf;
+ }
+
/**
* Creates the platform for the configured database.
*
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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -26,59 +26,49 @@
import org.apache.tools.ant.BuildException;
/**
- * 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.
+ * Task for getting structural info and data from a live database. Eg. it has sub tasks for
+ * writing the schema of the live database or the data currently in it to an XML file, for
+ * creating the DTDs for these data files, and for generating SQL to creating a schema in the
+ * database to a file.
+ * <br/>
+ * Example:<br/>
+ * <pre>
+ * <taskdef classname="org.apache.ddlutils.task.DatabaseToDdlTask"
+ * name="databaseToDdl"
+ * classpathref="project-classpath" />
+ *
+ * <databaseToDdl usedelimitedsqlidentifiers="true"
+ * modelname="example">
+ * <database driverclassname="org.apache.derby.jdbc.ClientDriver"
+ * url="jdbc:derby://localhost/ddlutils"
+ * username="ddlutils"
+ * password="ddlutils"/>
+ *
+ * <writeschematofile outputfile="schema.xml"/>
+ * <writedatatofile outputfile="data.xml"
+ * encoding="ISO-8859-1"/>
+ * </databaseToDdl>
+ * </pre>
+ * This reads the schema and data from the database and writes them to XML files.
*
* @version $Revision: 289996 $
* @ant.task name="databaseToDdl"
*/
public class DatabaseToDdlTask extends DatabaseTaskBase
{
- /** The specific schema to use. */
- private String _schema;
- /** The specific catalog to use. */
- private String _catalog;
/** The table types to recognize when reading the model from the database. */
private String _tableTypes;
/** The name of the model read from the database. */
private String _modelName;
/**
- * 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)
- {
- _schema = schema;
- }
-
- /**
- * 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)
- {
- _catalog = catalog;
- }
-
- /**
- * Specifies the table types to be processed. For details and typical table types see
+ * Specifies the table types to be processed. More precisely, all tables that are of a
+ * type not in this list, will be ignored by the task and its sub tasks. 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.
+ * @ant.not-required By default, only tables of type <code>TABLE</code> are used by the task.
*/
public void setTableTypes(String tableTypes)
{
@@ -86,12 +76,13 @@
}
/**
- * 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.
+ * Specifies the name of the model that is read from the database. This is mostly useful
+ * for the the <code>writeSchemaToFile</code> sub-task as it ensures that the generated
+ * XML defines a valid model.
*
* @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.
+ * or <code>"default"</code> if no schema name was returned by the database.
*/
public void setModelName(String modelName)
{
@@ -187,7 +178,10 @@
try
{
- return getPlatform().readModelFromDatabase(_modelName, _catalog, _schema, getTableTypes());
+ return getPlatform().readModelFromDatabase(_modelName,
+ getPlatformConfiguration().getCatalogPattern(),
+ getPlatformConfiguration().getSchemaPattern(),
+ getTableTypes());
}
catch (Exception ex)
{
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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -31,10 +31,35 @@
import org.apache.tools.ant.types.FileSet;
/**
- * 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.
+ * Task for performing operations on a live database. Sub tasks e.g. create the
+ * schema in the database, drop database schemas, insert data into the database,
+ * create DTDs for data files, or write the SQL for creating a schema to a file.
+ * <br/>
+ * Example:<br/>
+ * <pre>
+ * <taskdef classname="org.apache.ddlutils.task.DdlToDatabaseTask"
+ * name="ddlToDatabase"
+ * classpathref="project-classpath"/>
+ *
+ * <ddlToDatabase usedelimitedsqlidentifiers="true">
+ * <database driverclassname="org.apache.derby.jdbc.ClientDriver"
+ * url="jdbc:derby://localhost/ddlutils"
+ * username="ddlutils"
+ * password="ddlutils"/>
+ * <fileset dir=".">
+ * <include name="*schema.xml"/>
+ * </fileset>
+ *
+ * <createdatabase failonerror="false"/>
+ * <writeschematodatabase alterdatabase="true"
+ * failonerror="false"/>
+ * <writedatatodatabase datafile="data.xml"
+ * usebatchmode="true"
+ * batchsize="1000"/>
+ * </ddlToDatabase>
+ * </pre>
+ * This Ant build file snippet essentially creates a database, creates tables, foreign keys
+ * etc. int it and then writes data into the newly created tables.
*
* @version $Revision: 289996 $
* @ant.task name="ddlToDatabase"
@@ -52,8 +77,8 @@
/**
* 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.
+ * it matches <code>http://db.apache.org/torque/dtd/database.dtd</code>). This is
+ * especially useful in environments where no web access is possible or desired.
*
* @param useInternalDtd <code>true</code> if input files are to be validated against the internal DTD
* @ant.not-required Default is <code>true</code>.
@@ -64,10 +89,10 @@
}
/**
- * Specifies whether XML input files should be validated against the DTD.
+ * Specifies whether XML input files should be validated against the DTD at all.
*
* @param validateXml <code>true</code> if input files are to be validated
- * @ant.not-required Default is <code>false</code>.
+ * @ant.not-required Default is <code>false</code> meaning that the XML is not validated at all.
*/
public void setValidateXml(boolean validateXml)
{
@@ -85,7 +110,7 @@
}
/**
- * The single file that contains the database file. You can use this instead of embedded
+ * Defines 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
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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -27,10 +27,10 @@
import org.apache.tools.ant.Task;
/**
- * The sub task for dropping the target database. Note that this is only supported on some database
+ * 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.
+ * the <code>schemaFile</code> attribute of the enclosing task can be omitted.
*
* @version $Revision: 289996 $
* @ant.task name="dropDatabase"
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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -86,7 +86,7 @@
/**
* 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).
+ * shall be used (see the <code>databaseType</code> attribute of the tasks for possible values).
* For every platform not in this list, the parameter is ignored.
*
* @param platforms The platforms
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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -28,10 +28,10 @@
/**
* 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.
+ * Note also that if no table name is specified, the parameter is used for all created tables.
*
* @version $Revision: 231306 $
- * @ant.type name="tableParameter"
+ * @ant.type name="parameter"
*/
public class TableSpecificParameter extends Parameter
{
@@ -41,11 +41,12 @@
private ArrayList _tables = new ArrayList();
/**
- * Specifies the comma-separated list of table names where this parameter shall be applied.
+ * Specifies the comma-separated list of table names in whose creation this parameter
+ * shall be used. For every table not in this list, the parameter is ignored.
*
* @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.
+ * @ant.not-required Use this or the <code>table</code> parameter. If neither is specified,
+ * the parameter is applied in the creation of all tables.
*/
public void setTables(String tableList)
{
@@ -61,11 +62,11 @@
}
/**
- * Specifies the name of the table where this parameter shall be applied.
+ * Specifies the name of the table in whose creation 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.
+ * @ant.not-required Use this or the <code>tables</code> parameter. If neither is specified,
+ * the parameter is applied in the creation of 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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -43,8 +43,9 @@
* 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.
+ * simply use some unique values for their columns. DdlUtils then will automatically use the real
+ * primary key values when inserting the data. Note though that not every database supports the
+ * retrieval of auto-increment values which is necessary for this to work.
*
* @version $Revision: 289996 $
* @ant.task name="writeDataToDatabase"
@@ -76,7 +77,7 @@
* 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.
+ * @ant.not-required Use either this or <code>fileset</code> sub elements.
*/
public void setDataFile(File dataFile)
{
@@ -89,7 +90,7 @@
* 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
+ * @ant.not-required The default value is 1.
*/
public void setBatchSize(int batchSize)
{
@@ -97,14 +98,15 @@
}
/**
- * 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.
+ * Specifies whether batch mode shall be used for inserting the data. In batch mode, insert statements
+ * for the same table are bundled together and executed as one statement. This can be a lot faster
+ * than single insert statements but is not supported by all JDBC drivers/databases. To achieve the
+ * highest performance, you should group the data in the XML file according to the tables. This is
+ * because a batch insert only works for one table at a time. Thus when the table changes in an
+ * entry in the XML file, the batch is committed and then a new one is started.
*
* @param useBatchMode <code>true</code> if batch mode shall be used
- * @ant.not-required Per default, batch mode is not used
+ * @ant.not-required Per default batch mode is not used.
*/
public void setUseBatchMode(boolean useBatchMode)
{
@@ -112,14 +114,14 @@
}
/**
- * 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.
+ * Specifies whether the foreign key order shall be honored when inserting data into the database.
+ * If not, DdlUtils will simply assume that the entry order is correct, i.e. that referenced rows
+ * come before referencing rows in the data XML. Note that execution will be slower when DdlUtils
+ * has to ensure the foreign-key order of the data. Thus if you know that the data is specified in
+ * foreign key order 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
+ * @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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -30,7 +30,8 @@
import org.apache.tools.ant.Task;
/**
- * Generates an XML file containing the data currently stored in the database.
+ * Reads the data currently in the table in the live database (as specified by the
+ * enclosing task), and writes it as XML to a file.
*
* @version $Revision: 289996 $
* @ant.task name="writeDataToFile"
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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -31,7 +31,7 @@
/**
* 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.
+ * sub element of the enclosing task can be omitted.
*
* @version $Revision: 289996 $
* @ant.task name="writeDtdToFile"
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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -32,10 +32,11 @@
import org.apache.tools.ant.Task;
/**
- * 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.
+ * Parses the schema XML files specified in the enclosing task, and writes the SQL statements
+ * necessary to create this schema in the database, to a file. Note that this SQL is
+ * database specific and hence this subtask requires that for the enclosing task, either a
+ * data source is specified (via the <code>database</code> sub element) or the
+ * <code>databaseType</code> attribute is used to specify the database type.
*
* @version $Revision: 289996 $
* @ant.task name="writeSchemaSqlToFile"
@@ -71,11 +72,11 @@
}
/**
- * Specifies whether DdlUtils shall alter an existing database rather than clearing it and
- * creating it new.
+ * Specifies whether DdlUtils shall generate SQL to alter an existing database rather
+ * than SQL for 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
+ * @param alterTheDb <code>true</code> if SQL to alter the database shall be created
+ * @ant.not-required Per default SQL for altering the database is created
*/
public void setAlterDatabase(boolean alterTheDb)
{
@@ -83,9 +84,10 @@
}
/**
- * Determines whether to drop tables and the associated constraints if necessary.
+ * Determines whether SQL is generated to drop tables and the associated constraints
+ * if necessary.
*
- * @return <code>true</code> if drops shall be performed if necessary
+ * @return <code>true</code> if drops SQL shall be generated if necessary
*/
protected boolean isDoDrops()
{
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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -27,8 +27,8 @@
import org.apache.tools.ant.Task;
/**
- * Creates the schema in the database that is described by the schema XML files specified for
- * the enclosing task.
+ * Parses the schema XML files specified for the enclosing task, and creates the corresponding
+ * schema in the database.
*
* @version $Revision: 289996 $
* @ant.task name="writeSchemaToDatabase"
@@ -55,7 +55,7 @@
* creating it new.
*
* @param alterTheDb <code>true</code> if to alter the database
- * @ant.not-required Per default, an existing database is altered
+ * @ant.not-required Per default an existing database is altered
*/
public void setAlterDatabase(boolean alterTheDb)
{
@@ -77,7 +77,7 @@
* 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
+ * @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=473907&r1=473906&r2=473907
==============================================================================
--- 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 12 00:40:45 2006
@@ -29,7 +29,8 @@
import org.apache.tools.ant.Task;
/**
- * Dumps the schema in the live database specified in the enclosing task, to a schema XML file.
+ * Reads the schema of the live database (as specified in the enclosing task), and writes
+ * it as XML to a file.
*
* @version $Revision: 289996 $
* @ant.task name="writeSchemaToFile"
@@ -40,7 +41,7 @@
private File _outputFile;
/**
- * Specifries the name of the file to write the schema XML to.
+ * Specifies the name of the file to write the schema XML to.
*
* @param outputFile The output file
* @ant.required