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:ddlutils-user-subscribe@db.apache.org"/>
@@ -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 {@link org.apache.commons.beanutils.DynaBeanClass}
+  	Provides the special DdlUtils implementations of {@link org.apache.commons.beanutils.DynaClass}
   	and {@link 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>