Author: tomdz
Date: Sun Nov 5 19:03:11 2006
New Revision: 471621
URL: http://svn.apache.org/viewvc?view=rev&rev=471621
Log:
Documentation enhancements/fixes
Modified:
db/ddlutils/trunk/build.properties
db/ddlutils/trunk/build.xml
db/ddlutils/trunk/lib/build-only/ (props changed)
db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/api-usage.xml
db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/schema.xml
db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/site.xml
db/ddlutils/trunk/src/doc/src/documentation/skinconf.xml
db/ddlutils/trunk/src/java/database.dtd
db/ddlutils/trunk/src/java/org/apache/ddlutils/dynabean/SqlDynaException.java
db/ddlutils/trunk/src/java/org/apache/ddlutils/dynabean/package.html
db/ddlutils/trunk/src/java/org/apache/ddlutils/platform/oracle/package.html
Modified: db/ddlutils/trunk/build.properties
URL:
http://svn.apache.org/viewvc/db/ddlutils/trunk/build.properties?view=diff&rev=471621&r1=471620&r2=471621
==============================================================================
--- db/ddlutils/trunk/build.properties (original)
+++ db/ddlutils/trunk/build.properties Sun Nov 5 19:03:11 2006
@@ -25,6 +25,7 @@
build.java.dir=${build.dir}/classes
build.test.dir=${build.dir}/test
build.javadoc.dir=${build.dir}/javadoc
+build.schemadoc.dir=${build.dir}/schemadoc
build.doc.dir=${build.dir}/doc
build.check.dir=${build.dir}/check
@@ -32,7 +33,7 @@
doc.dir=doc
project-name=DdlUtils
-version=1.0-dev
+version=1.0-RC1
dist-filename-prefix=${project-name}-${version}
checkstyle.version.pattern=\\$Revision.*\\$
@@ -49,4 +50,5 @@
javadoc.footer=Copyright © 2005 Apache Software Foundation. All Rights
Reserved.
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=471621&r1=471620&r2=471621
==============================================================================
--- db/ddlutils/trunk/build.xml (original)
+++ db/ddlutils/trunk/build.xml Sun Nov 5 19:03:11 2006
@@ -87,8 +87,7 @@
<!-- Build the documentation -->
<!-- ================================================================== -->
<target name="doc"
- depends="javadoc"
- description="Builds the complete documentation using Forrest">
+ description="Builds the complete documentation">
<fail message="Please set the FORREST_HOME environment variable to the
'src/core' subdirectory of your Forrest installation. If you don't have yet
installed Forrest, you can get it from http://forrest.apache.org.";>
<condition>
<not>
@@ -100,7 +99,7 @@
<fail unless="commons.resolver.available" message="Please make the Apache
XML Commons Resolver library available in the classpath, e.g. by copying the
xml-commons-resolver jar file from the 'tools/ant/lib' subdirectory of your
Forrest installation (${env.FORREST_HOME}/tools/ant/lib) into the lib
subdirectory of your Ant installation (${env.ANT_HOME}/lib)."/>
<delete dir="${build.doc.dir}"
- failonerror="false"/>
+ failonerror="false"/>
<mkdir dir="${build.doc.dir}"/>
<!-- Copy all forrest src stuff to a temporary directoy -->
@@ -115,10 +114,16 @@
<replace file="${build.doc.dir}/src/documentation/content/xdocs/to-do.xml"
token="@@content@@" value="${todo.content}"/>
<replace
file="${build.doc.dir}/src/documentation/content/xdocs/release-notes.xml"
token="@@content@@" value="${release-notes.content}"/>
- <!-- Copy generated javadoc into the forrest structure in the temporary
directoy -->
+ <!-- Copy generated javadoc into the forrest structure in the temporary
directory -->
+ <antcall target="javadoc"/>
<copy todir="${forrest.javadoc.destdir}">
<fileset dir="${build.javadoc.dir}"/>
</copy>
+ <!-- Copy generated schema doc into the forrest structure in the temporary
directory -->
+ <antcall target="schemadoc"/>
+ <copy todir="${forrest.schemadoc.destdir}">
+ <fileset dir="${build.schemadoc.dir}"/>
+ </copy>
<ant antfile="${env.FORREST_HOME}/main/forrest.build.xml"
dir="${build.doc.dir}"
@@ -133,6 +138,19 @@
</copy>
</target>
+ <target name="-docbook">
+ <mkdir dir="${build.doc.dir}"/>
+ <copy todir="${build.doc.dir}">
+ <fileset dir="../velocity-docbook/"/>
+ </copy>
+ <mkdir dir="${build.doc.dir}/src/docbook/ddlutils"/>
+ <copy file="${src.doc.dir}/manual.xml"
todir="${build.doc.dir}/src/docbook/ddlutils"/>
+ <ant antfile="build-docbook.xml" target="all" inheritall="false"
dir="${build.doc.dir}">
+ <property name="docbook.dir" value="ddlutils"/>
+ <property name="docbook.file" value="manual"/>
+ </ant>
+ </target>
+
<!-- ================================================================== -->
<!-- Build the API JavaDocs -->
<!-- ================================================================== -->
@@ -156,6 +174,42 @@
<link href="http://jakarta.apache.org/commons/digester/apidocs/"/>
<link href="http://jakarta.apache.org/commons/betwixt/apidocs/"/>
</javadoc>
+ </target>
+
+ <!-- ================================================================== -->
+ <!-- Builds the documentation for the database XML schema format -->
+ <!-- ================================================================== -->
+ <target name="schemadoc"
+ description="Builds the documentation for the database XML schema
format">
+ <available classname="DTDDoc.DTDDocTask"
+ classpathref="compilation-classpath"
+ property="dtddoc.available"/>
+ <fail unless="dtddoc.available" message="For building the XML Schema
documentaion, you'll need DTDDoc which can be downloaded from
http://sourceforge.net/projects/dtddoc. Please make the DTDDoc and dtdparser
jars available in the classpath."/>
+ <taskdef name="dtddoc"
+ classname="DTDDoc.DTDDocTask"
+ classpathref="compilation-classpath"/>
+
+ <mkdir dir="${build.schemadoc.dir}"/>
+ <dtddoc destdir="${build.schemadoc.dir}" sourcedir="${src.java.dir}"
includes="*.dtd"/>
+ </target>
+
+ <!-- ================================================================== -->
+ <!-- Checks the docs for broken links -->
+ <!-- ================================================================== -->
+ <target name="check-doc"
+ description="Checks the doc for broken links using linklint">
+ <echo>Running linklint on ${build.doc.dir}. The output can be found in
linklint.log.</echo>
+ <exec executable="linklint">
+ <arg line="-quiet"/>
+ <arg line="-net"/>
+ <arg line="-error"/>
+ <arg line="-warn"/>
+ <arg line="-out"/>
+ <arg line="linklint.org"/>
+ <arg line="-root"/>
+ <arg line="${build.doc.dir}"/>
+ <arg line="/@"/>
+ </exec>
</target>
<!-- ================================================================== -->
Propchange: db/ddlutils/trunk/lib/build-only/
------------------------------------------------------------------------------
--- svn:ignore (original)
+++ svn:ignore Sun Nov 5 19:03:11 2006
@@ -1,2 +1,3 @@
-
checkstyle*.jar
+DTDDoc.jar
+dtdparser*.jar
Modified:
db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/api-usage.xml
URL:
http://svn.apache.org/viewvc/db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/api-usage.xml?view=diff&rev=471621&r1=471620&r2=471621
==============================================================================
--- db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/api-usage.xml
(original)
+++ db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/api-usage.xml Sun
Nov 5 19:03:11 2006
@@ -127,7 +127,7 @@
if (alterDb)
{
- platform.alterTables(targetModel, true, alterDb, false);
+ platform.alterTables(targetModel, false);
}
else
{
@@ -187,31 +187,101 @@
to stdout:
</p>
<source><![CDATA[
-import java.util.ArrayList;
-import java.util.Iterator;
-import javax.sql.DataSource;
-import org.apache.commons.beanutils.DynaBean;
-import org.apache.ddlutils.Platform;
-import org.apache.ddlutils.PlatformFactory;
-import org.apache.ddlutils.model.Database;
+import java.util.ArrayList;
+import java.util.Iterator;
+import javax.sql.DataSource;
+import org.apache.commons.beanutils.DynaBean;
+import org.apache.ddlutils.Platform;
+import org.apache.ddlutils.PlatformFactory;
+import org.apache.ddlutils.model.Database;
+import org.apache.ddlutils.model.Table;
...
-public void dumpBooks(DataSource dataSource,
- Database database)
-{
- Platform platform = PlatformFactory.createNewPlatformInstance(dataSource);
- ArrayList params = new ArrayList();
-
- params.add("Some title");
-
- for (Iterator it = platform.query(database, "select * from book where
title = ?", params); it.hasNext();)
- {
- DynaBean book = (DynaBean)it.next();
-
- System.out.println(book.get("title"));
- }
+public void dumpBooks(DataSource dataSource,
+ Database database)
+{
+ Platform platform = PlatformFactory.createNewPlatformInstance(dataSource);
+ ArrayList params = new ArrayList();
+
+ params.add("Some title");
+
+ Iterator it = platform.query(database,
+ "select * from book where title = ?",
+ params,
+ new Table[] { database.findTable("book") });
+
+ while (it.hasNext())
+ {
+ DynaBean book = (DynaBean)it.next();
+
+ System.out.println(book.get("title"));
+ }
}]]></source>
+ <p>
+ There are two things to note in this sample code:
+ </p>
+ <p>
+ First, we specified so-called query hints in the call to the
<code>query</code>. Query hints
+ are an array of tables whose columns are used by the query statement.
The reason why they
+ should be used is that not all databases provide sufficient
information in the JDBC result set
+ object to determine the table to which a column belongs to. Since this
info is need by
+ DdlUtils to properly extract the value and convert it to the
corresponding Java type, it is
+ safer to specify these hints. What DdlUtils does in this case, is to
search for a column
+ of that name within the specified tables and use the mapping for this
column. This of course
+ can fail if you use aliases in the query statement (and the JDBC
driver handles them in
+ a strange way), or if more than one table has a column of this name.
But in most cases you'll
+ get the expected results.
+ </p>
+ <p>
+ The other thing to note is that DdlUtils does not parse the query
statement. This means that
+ if you use delimited identifier mode (i.e. identifiers can contain
whitespaces, non-alphanumeric
+ characters etc., but they also need to be enclosed in double quotes),
then you'll have to
+ specify the query statement accordingly - DdlUtils won't do that for
you. If you'd like to be
+ on the safe side, then you could write the above statement like this:
+ </p>
+ <source><![CDATA[
+import java.util.ArrayList;
+import java.util.Iterator;
+import javax.sql.DataSource;
+import org.apache.commons.beanutils.DynaBean;
+import org.apache.ddlutils.Platform;
+import org.apache.ddlutils.PlatformFactory;
+import org.apache.ddlutils.model.Database;
+import org.apache.ddlutils.model.Table;
+
+...
+
+public void dumpBooks(DataSource dataSource,
+ Database database)
+{
+ Platform platform = PlatformFactory.createNewPlatformInstance(dataSource);
+ ArrayList params = new ArrayList();
+ String sql;
+
+ params.add("Some title");
+
+ if (platform.isDelimitedIdentifierModeOn())
+ {
+ sql = "select * from \"book\" where \"title\" = ?";
+ }
+ else
+ {
+ sql = "select * from book where title = ?";
+ }
+
+ Iterator it = platform.query(database,
+ sql,
+ params,
+ new Table[] { database.findTable("book") });
+
+ while (it.hasNext())
+ {
+ DynaBean book = (DynaBean)it.next();
+
+ System.out.println(book.get("title"));
+ }
+}]]></source>
</section>
</body>
</document>
Modified: db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/schema.xml
URL:
http://svn.apache.org/viewvc/db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/schema.xml?view=diff&rev=471621&r1=471620&r2=471621
==============================================================================
--- db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/schema.xml
(original)
+++ db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/schema.xml Sun
Nov 5 19:03:11 2006
@@ -22,7 +22,7 @@
<body>
<section>
<title>The schema used by DdlUtils</title>
- <p>The <a href="ext:torque/dtd">DTD</a>.</p>
+ <p>Documenation of the </p>
<note>Coming soon</note>
</section>
</body>
Modified: db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/site.xml
URL:
http://svn.apache.org/viewvc/db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/site.xml?view=diff&rev=471621&r1=471620&r2=471621
==============================================================================
--- db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/site.xml
(original)
+++ db/ddlutils/trunk/src/doc/src/documentation/content/xdocs/site.xml Sun Nov
5 19:03:11 2006
@@ -48,7 +48,7 @@
<documentation label="Documentation">
<index label="Summary" href="documentation.html"/>
<database-support label="Supported databases" href="database-support.html"
description="List of the supported databases"/>
- <schema label="The schema format" href="schema.html" description="The
schema format"/>
+ <schema label="The XML schema format" href="ext:ddlutils/schemadoc"
description="The schema format"/>
<ant-tasks label="The Ant tasks" href="ant-tasks.html" description="How to
use the Ant tasks"/>
<api-usage label="Using the API" href="api-usage.html" description="How to
use DdlUtils in your code"/>
<javadoc label="Javadoc" href="ext:ddlutils/javadoc" description="The API
documentation"/>
@@ -62,10 +62,11 @@
<external-refs>
<ddlutils>
<jira
href="http://issues.apache.org/jira/secure/BrowseProject.jspa?id=10731"/>
- <javadoc href="api/index.html">
- <model href="?org/apache/ddlutils/model/package-summary.html"/>
+ <javadoc href="api/">
+ <model
href="index.html?org/apache/ddlutils/model/package-summary.html"/>
<converter
href="org/apache/ddlutils/io/converters/SqlTypeConverter.html"/>
</javadoc>
+ <schemadoc href="schema/database.dtd.html"/>
<svn-view href="http://svn.apache.org/viewcvs.cgi/db/ddlutils/trunk/"/>
<user-list>
<subscribe href="mailto:[EMAIL PROTECTED]"/>
@@ -102,13 +103,13 @@
<derby href="http://db.apache.org/derby/";>
<manual href="manuals/index.html"/>
</derby>
- <eclipse href="http://www.eclipse.org"/>
- <firebird href="http://firebird.sourceforge.net/"/>
- <hsqldb href="http://hsqldb.sourceforge.net/";>
- <sql-syntax href="doc/guide/ch08.html"/>
+ <eclipse href="http://www.eclipse.org/"/>
+ <firebird href="http://www.firebirdsql.org/"/>
+ <hsqldb href="http://www.hsqldb.org/";>
+ <sql-syntax href="doc/guide/ch09.html"/>
</hsqldb>
- <idea href="http://www.jetbrains.com/idea"/>
- <interbase href="http://www.borland.com/interbase/"/>
+ <idea href="http://www.jetbrains.com/idea/"/>
+ <interbase href="http://www.borland.com/us/products/interbase/"/>
<jakarta href="http://jakarta.apache.org/";>
<commons href="commons/">
<dbcp href="dbcp/">
@@ -136,15 +137,15 @@
<mysql href="http://www.mysql.com/products/mysql/";>
<manual href="http://dev.mysql.com/doc/mysql/en/index.html"/>
</mysql>
- <netbeans href="http://www.netbeans.org";>
+ <netbeans href="http://www.netbeans.org/";>
<subversion-profile
href="http://vcsgeneric.netbeans.org/profiles/index.html"/>
</netbeans>
- <ojb href="http://db.apache.org/ojb"/>
+ <ojb href="http://db.apache.org/ojb/"/>
<oracle href="http://www.oracle.com/";>
<otn href="technology/index.html"/>
</oracle>
<postgresql href="http://www.postgresql.org/";>
- <manual href="docs/7.2/interactive/index.html"/>
+ <manual href="docs/7.4/interactive/index.html"/>
</postgresql>
<sapdb href="http://www.sapdb.org/";>
<manual href="pdf/reference_72_73eng.pdf"/>
@@ -159,9 +160,9 @@
<manual href="http://sybooks.sybase.com/as.html"/>
</sybase>
<tigris>
- <subclipse href="http://subclipse.tigris.org"/>
- <svn href="http://subversion.tigris.org"/>
- <svn-up href="http://svnup.tigris.org"/>
+ <subclipse href="http://subclipse.tigris.org/"/>
+ <svn href="http://subversion.tigris.org/"/>
+ <svn-up href="http://svnup.tigris.org/"/>
<tortoisesvn href="http://tortoisesvn.tigris.org"/>
</tigris>
<torque href="http://db.apache.org/torque/";>
Modified: db/ddlutils/trunk/src/doc/src/documentation/skinconf.xml
URL:
http://svn.apache.org/viewvc/db/ddlutils/trunk/src/doc/src/documentation/skinconf.xml?view=diff&rev=471621&r1=471620&r2=471621
==============================================================================
--- db/ddlutils/trunk/src/doc/src/documentation/skinconf.xml (original)
+++ db/ddlutils/trunk/src/doc/src/documentation/skinconf.xml Sun Nov 5
19:03:11 2006
@@ -463,7 +463,7 @@
<credits>
<credit box-location="alt">
<name>Ant</name>
- <url>http://jakarta.apache.org/ant/</url>
+ <url>http://ant.apache.org/</url>
<image>images/ant.gif</image>
<width>80</width>
<height>30</height>
Modified: db/ddlutils/trunk/src/java/database.dtd
URL:
http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/database.dtd?view=diff&rev=471621&r1=471620&r2=471621
==============================================================================
Binary files - no diff available.
Modified:
db/ddlutils/trunk/src/java/org/apache/ddlutils/dynabean/SqlDynaException.java
URL:
http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/dynabean/SqlDynaException.java?view=diff&rev=471621&r1=471620&r2=471621
==============================================================================
---
db/ddlutils/trunk/src/java/org/apache/ddlutils/dynabean/SqlDynaException.java
(original)
+++
db/ddlutils/trunk/src/java/org/apache/ddlutils/dynabean/SqlDynaException.java
Sun Nov 5 19:03:11 2006
@@ -1,7 +1,5 @@
package org.apache.ddlutils.dynabean;
-import org.apache.ddlutils.DdlUtilsException;
-
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
@@ -20,6 +18,8 @@
* specific language governing permissions and limitations
* under the License.
*/
+
+import org.apache.ddlutils.DdlUtilsException;
/**
* This exception is thrown when something dealing with sql dyna beans or
classes failed.
Modified: db/ddlutils/trunk/src/java/org/apache/ddlutils/dynabean/package.html
URL:
http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/dynabean/package.html?view=diff&rev=471621&r1=471620&r2=471621
==============================================================================
--- db/ddlutils/trunk/src/java/org/apache/ddlutils/dynabean/package.html
(original)
+++ db/ddlutils/trunk/src/java/org/apache/ddlutils/dynabean/package.html Sun
Nov 5 19:03:11 2006
@@ -23,7 +23,7 @@
</head>
<body bgcolor="white">
<p>
- Provides the special DdlUtils implementations of [EMAIL PROTECTED]
org.apache.commons.beanutils.DynaBeanClass}
+ Provides the special DdlUtils implementations of [EMAIL PROTECTED]
org.apache.commons.beanutils.DynaClass}
and [EMAIL PROTECTED] org.apache.commons.beanutils.DynaBean} that
directly map to tables in the database
model. These are used by DdlUtils when reading data from or writing
data to the database.
If you want to create these beans manually, use the
Modified:
db/ddlutils/trunk/src/java/org/apache/ddlutils/platform/oracle/package.html
URL:
http://svn.apache.org/viewvc/db/ddlutils/trunk/src/java/org/apache/ddlutils/platform/oracle/package.html?view=diff&rev=471621&r1=471620&r2=471621
==============================================================================
--- db/ddlutils/trunk/src/java/org/apache/ddlutils/platform/oracle/package.html
(original)
+++ db/ddlutils/trunk/src/java/org/apache/ddlutils/platform/oracle/package.html
Sun Nov 5 19:03:11 2006
@@ -24,7 +24,7 @@
<body bgcolor="white">
<p>
This package contains the platform implementation for the
- <a href="http://www.oracle.com/database/index.html";>Oracle</a> database.
+ <a href="http://www.oracle.com/database/";>Oracle</a> database.
</p>
</body>
</html>
