db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r371077 [1/2] - in /db/torque/runtime/trunk: ./ xdocs/ xdocs/images/ xdocs/reference/
Date Sat, 21 Jan 2006 15:46:51 GMT
Author: tfischer
Date: Sat Jan 21 07:46:38 2006
New Revision: 371077

URL: http://svn.apache.org/viewcvs?rev=371077&view=rev
Log:
- changed inclusion of project reports from automatic to manual
- corrected some urls
- rewritten runtime's index.html. Information about which database is supported was moved to an extra page in docs-all-components.
- removed the jar guide. It is not applicable any more as the generator was seperated from the runtime in torque 3.1
- the information in peers-howto was moved to several other documents in the reference (read-to-db, write-to-db, extend-classes)
- todo.xml was removed. Todo information is discussed in the wiki.
- users-guide was removed. It is not up-to-date anymore and mostly repeats information in the tutorial. The ant part will be rewritten and added to the generator reference.
- old logos (db-logo-blue.png, torque-logo-blue.png) are removed.
- the stuff in reference (which was scattered in the howtos before) was re-organized, checked to be up-to-date, rewritten in some parts and brought to a common format. 

Added:
    db/torque/runtime/trunk/xdocs/navigation.xml
    db/torque/runtime/trunk/xdocs/reference/extend-classes.xml
    db/torque/runtime/trunk/xdocs/reference/index.xml
    db/torque/runtime/trunk/xdocs/reference/relevant-classes.xml
    db/torque/runtime/trunk/xdocs/reference/write-to-db.xml
Removed:
    db/torque/runtime/trunk/xdocs/images/db-logo-blue.png
    db/torque/runtime/trunk/xdocs/images/torque-logo-blue.png
    db/torque/runtime/trunk/xdocs/jar-guide.xml
    db/torque/runtime/trunk/xdocs/maven-howto.xml
    db/torque/runtime/trunk/xdocs/peers-howto.xml
    db/torque/runtime/trunk/xdocs/todo.xml
    db/torque/runtime/trunk/xdocs/user-guide.xml
Modified:
    db/torque/runtime/trunk/project.properties
    db/torque/runtime/trunk/project.xml
    db/torque/runtime/trunk/xdocs/index.xml
    db/torque/runtime/trunk/xdocs/reference/beans.xml
    db/torque/runtime/trunk/xdocs/reference/initialisation-configuration.xml
    db/torque/runtime/trunk/xdocs/reference/managers-cache.xml
    db/torque/runtime/trunk/xdocs/reference/new-database-support.xml
    db/torque/runtime/trunk/xdocs/reference/read-from-db.xml

Modified: db/torque/runtime/trunk/project.properties
URL: http://svn.apache.org/viewcvs/db/torque/runtime/trunk/project.properties?rev=371077&r1=371076&r2=371077&view=diff
==============================================================================
--- db/torque/runtime/trunk/project.properties (original)
+++ db/torque/runtime/trunk/project.properties Sat Jan 21 07:46:38 2006
@@ -29,3 +29,7 @@
 torque.generator.home = ../generator
 torque.template.home = ../templates
 
+# Project documentation is included manually
+maven.xdoc.includeProjectDocumentation = no
+
+maven.linkcheck.exclude=http://svn.apache.org,..

Modified: db/torque/runtime/trunk/project.xml
URL: http://svn.apache.org/viewcvs/db/torque/runtime/trunk/project.xml?rev=371077&r1=371076&r2=371077&view=diff
==============================================================================
--- db/torque/runtime/trunk/project.xml (original)
+++ db/torque/runtime/trunk/project.xml Sat Jan 21 07:46:38 2006
@@ -29,7 +29,7 @@
   <repository>
     <connection>scm:svn:http://svn.apache.org/repos/asf/db/torque/runtime/trunk</connection>
     <developerConnection>scm:svn:https://svn.apache.org/repos/asf/db/torque/runtime/trunk</developerConnection>
-    <url>http://svn.apache.org/viewcvs/db/torque/runtime/trunk/</url>
+    <url>http://svn.apache.org/viewcvs</url>
   </repository>
 
   <dependencies>
@@ -171,7 +171,7 @@
       <groupId>xerces</groupId>
       <artifactId>xercesImpl</artifactId>
       <version>2.6.2</version>
-      <url>http://xml.apache.org/xerces2-j/</url>
+      <url>http://xerces.apache.org/xerces2-j/</url>
       <properties>
         <dist.bundle>true</dist.bundle>
       </properties>

Modified: db/torque/runtime/trunk/xdocs/index.xml
URL: http://svn.apache.org/viewcvs/db/torque/runtime/trunk/xdocs/index.xml?rev=371077&r1=371076&r2=371077&view=diff
==============================================================================
--- db/torque/runtime/trunk/xdocs/index.xml (original)
+++ db/torque/runtime/trunk/xdocs/index.xml Sat Jan 21 07:46:38 2006
@@ -18,165 +18,31 @@
 <document>
 
   <properties>
-    <title>Torque</title>
+    <title>Torque - Runtime Documentation</title>
     <author email="jvanzyl@apache.com">Jason van Zyl</author>
     <author email="mpoeschl@marmot.at">Martin Poeschl</author>
     <author email="seade@backstagetech.com.au">Scott Eade</author>
+    <author email="fischer@seitenbau.de">Thomas Fischer</author>
   </properties>
 
   <body>
 
-    <section name="What is Torque?">
+    <section name="Torque Runtime">
       <p>
-        Torque is a persistence layer. Torque includes a <a href="generator">
-        generator</a> to generate all the database
-        resources required by your application and includes a runtime
-        environment to run the generated classes.
+        The Torque runtime is the only part of Torque you need after you
+        have generated the persistence classes using the Torque Maven plugin
+        resp. the Torque generator.  It contains the classes the generated
+        classes depend on.
       </p>
+      
       <p>
-        Torque was developed as part of the
-        <a href="http://jakarta.apache.org/turbine/">Turbine Framework</a>.
-        It is now decoupled and can be used by itself. Starting with version
-        2.2 Turbine uses the decoupled Torque.
+        This section contains information about how to work with the generated
+        classes.  For information of how to generate these classes, see the
+        <a href="../maven-plugin/index.html">Maven plugin reference</a>
+        or the
+        <a href="../generator/index.html">generator reference</a>.
       </p>
-      <p>
-        Torque's runtime environment includes everything you need to use the
-        generated OM/Peer classes. It includes a jdbc connection pool.
-      </p>
-    </section>
 
-    <section name="Supported RDBMS">
-      <table>
-        <tr>
-          <th>RDBMS</th>
-          <th>Driver</th>
-          <th>Status</th>
-          <th>Tester</th>
-        </tr>
-        <tr>
-          <td>Axion</td>
-          <td>org.axiondb.jdbc.AxionDriver</td>
-          <td>Alpha</td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Cloudscape</td>
-          <td>COM.cloudscape.core.JDBCDriver</td>
-          <td></td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>DB2</td>
-          <td>COM.ibm.db2.jdbc.{app|net}.DB2Driver</td>
-          <td></td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>DB2/AS400</td>
-          <td>com.ibm.as400.access.AS400JDBCDriver</td>
-          <td>Possible case-insensitivity issues</td>
-          <td><a href="mailto:Sweaver@rippe.com">Scott Weaver</a></td>
-        </tr>
-        <tr>
-          <td>Derby</td>
-          <td>org.apache.derby.jdbc.EmbeddedDriver</td>
-          <td>Only the embedded driver works.</td>
-          <td><a href="mailto:fischer@seitenbau.de">Thomas Fischer</a></td>
-        </tr>
-        <tr>
-          <td>Firebird</td>
-          <td>org.firebirdsql.jdbc.FBDriver</td>
-          <td>idMethod=&quot;native&quot; does not work</td>
-          <td><a href="mailto:fischer@seitenbau.de">Thomas Fischer</a></td>
-        </tr>
-        <tr>
-          <td>Hypersonic</td>
-          <td>org.hsql.jdbcDriver</td>
-          <td></td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Informix</td>
-          <td>com.informix.jdbc.IfxDriver</td>
-          <td></td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>InstantDB</td>
-          <td>org.enhydra.instantdb.jdbc.idbDriver</td>
-          <td></td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>Interbase</td>
-          <td>interbase.interclient.Driver</td>
-          <td></td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>MS Access</td>
-          <td>sun.jdbc.odbc.JdbcOdbcDriver</td>
-          <td></td>
-          <td></td>
-        </tr>
-        <tr>
-          <td><a href="mssql-howto.html">MS SQL</a></td>
-          <td>com.microsoft.jdbc.sqlserver.SQLServerDriver</td>
-          <td></td>
-          <td></td>
-        </tr>
-        <tr>
-          <td>MySQL</td>
-          <td>org.gjt.mm.mysql.Driver</td>
-          <td>No known problems</td>
-          <td><a href="mailto:seade@backstagetech.com.au">Scott Eade</a></td>
-        </tr>
-        <tr>
-          <td><a href="oracle-howto.html">Oracle</a></td>
-          <td>oracle.jdbc.driver.OracleDriver</td>
-          <td>Issues with LOBs</td>
-          <td></td>
-        </tr>
-        <tr>
-          <td><a href="postgres-howto.html">Postgres</a></td>
-          <td>org.postgresql.Driver</td>
-          <td>No known problems</td>
-          <td><a href="mailto:seade@backstagetech.com.au">Scott Eade</a></td>
-        </tr>
-        <tr>
-          <td>SapDB</td>
-          <td>com.sap.dbtech.jdbc.DriverSapDB</td>
-          <td></td>
-          <td></td>
-        </tr>
-        <tr>
-          <td><a href="sybase-howto.html">Sybase</a></td>
-          <td>com.sybase.jdbc2.jdbc.SybDriver</td>
-          <td>
-          JDBCToXMLSchema task will not generate the schema properly.
-          All other tests pass.
-          </td>
-          <td><a href="mailto:brekke@apache.org">Jeffrey D. Brekke</a></td>
-        </tr>
-        <tr>
-          <td>Weblogic</td>
-          <td>weblogic.jdbc.pool.Driver</td>
-          <td></td>
-          <td></td>
-        </tr>
-      </table>
-
-      <p>
-        If your RDBMS is not listed here, please read the document about
-        <a href="db-adapters.html">writing DB Adapters</a>
-      </p>
-      <p>
-        If there is no tester for your RDBMS and you want to help, please read
-        the <a href="developer-guide.html">developer-guide</a>, run the tests
-        and send your results (and bugfixes ;) to the
-        <a href="mailto:torque-dev@db.apache.org">torque-dev@db.apache.org</a>
-        list.
-      </p>
     </section>
 
   </body>

Added: db/torque/runtime/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/db/torque/runtime/trunk/xdocs/navigation.xml?rev=371077&view=auto
==============================================================================
--- db/torque/runtime/trunk/xdocs/navigation.xml (added)
+++ db/torque/runtime/trunk/xdocs/navigation.xml Sat Jan 21 07:46:38 2006
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ Copyright 2001-2005 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License")
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<project name="Torque" href="http://db.apache.org/torque/">
+
+  <title>Torque</title>
+
+  <body>
+
+    <menu name="Torque"> 
+      <item name="Overview"              href="../../../index.html"/>
+      <item name="News and Status"       href="../../../status.html"/>
+      <item name="Downloads"             href="../../../download.html"/>
+      <item name="Changes"               href="../../../changes-report.html"/>
+      <item name="Wiki"                  href="http://wiki.apache.org/db-torque/"/>
+      <item name="Issue tracker"         href="../../../issue-tracking.html"/>
+      <item name="Mailing lists"         href="../../../mail-lists.html"/>
+      <item name="Developer Information" href="../../../developer-info/index.html" collapse="true">
+        <item name="dummy"               href="/dummy.html" />
+      </item>
+    </menu>
+
+    <menu name="Documentation">
+      <item name="Documentation"         href="../../../documentation/index.html">
+        <item name="Torque 3.2 Runtime"  href="/index.html">
+          <item name="Reference"         href="/reference/index.html" collapse="true">
+            <item name="Initialisation"  href="/reference/initialisation-configuration.html"/>
+            <item name="Reading from the DB" href="/reference/read-from-db.html"/>
+ยด           <item name="Writing to the DB" href="/reference/write-to-db.html"/>
+            <item name="Extending classes" href="/reference/extend-classes.html"/>
+            <item name="Managers and Cache" href="/reference/managers-cache.html"/>
+            <item name="Beans"           href="/reference/beans.html"/>
+            <item name="Relevant classes" href="/reference/relevant-classes.html"/>
+            <item name="Supporting a new DB" href="/reference/new-database-support.html"/>
+          </item>
+          <item name="Dependencies"      href="/dependencies.html"/>
+          <item name="Project Reports"   href="/maven-reports.html" collapse="true">
+            <item name="Metrics"         href="/jdepend-report.html"/>
+            <item name="Checkstyle"      href="/checkstyle-report.html"/>
+            <item name="Change Log"      href="/changelog-report.html"/>
+            <item name="File Activity"   href="/file-activity-report.html"/>
+            <item name="Developer Activity" href="/developer-activity-report.html"/>
+            <item name="JavaDocs"        href="/apidocs/index.html" target="_blank" />
+            <item name="JavaDoc Report"  href="/javadoc.html"/>
+            <item name="JavaDoc Warnings Report" href="/javadoc-warnings-report.html"/>
+            <item name="Source Xref"     href="/xref/index.html" target="_blank" />
+            <item name="Test Xref"       href="/xref-test/index.html" target="_blank" />
+            <item name="Unit Tests"      href="/junit-report.html"/>
+            <item name="Project License" href="/license.html"/>
+            <item name="Task List"       href="/task-list.html"/>
+            <item name="PMD Report"      href="/pmd-report.html"/>
+            <item name="Simian Report"   href="/simian-report.html"/>
+            <item name="JCoverage"       href="/jcoverage/index.html" target="_blank"/>
+            <item name="FindBugs Report" href="/findbugs-report.html"/>
+            <item name="Link Check Report" href="/linkcheck.html"/>
+          </item>
+        </item>
+      </item>
+    
+      <item name="Tutorial"              href="../../../tutorial/index.html"/>
+    </menu>
+
+    <menu name="Project documentation">
+      <item name="Project info"          href="../../../project-info.html" collapse="true">
+        <item name="dummy"               href="/dummy.html"/>
+      </item>
+      <item name="Project Reports"       href="../../../project-reports.html" collapse="true">
+        <item name="dummy"               href="/dummy.html"/>
+      </item>
+    </menu>
+
+  </body>
+</project>
\ No newline at end of file

Modified: db/torque/runtime/trunk/xdocs/reference/beans.xml
URL: http://svn.apache.org/viewcvs/db/torque/runtime/trunk/xdocs/reference/beans.xml?rev=371077&r1=371076&r2=371077&view=diff
==============================================================================
--- db/torque/runtime/trunk/xdocs/reference/beans.xml (original)
+++ db/torque/runtime/trunk/xdocs/reference/beans.xml Sat Jan 21 07:46:38 2006
@@ -17,103 +17,99 @@
 
 <document>
  <properties>
-  <title>Beans Howto</title>
+  <title>Torque Runtime Reference - Beans</title>
   <author email="fischer@seitenbau.de">Thomas Fischer</author>
  </properties>
 
  <body>
-
-  <section name="Creation of beans from Torque objects and vice versa">
-
-   <p>
-    Creating beans from Torque objects creates a bridge between
-    an environment which knows Torque and has access to a database,
-    and another environment which dies not know anything about Torque
-    and databases.
-   </p>
-
-   <p>
-    For example, you might have a server using Torque, and a java client
-    without database access where you want to use data supplied by
-    Torque, but do not want to include Torque in any way.
-   </p>
-
-   <p>
-    If this is the case, you can create simple beans from Torque objects
-    in the server, send them over the network to your client,
-    manipulate them there, send them back over the network,
-    create Torque objects from the beans,
-    and save the objects generated from the beans.
-   </p>
-
-   <subsection name="Enabling bean creation support in the generator">
+ 
+  <section name="Introduction">
 
     <p>
-     Bean creation is turned off by default. To enable bean creation,
-     you have to add the following line to your build.properties file
-     in the generator
+      Bean creation is turned off by default. To enable bean creation,
+      you have to generate your object model with the property 
+      <code>torque.generateBeans</code>code> set to <code>true</code>.
     </p>
-
-    <source>
-torque.generateBeans = true</source>
-
+    
     <p>
-     Then you just need to regenerate your object model to obtain an object model
-     with bean creation support enabled.
+      Creating beans from Torque objects creates a bridge between
+      an environment which knows Torque and has access to a database,
+      and another environment which does not know anything about Torque
+      and databases.
     </p>
 
-   </subsection>
-
-   <subsection name="Created beans">
     <p>
-     If bean creation is turned on, the beans are automatically created by torque
-     in the bean subpackage of your target package. E.g. in the bookstore example
-     in the tutorial, the classes are generated in the com.kazmier.om package,
-     so the beans will generated in the package com.kazmier.om.bean.
-     Each bean has getters and setters for all the properties defined
-     in the schema.xml.
+      For example, you might have a server using Torque, and a java client
+      without database access where you want to use data supplied by
+      Torque, but do not want to include Torque in any way.
     </p>
 
     <p>
-     Also, getters and setters for two boolean values, namely
-     isNew(), setNew(), isModified() and setModified() are generated, which keep
-     track of which changes have already made it into the
-     database. You should not normally need to use these.
+      If this is the case, you can create simple beans from Torque objects
+      in the server, send them over the network to your client,
+      manipulate them there, send them back over the network,
+      create Torque objects from the beans,
+      and save the objects generated from the beans.
     </p>
 
-   </subsection>
-
-   <subsection name="Additional methods in the Torque objects">
-
-     <p>
-      If bean creation is enabled, every Torque object gets some
-      additional methods. E.g, the author class from the bookstore example
-      in the tutorial gets the additional methods
-    </p>
+  </section>
 
-    <source>
-public AuthorBean createBean();
+  <section name="Creation of beans from Torque objects and vice versa">
 
-public static Author createAuthor(AuthorBean bean);</source>
+    <subsection name="Created bean classes">
 
-    <p>
-     These methods are used to create a bookBean from a book or vice versa.
-    </p>
+      <p>
+        If bean creation is turned on, the beans are automatically created
+        by torque in the bean subpackage of your target package. 
+        E.g. in the bookstore example in the tutorial, the classes
+        are generated in the com.kazmier.om package, so the beans 
+        will be generated in the package com.kazmier.om.bean.
+        Each bean has getters and setters for all the properties defined
+        in the schema.xml.
+      </p>
+
+      <p>
+        Also, getters and setters for two boolean values, namely
+        isNew(), setNew(), isModified() and setModified() are generated, 
+        which keep track of which changes have already made it into the
+        database. You should not normally need to use these.
+      </p>
+
+    </subsection>
+
+    <subsection name="Additional methods in the Torque objects">
+
+      <p>
+        If bean creation is enabled, every Torque object gets some
+        additional methods. E.g, the author class from the bookstore example
+        in the tutorial gets the additional methods
+      </p>
 
-   </subsection>
+<source>
+public AuthorBean createBean();
 
-   <subsection name="Beans and database state">
+public static Author createAuthor(AuthorBean bean);
+</source>
 
-    <p>
-     If a bean is created from an object, the beans gets knowledge about
-     whether the object it was created from already exists in the database,
-     or whether it was changed after redaing it from the database
-     (that is what the isNew() and isModified() methods are for).
-     So assuming we have at least one author stored in the database,
-     the following code works as expected
-    </p>
+      <p>
+        These methods are used to create an AuthorBean from an Author 
+        or vice versa.
+      </p>
+
+    </subsection>
+
+    <subsection name="Beans and database state">
+
+      <p>
+        If a bean is created from an object, the beans gets knowledge about
+        whether the object it was created from already exists in the database,
+        or whether it was changed after redaing it from the database
+        (that is what the isNew() and isModified() methods are for).
+        So assuming we have at least one author stored in the database,
+        the following code works as expected
+      </p>
 
-    <source>
+<source>
 List authors = AuthorPeer.doSelect(new Criteria());
 Author author = (Author) authors.get(0);
 
@@ -124,86 +120,92 @@
 // e.g. send the authorBean back over the network
 
 Author authorFromBean = Author.createAuthor(authorBean);
-authorFromBean.save();</source>
-
-    <p>
-     This reads an author from the database,
-     creates a bean from the author,
-     manipulates the bean,
-     and saves the manipulated data back into the database.
-    </p>
+authorFromBean.save();
+</source>
 
-   </subsection>
+      <p>
+        This reads an author from the database,
+        creates a bean from the author,
+        manipulates the bean,
+        and saves the manipulated data back into the database.
+      </p>
+
+    </subsection>
+
+    <subsection name="Object relations">
+
+      <p>
+        The bean creation process preserves object relations.
+        Consider again the bookstore example from the tutorial:
+        Each book has an author, and an author can have serveral books.
+        So if you have created an author-book relation, e.g. by
+      </p>
 
-   <subsection name="Object relations">
-
-    <p>
-     The bean creation process preserves object relations.
-     Consider again the bookstore example from the tutorial:
-     Each book has an author, and an author can have serveral books.
-     So if you have created an author-book relation, e.g. by
-    </p>
-
-    <source>
+<source>
 Author author = new Author();
 // fill author data here
 Book book = new Book();
 // fill book data here();
 author.addBook(book);
 
-AuthorBean authorBean = author.getBean();</source>
-
-    <p>
-     then the related bookBean is automatically created,
-     and can be retrieved by
-    </p>
-
-    <source>
-BookBean bookBean = (BookBean) authorBean.getBookBeans().get(0);</source>
+AuthorBean authorBean = author.getBean();
+</source>
 
-    <p>
-     This is also true in the reverse direction. If you create an
-     author from this authorBean, the corresponding book can also
-     be retrieved:
-    </p>
+      <p>
+        then the related bookBean is automatically created,
+        and can be retrieved by
+      </p>
+
+<source>
+BookBean bookBean = (BookBean) authorBean.getBookBeans().get(0);
+</source>
+
+      <p>
+        This is also true in the reverse direction. If you create an
+        author from this authorBean, the corresponding book can also
+        be retrieved:
+      </p>
 
-    <source>
+<source>
 Author authorFromBean = Author.createAuthor(authorBean);
-Book bookFromBean = (Book) author.getBooks().get(0);</source>
+Book bookFromBean = (Book) author.getBooks().get(0);
+</source>
 
-    <p>
-     Note that only newly created or cached related objects are cosnidered
-     in bean creation.
-     To elaborate that, consider the case where one author which is related
-     to several books is stored in the database.
-    </p>
-
-    <p>
-     The following code will NOT transfer the related books into the bean:
-    </p>
+      <p>
+        Note that only newly created or cached related objects are considered
+        in bean creation.
+        To elaborate that, consider the case where one author which is related
+        to several books is stored in the database.
+      </p>
+
+      <p>
+        The following code will NOT transfer the related books into the bean:
+      </p>
 
-    <source>
+<source>
 List authorList = AuthorPeer.doSelect(new Criteria());
 Author author = (Author) authorList.get(0);
-AuthorBean authorBean = author.getBean()</source>
+AuthorBean authorBean = author.getBean();
+</source>
 
-    <p>
-     This is because the related books are never read from the database,
-     and thus are not included in bean conversion. To include the
-     related books into the author bean, you have to assure that the
-     related books are read into memory. This can be done as follows:
-    </p>
+      <p>
+        This is because the related books are never read from the database,
+        and thus are not included in bean conversion. To include the
+        related books into the author bean, you have to assure that the
+        related books are read into memory. This can be done as follows:
+      </p>
 
-    <source>
+<source>
 List authorList = AuthorPeer.doSelect(new Criteria());
 Author author = (Author) authorList.get(0);
 
 // the following reads all books related to the author into memory
 author.getBooks();
 
-AuthorBean authorBean = author.getBean();</source>
+AuthorBean authorBean = author.getBean();
+</source>
 
-   </subsection>
+    </subsection>
 
   </section>
 

Added: db/torque/runtime/trunk/xdocs/reference/extend-classes.xml
URL: http://svn.apache.org/viewcvs/db/torque/runtime/trunk/xdocs/reference/extend-classes.xml?rev=371077&view=auto
==============================================================================
--- db/torque/runtime/trunk/xdocs/reference/extend-classes.xml (added)
+++ db/torque/runtime/trunk/xdocs/reference/extend-classes.xml Sat Jan 21 07:46:38 2006
@@ -0,0 +1,77 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2001-2005 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License")
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<document>
+
+ <properties>
+    <title>Torque Runtime Reference - Extending the Base Classes</title>
+    <author email="fischer@seitenbau.de">Thomas Fischer</author>
+    <author email="leon@opticode.co.za">Leon Messerschmidt</author>
+    <author email="jvanzyl@periapt.com">Jason van Zyl</author>
+    <author email="seade@backstagetech.com.au">Scott Eade</author>
+ </properties>
+ 
+ <body>
+  <section name="Extending the Base Classes">
+    <p>
+      Much of the power of Torque stems from the fact that you can easily add to
+      and change the behaviour of the generated Peer and Data Object classes 
+      by adding or overriding methods. To keep your changes apart from the 
+      autogenerated code, Torque provides two Peer classes and two
+      Data Object classes per table:  The Base&lt;table-name&gt;Peer and 
+      Base&lt;table-name&gt; classes are overwritten each time you regenerate
+      the classes from the schema and contain all functionality provided by 
+      Torque.  
+      The &lt;table-name&gt;Peer and &lt;table-name&gt; classes inherit from their 
+      respective Base Classes, but are empty initially.  They are not overwritten
+      if you regenerate the classes from the schema.  All code which you add 
+      to the data model should go into the &lt;table-name&gt;Peer and 
+      &lt;table-name&gt; classes.
+    </p>
+  </section>
+  
+  
+  <section name="Adding Methods to Peers">
+ 
+    <p>
+      Adding methods to Peers will be one of the most common things you will do
+      while using Torque. 
+      For example, if you want to retrieve objects from the database without
+      creating a Criteria objects, you would typically add a corresponding 
+      method to the Peer class.
+    </p>
+  
+    <p>
+      As an example, consider the bookstore example from the Tutorial. 
+      If you often retrieve Books by their ISBN number, you would add the 
+      following method to the BookPeer class:
+    </p>
+ 
+<source><![CDATA[
+public List doSelectByISBN(String isbn)
+{
+    Criteria crit = new Criteria();
+    crit.add(BookPeer.ISBN, isbn);
+    List books = BookPeer.doSelect(crit);
+    return books;
+}
+]]></source>
+    
+  </section>
+  
+ </body>
+</document>
\ No newline at end of file

Added: db/torque/runtime/trunk/xdocs/reference/index.xml
URL: http://svn.apache.org/viewcvs/db/torque/runtime/trunk/xdocs/reference/index.xml?rev=371077&view=auto
==============================================================================
--- db/torque/runtime/trunk/xdocs/reference/index.xml (added)
+++ db/torque/runtime/trunk/xdocs/reference/index.xml Sat Jan 21 07:46:38 2006
@@ -0,0 +1,52 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2001-2005 The Apache Software Foundation.
+
+ Licensed under the Apache License, Version 2.0 (the "License")
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<document>
+
+ <properties>
+  <title>Torque Runtime Reference</title>
+  <author email="fischer@seitenbau.de">Thomas Fischer</author>
+ </properties>
+
+ <body>
+ 
+  <section name="Contents">
+    
+    <p>
+     <br/>
+     <a href="initialisation-configuration.html">Initialisation and Configuration</a>
+     <br/><br/>
+     <a href="read-from-db.html">Reading from the database</a>
+     <br/><br/>
+     <a href="write-to-db.html">Writing to the database</a>
+     <br/><br/>
+     <a href="extend-classes.html">Extending the base classes</a>
+     <br/><br/>
+     <a href="managers-cache.html">Managers and Caching</a>
+     <br/><br/>    
+     <a href="beans.html">Beans</a>
+     <br/><br/>
+     <a href="relevant-classes.html">Relevant classes</a>
+     <br/><br/>
+     <a href="new-database-support.html">Supporting a new Database</a>
+     <br/><br/>
+    </p>
+ 
+  </section>
+
+ </body>
+</document>

Modified: db/torque/runtime/trunk/xdocs/reference/initialisation-configuration.xml
URL: http://svn.apache.org/viewcvs/db/torque/runtime/trunk/xdocs/reference/initialisation-configuration.xml?rev=371077&r1=371076&r2=371077&view=diff
==============================================================================
--- db/torque/runtime/trunk/xdocs/reference/initialisation-configuration.xml (original)
+++ db/torque/runtime/trunk/xdocs/reference/initialisation-configuration.xml Sat Jan 21 07:46:38 2006
@@ -18,136 +18,168 @@
 <document>
 
  <properties>
-  <title>Pool Configuration</title>
+  <title>Torque Runtime Reference - Initialisation and Configuration</title>
   <author email="jmcnally@apache.org">John McNally</author>
   <author email="mpoeschl@marmot.at">Martin Poeschl</author>
   <author email="seade@backstagetech.com.au">Scott Eade</author>
+  <author email="fischer@seitenbau.de">Thomas Fischer</author>
  </properties>
 
-<body>
-
-<section name="Introduction">
-
-<p>
-Torque can use any connection pool implementing the <code>DataSource</code>.
-Torque expects a factory that can return a <code>DataSource</code> and can
-be configured using torque's configuration file.
-</p>
-
-<p>
-Torque provides factories to use the commons-dbcp as well as a general
-factory that uses jndi to retrieve the <code>DataSource</code>.
-The jndi factory looks up a <code>DataSource</code> bound to jndi; it
-also provides a simple property file based way to configure and deploy most
-<code>DataSource</code>'s, though in many cases a pool may already be
-bound to jndi and torque only needs to use it.
-</p>
-
-<p>
-Before going over how to configure the factories, which will take up most the
-content of this document, you must first consider your database handles and
-adapters.
-</p>
-
-</section>
-
-<section name="Database handles">
-
-<p>
-A database handle is the name attribute that was used in the
-<code>&lt;database&gt;</code> tag of the schema.xml file.  If the name
-attribute is not used, then the handle would be 'default'.
-</p>
-
-<p>
-In all examples that follow we will use the handle 'bookstore'.  As Torque has
-the ability to use multiple databases you can tell it which one to use by
-default thus:</p>
+ <body>
+ 
+  <section name="Initialisation">
+    <p>
+      Torque is initialized by calling one of the <code>Torque.init()</code>
+      methods. Torque must be initialized before it is used, and it must not
+      be initialized more than once.
+    </p>
+
+    <p>
+      When calling one of the <code>Torque.init()</code> methods, you
+      must supply either the path to a configuration file or the configuration 
+      itself.  The configuration must contain a valid <code>DataSource</code>,
+      a default database handle, and an adapter for each 
+      <code>DataSource</code>.
+      For details, see the section <a href="#Configuration">Configuration</a>
+      below.
+    </p>
+    
+    <p>
+      Upon initialisation, also the runtime model of the database,
+      i.e. the <code>DatabaseMaps</code>, are built by autogenerated
+      <code>MapBuilder</code>classes.  This happens automatically,
+      so usually you need not bother about it.
+      The detailed procedure is the following: Each peer class registers
+      its Map builder with the Torque runtime when the Base Peer Class is loaded
+      (Usually, a peer class is loaded if one of the constants
+      for a column name is accessed, or a method is called).
+      If Torque is already initialized when the Peer class is loaded
+      (this is usually the case) the Map Builder builds the database map
+      instantly and makes it avaliable to Torque. If Torque is not yet
+      initialized, the Peer class stores the Map Builder with Torque,
+      which builds the database Map when Torque is initialized.
+    </p>
+
+  </section>
+
+  <section name="Configuration">
+  
+    <subsection name="Database handles">
+
+      <p>
+        A database handle is the name attribute that was used in the
+        <code>&lt;database&gt;</code> tag of the schema.xml file.  If the name
+        attribute is not used, then the handle would be 'default'.
+      </p>
+
+      <p>
+        In all examples that follow we will use the handle 'bookstore'.
+        As Torque has the ability to use multiple databases you can tell it 
+        which one to use by default thus:
+      </p>
 
 <source><![CDATA[
 torque.database.default=bookstore
 ]]></source>
 
-</section>
+    </subsection>
 
-<section name="Database Adapters">
+    <subsection name="Database Adapters">
 
-<p>
-Previously, Torque provided an internal map between many Drivers and a set
-of adapter classes which are used to account for differences among databases.
-This arrangement is no longer possible using <code>DataSource</code>, so
-the adapter must be given in the configuration.
-The adapter property is given as:
-</p>
+      <p>
+        Previously, Torque provided an internal map between many Drivers 
+        and a set of adapter classes which are used to account for 
+        differences among databases.
+        This arrangement is no longer possible using <code>DataSource</code>, 
+        so the adapter must be given in the configuration.
+        The adapter property is given as:
+      </p>
 
 <source><![CDATA[
 torque.database.bookstore.adapter=mysql
 ]]></source>
 
-<p>
-The valid values are:
-</p>
-
-<table align="center">
-<tr>
-<td>
-<ul>
-  <li>as400</li>
-  <li>axion</li>
-  <li>db2app</li>
-  <li>db2net</li>
-  <li>cloudscape</li>
-</ul>
-</td>
-<td>
-<ul>
-  <li>hypersonic</li>
-  <li>interbase</li>
-  <li>instantdb</li>
-  <li>mssql</li>
-  <li>mysql</li>
-</ul>
-</td>
-<td>
-<ul>
-  <li>oracle</li>
-  <li>postgresql</li>
-  <li>sapdb</li>
-  <li>sybase</li>
-  <li>weblogic.</li>
-</ul>
-</td>
-</tr>
-</table>
-
-</section>
-
-
-<section name="SharedPoolDataSourceFactory">
-
-<p>
-This factory uses the more full featured DataSource available in the
-commons-dbcp package. SharedPoolDataSourceFactory provides an easy way
-to configure this pool and it assumes you will have a jdbc Driver class
-providing the physical database connections.  Again, you must let torque know
-you are using this factory.
-</p>
+      <p>
+        The valid values are:
+      </p>
+
+      <table align="center">
+        <tr>
+          <td>
+            <ul>
+              <li>as400</li>
+              <li>axion</li>
+              <li>db2app</li>
+              <li>db2net</li>
+              <li>cloudscape</li>
+            </ul>
+          </td>
+          <td>
+            <ul>
+              <li>hypersonic</li>
+              <li>interbase</li>
+              <li>instantdb</li>
+              <li>mssql</li>
+              <li>mysql</li>
+            </ul>
+          </td>
+          <td>
+            <ul>
+              <li>oracle</li>
+              <li>postgresql</li>
+              <li>sapdb</li>
+              <li>sybase</li>
+              <li>weblogic.</li>
+            </ul>
+          </td>
+        </tr>
+      </table>
+
+    </subsection>
+
+    <subsection name="Connection pool">
+    
+      <p>
+        Torque can use any connection pool implementing the interface
+        <code>DataSource</code>.  Torque expects a factory that can return a 
+        <code>DataSource</code> and can be configured using Torque's
+        configuration file.
+      </p>
+
+      <p>
+        Torque provides factories to use the commons-dbcp pools as well as a 
+        general factory that uses jndi to retrieve the <code>DataSource</code>.
+        The jndi factory looks up a <code>DataSource</code> bound to jndi; it
+        also provides a simple property file based way to configure and deploy most
+        <code>DataSource</code>'s, though in many cases a pool may already be
+        bound to jndi and torque only needs to use it.
+      </p>
+
+    </subsection>
+    
+  </section>
+  
+  <section name="SharedPoolDataSourceFactory">
+
+    <p>
+      This factory uses the SharedDataSource available in the
+      commons-dbcp package. SharedPoolDataSourceFactory provides an easy way
+      to configure this pool and it assumes you will have a jdbc Driver class
+      providing the physical database connections.  Again, you must let 
+      Torque know you are using this factory:
+    </p>
 
 <source><![CDATA[
 torque.dsfactory.bookstore.factory= \
   org.apache.torque.dsfactory.SharedPoolDataSourceFactory
 ]]></source>
 
-<p>
-Then there are two sets of properties related to the pool configuration and
-settings for making the connection to the database.
-</p>
-
-<source><![CDATA[
-torque.dsfactory.bookstore.pool.maxActive=30
-torque.dsfactory.bookstore.pool.testOnBorrow=true
-torque.dsfactory.bookstore.pool.validationQuery=SELECT 1
-]]></source>
+    <p>
+      Then there are two sets of properties related to the pool 
+      configuration and settings for making the connection to the database.
+      The &quot;connection&quot; set contains all information to create a
+      physical connection to the database:
+    </p>
 
 <source><![CDATA[
 torque.dsfactory.bookstore.connection.driver = org.gjt.mm.mysql.Driver
@@ -156,293 +188,230 @@
 torque.dsfactory.bookstore.connection.password = 1234
 ]]></source>
 
-<p>
-Comparing this with the torque's old pool, you can see that this pool does not
-rely on expirying connections periodically to maintain their validity.  The
-pool can be setup to test each connection before returning it to the
-application, so the likelihood of the application receiving a bad connection
-is much smaller than using <code>TorqueClassicDataSource</code>.
-Torque also includes a factory for the <code>PerUserPoolDataSource</code>.
-Please see the commons-dbcp javadoc for more info.
-</p>
-
-</section>
-
-<section name="JndiDataSourceFactory">
-
-<p>
-This factory is used if the <code>DataSource</code> is to be available via
-jndi.  It is possible to use this factory to deploy a <code>DataSource</code>
-into jndi, but in many cases for using this factory the <code>DataSource</code>
-is already deployed. This factory is specified with the following property:
-</p>
+    <p>
+      The &quot;pool&quot; set contains information of how the pool should
+      handle the physical connections.  See
+      <a href="http://jakarta.apache.org/commons/dbcp/configuration.html">the dbcp reference</a>
+      for possible properties.  For example, you could use: 
+    </p>
 
 <source><![CDATA[
-torque.dsfactory.bookstore.factory=org.apache.torque.dsfactory.JndiDataSourceFactory
+torque.dsfactory.bookstore.pool.maxActive=30
+torque.dsfactory.bookstore.pool.testOnBorrow=true
+torque.dsfactory.bookstore.pool.validationQuery=SELECT 1
 ]]></source>
 
 
-<subsection name="Using pre-configured pool">
+    <p>
+      Torque also includes a factory for the 
+      <code>PerUserPoolDataSource</code>.
+      Please see the commons-dbcp javadoc for more info.
+    </p>
+
+  </section>
+  
+  <section name="JndiDataSourceFactory">
+
+    <p>
+      This factory is used if the <code>DataSource</code> is to be available 
+      via jndi.  It is possible to use this factory to deploy a
+      <code>DataSource</code> into jndi, but in many cases for using this 
+      factory the <code>DataSource</code> is already deployed. 
+      This factory is specified with the following property:
+    </p>
+
+<source><![CDATA[
+torque.dsfactory.bookstore.factory = \
+  org.apache.torque.dsfactory.JndiDataSourceFactory
+]]></source>
+
 
-<p>
-If a pool is known to already be available via jndi, only one more property
-is required.
-</p>
+    <subsection name="Using JndiDataSourceFactory with pre-configured pool">
+    
+      <p>
+        In this section, it is assumed that a <code>DataSource</code>
+        is available via jndi.  Usually, a J2EE environment can be configured
+        to bind a <code>DataSource</code> into jndi for further use.
+        For example, Tomcat can bind a <code>DataSource</code> into jndi, see
+        <a href="http://tomcat.apache.org/tomcat-5.5-doc/jndi-datasource-examples-howto.html">the Tomcat Documentation</a>
+        for details.
+      </p>
+
+      <p>
+        If a pool is known to already be available via jndi, 
+        only one more property is required for Torque:
+      </p>
 
 <source><![CDATA[
 torque.dsfactory.bookstore.jndi.path=jdbc/bookstore
 ]]></source>
 
-<p>
-This line defines the string that will be used to lookup the
-<code>DataSource</code> within the default jndi <code>InitialContext</code>.
-If everything is configured and the default <code>InitialContext</code>
-contains the <code>DataSource</code>, this is all that is
-needed.  The default <code>InitialContext</code> is chosen according to the
-rules given in the class's javadoc.  If the default has not been configured,
-you can specify any other environment properties that are needed to instantiate
-the <code>InitialContext</code> as extra properties of the form,
-torque.jndi.&lt;handle&gt;.&lt;env-var&gt;.  A couple examples are shown below:
-</p>
-
-<source><![CDATA[
-torque.dsfactory.bookstore.jndi.java.naming.factory.initial = org.apache.naming.java.javaURLContextFactory
-torque.dsfactory.bookstore.jndi.java.naming.factory.url.pkgs = org.apache.naming
-]]></source>
-
-<p>
-Such environment settings will likely not be necessary when running within
-a J2EE container, but they are useful in other cases.  One such case is when
-running torque's unit/run-time tests
-</p>
-
-<p>
-One of the advantages of jndi is that it supports changing
-the <code>DataSource</code> on the fly. On the other hand this means that the
-actual <code>DataSource</code> object must be looked up in the context with
-every database operation. To avoid this, the factory provides a simple
-caching mechanism, which stores the <code>DataSource</code> object for a
-configurable amount of time (im ms). The <b>t</b>ime between <b>t</b>wo
-<b>l</b>ookups is specified as follows:
-</p>
+      <p>
+        This line defines the string that will be used to lookup the
+        <code>DataSource</code> within the default jndi 
+        <code>InitialContext</code>.
+        If everything is configured and the default <code>InitialContext</code>
+        contains the <code>DataSource</code>, this is all that is
+        needed.  The default <code>InitialContext</code> is chosen 
+        according to the rules given in the class's javadoc.  
+        If the default has not been configured, you can specify any other 
+        environment properties that are needed to instantiate
+        the <code>InitialContext</code> as extra properties of the form,
+        torque.jndi.&lt;handle&gt;.&lt;env-var&gt;.
+        A couple of examples are shown below:
+      </p>
+
+<source><![CDATA[
+torque.dsfactory.bookstore.jndi.java.naming.factory.initial = \
+  org.apache.naming.java.javaURLContextFactory
+torque.dsfactory.bookstore.jndi.java.naming.factory.url.pkgs = \
+  org.apache.naming
+]]></source>
+
+      <p>
+        Such environment settings will most likely not be necessary when running 
+        within a J2EE container, but they are useful in other cases.
+      </p>
+
+      <p>
+        One of the advantages of jndi is that it supports changing
+        the <code>DataSource</code> on the fly.
+        On the other hand this means that the actual <code>DataSource</code>
+        object must be looked up in the context with every database operation.
+        To avoid this, the factory provides a simple caching mechanism,
+        which stores the <code>DataSource</code> object for a configurable
+        amount of time (im ms). The <b>t</b>ime between <b>t</b>wo
+        <b>l</b>ookups is specified as follows:
+      </p>
 
 <source><![CDATA[
 torque.dsfactory.bookstore.jndi.ttl=60000
 ]]></source>
 
-<p>
-This property is optional. If not specified, it defaults to 0 (no caching).
-</p>
-
-</subsection>
-
-<subsection name="Using torque to bind pool">
-
-<p>
-Generally a J2EE environment such as a servlet engine or application server is
-expected to provide a jdbc2 compatible connection pool.  If your application
-is not running within such an environment, or even if it is and torque is your
-only use of a connection pool, torque provides a simple properties file
-method of configuring a <code>DataSource</code> and deploying it via jndi.
-The one property that is necessary for all <code>DataSource</code>'s is the
-classname the <code>DataSource</code> implementation.  Beyond that the properties are implementation specific.
-<code>DataSource</code>'s contain getters/setters for configuration.  You
-can specify the values for these properties as shown below:
-</p>
-
-<source><![CDATA[
-torque.dsfactory.bookstore.datasource.classname=org.apache.torque.pool.TorqueClassicDataSource
-torque.dsfactory.bookstore.datasource.dataSourceName=jdbc/DBbookstore
-torque.dsfactory.bookstore.datasource.defaultMaxConnections=10
-]]></source>
-
-<source><![CDATA[
-torque.dsfactory.DBbookstore.datasource.factory=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
-torque.dsfactory.DBbookstore.datasource.driver = org.gjt.mm.mysql.Driver
-torque.dsfactory.DBbookstore.datasource.url = jdbc:mysql://localhost:3306/bookstore
-torque.dsfactory.DBbookstore.datasource.user = root
-torque.dsfactory.DBbookstore.datasource.password = 1234
-]]></source>
-
-<p>
-In the above example two objects are being configured.  One is a
-<code>DataSource</code> that is used by the application (torque).  The other is
-a <code>ConnectionPoolDataSource</code> that is provided as part of a jdbc2
-driver.  If the jdbc driver implementation you are using does not fully
-implement the jdbc2 specification.  commons-dbcp provides an
-adapter for older <code>Driver</code> based drivers.  Another alternative is
-provided in commons-dbcp where <code>BasicDataSource</code> provides a
-<code>DataSource</code> frontend, and has properties to directly configure
-a jdbc1 <code>Driver</code>.  But regardless of the implementation torque
-uses commons-beanutils package to call the setters on the object using
-reflection.
-</p>
-
-<p>Torque uses the jndi path properties to know where to deploy the
-configured objects.  So you would have the two following properties in
-addition to the datasource props:
-</p>
-
+      <p>
+        This property is optional. If not specified, it defaults to 0 
+        (no caching).
+      </p>
+
+    </subsection>
+
+    <subsection name="Using Torque to bind a pool to jndi">
+
+      <p>
+        Generally a J2EE environment such as a servlet engine or application
+        server is expected to provide a jdbc2 compatible connection pool.
+        If your application is not running within such an environment,
+        or even if it is and torque is your only use of a connection pool,
+        Torque provides a simple properties file method of configuring a
+        <code>DataSource</code> and deploying it via jndi.
+      </p>
+      
+      <p>
+        Too use this feature, you need to specify the jndi configuration 
+        parameters as shown above, setting the factory and the jndi path.
+        In addition to that, you need to configure
+        the <code>DataSource</code> which should be bound into jndi.
+        The one property that is necessary for all <code>DataSource</code>'s 
+        is the classname of the <code>DataSource</code> implementation.
+        Beyond that the properties are implementation specific, depending on the
+        <code>DataSource</code>'s setters for the configuration.
+        You can specify the values for the setters as properties in the
+        configuration file.  For example, dbcp's <code>BasicDataSource</code>
+        could be configured as shown below:
+      </p>
+
+<source><![CDATA[
+torque.dsfactory.bookstore.datasource.classname= \
+  org.apache.commons.dbcp.BasicDataSource
+torque.dsfactory.bookstore.datasource.driver = org.gjt.mm.mysql.Driver
+torque.dsfactory.bookstore.datasource.url = jdbc:mysql://localhost:3306/bookstore
+torque.dsfactory.bookstore.datasource.user = root
+torque.dsfactory.bookstore.datasource.password = 1234
+]]></source>
+
+      <p>
+        plus the properties for the factory and the jndi path:
+      </p>
+      
 <source><![CDATA[
+torque.dsfactory.bookstore.factory = \
+  org.apache.torque.dsfactory.JndiDataSourceFactory
 torque.dsfactory.bookstore.jndi.path=jdbc/bookstore
-torque.dsfactory.DBbookstore.jndi.path=jdbc/DBbookstore
 ]]></source>
 
-<p>
-The second handle, DBbookstore, has no relevance to torque, other than
-to uniquely identify this group of properties as belonging together.  Any
-unique handle may be used.
-</p>
-
-</subsection>
-
-<subsection name="Tomcat example of external configuration/binding">
-
-<p>
-If you have other parts of your application that need to use the same
-connection pool and torque cannot be guaranteed to be initialized in time for
-these other uses, or if you just want to follow your j2ee environment's
-standard jndi deployment pattern, torque can just make use of these externally
-deployed pools.  Here is an example using catalina of deploying the pool that
-used to come with torque, but is now part of commons-jdbc2pool.
-</p>
-
-<p>In server.xml, the following would be added to the &lt;Context&gt; for your
-webapp:
-</p>
-
-<source><![CDATA[
- <Resource name="jdbc/ScarabDB" auth="Container"
-            type="org.apache.torque.pool.TorqueClassicDataSource"/>
-  <ResourceParams name="jdbc/bookstore">
-    <parameter>
-      <name>factory</name>
-      <value>org.apache.torque.pool.TorqueClassicDataSource</value>
-    </parameter>
-    <parameter>
-      <name>dataSourceName</name><value>java:comp/env/jdbc/DBbookstore</value>
-    </parameter>
-    <parameter>
-      <name>defaultMaxConnections</name><value>30</value>
-    </parameter>
-    <parameter>
-      <name>maxExpiryTime</name><value>3600</value>
-    </parameter>
-    <parameter>
-      <name>connectionWaitTimeout</name><value>10</value>
-    </parameter>
-    <parameter>
-      <name>logInterval</name><value>0</value>
-    </parameter>
-
-  </ResourceParams>
-]]></source>
-
-<p>In web.xml.  Elements must be given in the order of the dtd described in
-the servlet specification:
-</p>
-
-<source><![CDATA[
-<resource-ref>
-  <description>
-    Resource reference to a factory for java.sql.Connection
-    instances that may be used for talking to a particular
-    database that is configured in the server.xml file.
-  </description>
-  <res-ref-name>
-    jdbc/bookstore
-  </res-ref-name>
-  <res-type>
-    org.apache.torque.pool.TorqueClassicDataSource
-  </res-type>
-  <res-auth>
-    Container
-  </res-auth>
-</resource-ref>
-]]></source>
-
-<p>
-Catalina deploys all objects configured similarly to above within the
-<strong>java:comp/env</strong> namespace so the jndi path given in
-Torque.properties would be
-</p>
-
-<source><![CDATA[
-torque.dsfactory.bookstore.jndi.path=java:comp/env/jdbc/bookstore
-]]></source>
-
-<p>
-Remember that jdbc2 pools expect a
-<code>ConnectionPoolDataSource</code>
-available via jndi under the name given in the dataSourceName, so you will
-need entries in server.xml and web.xml for this object as well.
-</p>
-
-<p>
-Catalina provides a default <code>DataSource</code> that can be used as well
-and it is configured similarly, but detailed information on that
-implementation is <a href="http://jakarta.apache.org/tomcat/tomcat-4.1-doc/jndi-resources-howto.html">here</a>.  Note that the
-"type attribute/ref-type element" value of "javax.sql.DataSource" appears to
-be reserved for catalina's default implementation, which is why the
-implementation classname is used in our configuration example.
-</p>
-
-</subsection>
-
-
-<subsection name="An example configuration from scarab">
-
-<p>
-The following example shows a complete torque configuration from
-scarab, an issue tracking application, running under catalina, but using torque
-to deploy the <code>DataSource</code>.  It is here to
-put together some of the details shown above.
-</p>
-
-<source><![CDATA[
-torque.database.scarab.adapter=mysql
-
-# Jndi location
-torque.dsfactory.scarab.jndi.path=jdbc/scarab
-torque.dsfactory.DBscarabDB.jndi.path=jdbc/DBscarabDB
-
-# Connection properties for the pooling DataSource
-# These properties will vary from one datasource to another, see the class
-# javadoc for a description of which properties can be set.
-torque.dsfactory.scarab.datasource.classname=org.apache.torque.pool.TorqueClassicDataSource
-torque.dsfactory.scarab.datasource.dataSourceName=jdbc/DBscarabDB
-torque.dsfactory.scarab.datasource.defaultMaxConnections=30
-torque.dsfactory.scarab.datasource.maxExpiryTime=3600
-torque.dsfactory.scarab.datasource.connectionWaitTimeout=10
-torque.dsfactory.scarab.datasource.logInterval=0
-
-# Connection properties for the ConnectionPoolDataSource
-torque.dsfactory.DBscarabDB.datasource.classname=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
-torque.dsfactory.DBscarabDB.datasource.driver=org.gjt.mm.mysql.Driver
-torque.dsfactory.DBscarabDB.datasource.url=jdbc:mysql://localhost:3306/scarab
-torque.dsfactory.DBscarabDB.datasource.user=xxx
-torque.dsfactory.DBscarabDB.datasource.password=yyy
-
-
-# Determines if the quantity column of the IDBroker's id_table should
-# be increased automatically if requests for ids reaches a high
-# volume.
-
-torque.idbroker.clever.quantity=false
-
-# Determines if IDBroker should prefetch IDs or not.  If set to false
-# this property has the effect of shutting off the housekeeping thread
-# that attempts to prefetch the id's.  It also sets the # of id's grabbed
-# per request to 1 regardless of the settings in the database.
-# Default: true
-
-torque.idbroker.prefetch=true
+      <p>
+        Note that in dbcp 1.2.1, the SharedPoolDataSourceFactory and 
+        PerUserPoolDataSourceFactory cannot be bound into jndi (this is a dbcp 
+        problem).  
+      </p>
+
+    </subsection>
+    
+  </section>
+
+  <section name="Examples">
+
+    <p>
+      In this section, the bits explained above are assembled to full
+      examples of configuration files for the Torque runtime.  Do not forget
+      to change the values to match your database environment.
+    </p>
+      
+    <p>
+      Using SharedPoolDataSourceFactory (this example is also used in the 
+      Tutorial):
+    </p>
+      
+<source><![CDATA[
+torque.database.default = bookstore
+torque.database.bookstore.adapter = mysql
 
+#Using commons-dbcp
+torque.dsfactory.bookstore.factory =\
+  org.apache.torque.dsfactory.SharedPoolDataSourceFactory
+torque.dsfactory.bookstore.connection.driver = org.gjt.mm.mysql.Driver
+torque.dsfactory.bookstore.connection.url =\
+  jdbc:mysql://localhost:3306/bookstore
+torque.dsfactory.bookstore.connection.user = user
+torque.dsfactory.bookstore.connection.password = password
+]]></source>
+
+    <p>
+      Using JndiDataSourceFactory with externally bound 
+      <code>DataSource</code>:
+    </p>
+      
+<source><![CDATA[
+torque.database.default = bookstore
+torque.database.bookstore.adapter = mysql
+torque.dsfactory.bookstore.factory =\
+  org.apache.torque.dsfactory.JndiDataSourceFactory
+torque.dsfactory.bookstore.jndi.path = jdbc/jndiTestDataSource
+]]></source>
+
+    <p>
+      Using JndiDataSourceFactory to bind a <code>DataSource</code> to jndi:
+    </p>
+      
+<source><![CDATA[
+torque.database.default = bookstore
+torque.database.bookstore.adapter = mysql
+torque.dsfactory.bookstore.factory =\
+  org.apache.torque.dsfactory.JndiDataSourceFactory
+torque.dsfactory.bookstore.jndi.path = jdbc/jndiTestDataSource
+torque.dsfactory.bookstore.jndi.java.naming.factory.initial =\
+  org.apache.naming.java.javaURLContextFactory
+torque.dsfactory.bookstore.datasource.classname =\
+  org.apache.commons.dbcp.BasicDataSource
+torque.dsfactory.bookstore.datasource.password = mysql
+torque.dsfactory.bookstore.datasource.username = root
+torque.dsfactory.bookstore.datasource.driverClassName =\
+  org.gjt.mm.mysql.Driver
+torque.dsfactory.bookstore.datasource.url =\
+  jdbc:mysql://localhost:3306/bookstore
 ]]></source>
 
-</subsection>
-
-</section>
+  </section>
 
-</body>
+ </body>
 </document>

Modified: db/torque/runtime/trunk/xdocs/reference/managers-cache.xml
URL: http://svn.apache.org/viewcvs/db/torque/runtime/trunk/xdocs/reference/managers-cache.xml?rev=371077&r1=371076&r2=371077&view=diff
==============================================================================
--- db/torque/runtime/trunk/xdocs/reference/managers-cache.xml (original)
+++ db/torque/runtime/trunk/xdocs/reference/managers-cache.xml Sat Jan 21 07:46:38 2006
@@ -17,123 +17,127 @@
 
 <document>
 
-<properties>
-  <title>Torque Managers and Caching</title>
-  <author email="jmcnally@collab.net">John McNally</author>
-</properties>
-
-<body>
-    <!--
-    <section name="Table of Contents">
-      <p>
-        <ol>
-          <li>
-            <a href="#"></a>
-          </li>
-        </ol>
-      </p>
-    </section>
-    -->
-
-<section name="Managers - Intro">
-  <p>
-    Note: Managers and the caching they provide is fairly new (as this is
-    written on 2002-04-11).  Feedback is welcome and usage by the brave
-    is encouraged.  But the api should not be expected to be stable.
-  </p>
-  <p>
-    A manager is responsible for instantiating new objects, retrieving stored
-    objects, and possibly caching these objects.  Managers provide static
-    accessors for much of its functionality, so usage examples are:
-  </p>
-
-  <source><![CDATA[
-    Foo foo = FooManager.getInstance(); // gets a new Foo.
-    // id is an ObjectKey that identifies the object in the db
-    foo = FooManager.getInstance(id);
-    // ids is a List of ObjectKey's that identifies objects in the db
-    List foos = FooManager.getInstances(ids);
-  ]]></source>
-
-</section>
-
-<section name="Business Object Cache">
-
-  <p>
-    If no-arg constructor of FooManager,
-    calls setRegion(region) where the String region is the key used to
-    determine the cache, the manager will cache instances of Foo retrieved
-    via the getInstance(ObjectKey id) and getInstances(List ids) methods.
-    One possibility for the region key is the
-    fully qualified classname with dots replaced by underscores.
-  </p>
-
-  <source><![CDATA[
-    public FooManager()
-        throws TorqueException
-    {
-        setRegion("net_bar_om_Foo");
-    }
-  ]]></source>
+ <properties>
+   <title>Torque Runtime Reference - Managers and Caching</title>
+   <author email="jmcnally@collab.net">John McNally</author>
+ </properties>
+
+ <body>
+
+  <section name="Managers - Intro">
+  
+    <p>
+      To use Managers in Torque, you need to generate your object model 
+      with the generator option <code>torque.useManagers = true</code>. 
+    </p>
+  
+    <p>
+      A manager is responsible for instantiating new objects, retrieving stored
+      objects, and possibly caching these objects.  Managers provide static
+      accessors for much of its functionality, so usage examples are:
+    </p>
+
+<source><![CDATA[
+Foo foo = FooManager.getInstance(); // gets a new Foo.
+// id is an ObjectKey that identifies the object in the db
+foo = FooManager.getInstance(id);
+// ids is a List of ObjectKey's that identifies objects in the db
+List foos = FooManager.getInstances(ids);
+]]></source>
+
+    <p>
+      Note: Managers and the caching they provide is fairly new.  Feedback 
+      is welcome and usage by the brave is encouraged.  
+      But the api should not be expected to be stable.
+    </p>
+    
+    <p>
+      Also, note that the cache is global and is not Transaction-aware.
+      This implies that isolation of different transactions will be difficult
+      to achieve. For example, you might read uncommited data out of the 
+      cache even if you database transaction isolation is set to 
+      <code>READ_COMMITTED</code>.
+    </p>
+
+  </section>
+
+  <section name="Business Object Cache">
+
+    <p>
+      If no-arg constructor of FooManager,
+      calls setRegion(region) where the String region is the key used to
+      determine the cache, the manager will cache instances of Foo retrieved
+      via the getInstance(ObjectKey id) and getInstances(List ids) methods.
+      One possibility for the region key is the
+      fully qualified classname with dots replaced by underscores.
+    </p>
+
+<source><![CDATA[
+public FooManager()
+    throws TorqueException
+{
+    setRegion("net_bar_om_Foo");
+}
+]]></source>
 
-  <p>
-    The key given for the region is used in a JCS
-    configuration file, cache.ccf, to set up a cache that the manager uses
-    to store objects for which it is responsible. See the JCS
-    <a href="http://jakarta.apache.org/jcs/">
-    documentation</a> for details on configuring JCS.  But here is a
-    simple section that creates an in-memory only LRU cache for FooManager.
-  </p>
+    <p>
+      The key given for the region is used in a JCS
+      configuration file, cache.ccf, to set up a cache that the manager uses
+      to store objects for which it is responsible. See the JCS
+      <a href="http://jakarta.apache.org/jcs/">
+      documentation</a> for details on configuring JCS.  But here is a
+      simple section that creates an in-memory only LRU cache for FooManager.
+    </p>
 
-  <source><![CDATA[
+<source><![CDATA[
 jcs.region.net_bar_om_Foo=
 jcs.region.net_bar_om_Foo.cacheattributes=
     org.apache.jcs.engine.CompositeCacheAttributes
 jcs.region.net_bar_om_Foo.cacheattributes.MaxObjects=1200
 jcs.region.net_bar_om_Foo.cacheattributes.MemoryCacheName=
     org.apache.jcs.engine.memory.lru.LRUMemoryCache
-  ]]></source>
+]]></source>
 
-  <p>
-    It is a good idea to set a region for each manager, but this behavior
-    is optional.  There also will be no caching if JCS is
-    not configured for the region given in the Constructor.
-  </p>
-
-  <p>
-    The generated object model classes have methods for getting objects
-    that are related by foreign keys.  If the FOO table contains an fk to
-    the BAR table then Foo.getBar() will exist.  This method uses
-    BarManager.getInstance(bar_id) and therefore will return a cached
-    Bar, if the Bar has been previously requested (and it still exists in
-    the cache.)
-  </p>
-
-</section>
-
-<section name="Method Result Cache">
-
-  <p>
-    The above fk relationship will also generate a Bar.getFoos(Criteria).  It
-    would be preferrable that repeated requests to this method returned
-    cached results as opposed to hitting the db for each call.  It could be
-    possible to add such caching to the generated method, and Criteria
-    implements an equals() method that would make this possible.  But
-    determining the equality of a Criteria is complex and possibly buggy (this
-    is the perception of the author of this doc, there are no known bugs).
-    Invalidating the results has also not been reduced to templated Java code.
-    So whether to cache these kinds of results is left to the developer
-    who is using torque.
-  </p>
-
-  <p>
-    It is a good practice to write methods within Bar that wrap the
-    getFoos(Criteria) method.  The conversion from application parameters
-    to a Criteria is then implemented in a more maintainable manner.  For
-    example:
-  </p>
+    <p>
+      It is a good idea to set a region for each manager, but this behavior
+      is optional.  There also will be no caching if JCS is
+      not configured for the region given in the Constructor.
+    </p>
+
+    <p>
+      The generated object model classes have methods for getting objects
+      that are related by foreign keys.  If the FOO table contains an fk to
+      the BAR table then Foo.getBar() will exist.  This method uses
+      BarManager.getInstance(bar_id) and therefore will return a cached
+      Bar, if the Bar has been previously requested (and it still exists in
+      the cache.)
+    </p>
+
+  </section>
+
+  <section name="Method Result Cache">
+
+    <p>
+      The above fk relationship will also generate a Bar.getFoos(Criteria).  It
+      would be preferrable that repeated requests to this method returned
+      cached results as opposed to hitting the db for each call.  It could be
+      possible to add such caching to the generated method, and Criteria
+      implements an equals() method that would make this possible.  But
+      determining the equality of a Criteria is complex and possibly buggy (this
+      is the perception of the author of this doc, there are no known bugs).
+      Invalidating the results has also not been reduced to templated Java code.
+      So whether to cache these kinds of results is left to the developer
+      who is using torque.
+    </p>
+
+    <p>
+      It is a good practice to write methods within Bar that wrap the
+      getFoos(Criteria) method.  The conversion from application parameters
+      to a Criteria is then implemented in a more maintainable manner.  For
+      example:
+    </p>
 
-  <source><![CDATA[
+<source><![CDATA[
 public List getFoos(FooType type, boolean deleted)
 {
     List result = null;
@@ -145,15 +149,15 @@
 
     return result;
 }
-  ]]></source>
+]]></source>
 
-  <p>
-    In the above code the database will be hit for every call to the method.
-    BarManager provides some convenience code to add caching to the above
-    method, so it can be rewritten as:
-  </p>
+    <p>
+      In the above code the database will be hit for every call to the method.
+      BarManager provides some convenience code to add caching to the above
+      method, so it can be rewritten as:
+    </p>
 
-  <source><![CDATA[
+    <source><![CDATA[
 public List getFoos(FooType type, boolean deleted)
 {
     List result = null;
@@ -174,123 +178,123 @@
     }
     return result;
 }
-  ]]></source>
+    ]]></source>
 
-  <p>
-    The getMethodResult() method returns a MethodResultCache object, which
-    creates a key from the arguments given in the get method.  All the
-    arguments must be Serializable.  The first object should be the business
-    object on which the method was called.  If the object is not Serializable
-    or the method is static, a String as given by Object.toString() method or
-    the className might be used.  The second argument is the method name.
-    There are versions of the get method that take up to 3 additional arguments
-    that will be the arguments to the method, or if they are not Serializable
-    some Serializable proxy.  There is also a get method that takes an
-    Object[] that can be used for methods that have more than 3 arguments; the
-    first two objects in the array should be the instance and method name.
-    The reason for not just having the Object[] format is that keys are pooled
-    and since most methods will be less than 4 arguments, object creation
-    related to the cache is minimized.  Now the method will return cached
-    results as long as the results remain in the cache. So there must be some
-    way to invalidate these results, if the database changes in a way that
-    is likely to affect the result that should be returned by the method.
-  </p>
-
-</section>
-
-<section name="Invalidating the Cache">
-
-  <p>
-    An event model exists for invalidating cached method results.  Continuing
-    the example from above, BarManager should register itself as a listener
-    with the FooManager.
-    Then FooManager will notify BarManager, if a foo.save() is called
-    that might affect its cached results.  The following code is added to
-    BarManager.java which implements the CacheListener interface.
-  </p>
-
-  <source><![CDATA[
-    /**
-     * Method should be overridden to notify other managers with
-     * relevant CacheEvents.
-     */
-    protected void registerAsListener()
-    {
-        FooManager.addCacheListener(this);
-        XManager.addCacheListener(this);
-        ...
-    }
+    <p>
+      The getMethodResult() method returns a MethodResultCache object, which
+      creates a key from the arguments given in the get method.  All the
+      arguments must be Serializable.  The first object should be the business
+      object on which the method was called.  If the object is not Serializable
+      or the method is static, a String as given by Object.toString() method or
+      the className might be used.  The second argument is the method name.
+      There are versions of the get method that take up to 3 additional 
+      arguments that will be the arguments to the method, or if they are not 
+      Serializable some Serializable proxy.  
+      There is also a get method that takes an Object[] that can be used for 
+      methods that have more than 3 arguments; the
+      first two objects in the array should be the instance and method name.
+      The reason for not just having the Object[] format is that keys are pooled
+      and since most methods will be less than 4 arguments, object creation
+      related to the cache is minimized.  Now the method will return cached
+      results as long as the results remain in the cache. So there must be some
+      way to invalidate these results, if the database changes in a way that
+      is likely to affect the result that should be returned by the method.
+    </p>
+
+  </section>
+
+  <section name="Invalidating the Cache">
+
+    <p>
+      An event model exists for invalidating cached method results.  Continuing
+      the example from above, BarManager should register itself as a listener
+      with the FooManager.
+      Then FooManager will notify BarManager, if a foo.save() is called
+      that might affect its cached results.  The following code is added to
+      BarManager.java which implements the CacheListener interface.
+    </p>
+
+<source><![CDATA[
+/**
+ * Method should be overridden to notify other managers with
+ * relevant CacheEvents.
+ */
+protected void registerAsListener()
+{
+    FooManager.addCacheListener(this);
+    XManager.addCacheListener(this);
+    ...
+}
 
-    // -------------------------------------------------------------------
-    // CacheListener implementation
+// -------------------------------------------------------------------
+// CacheListener implementation
 
-    public void addedObject(Persistent om)
+public void addedObject(Persistent om)
+{
+    if (om instanceof Foo)
     {
-        if (om instanceof Foo)
-        {
-            getMethodResult().removeAll(om, "getFoos");
-        }
-        else if (om instanceof X)
-        {
-            getMethodResult().remove(om, GET_URLS);
-            getMethodResult().removeAll(om, GET_COMMENTS);
-        }
-        ...
+        getMethodResult().removeAll(om, "getFoos");
     }
-
-    public void refreshedObject(Persistent om)
+    else if (om instanceof X)
     {
-        addedObject(om);
+        getMethodResult().remove(om, GET_URLS);
+        getMethodResult().removeAll(om, GET_COMMENTS);
     }
+    ...
+}
 
-    /** fields which interest us with respect to cache events */
-    public List getInterestedFields()
-    {
-        List interestedCacheFields = new LinkedList();
-        interestedCacheFields.add(FooPeer.BAR_ID);
-        interestedCacheFields.add(XPeer.X_ID);
-        ...
-        return interestedCacheFields;
-    }
-  ]]></source>
+public void refreshedObject(Persistent om)
+{
+    addedObject(om);
+}
 
-  <p>
-    When a foo which is of interest to BarManager is saved, the instance is
-    passed
-    to the appropriate listener method.  This object may contain information
-    that could result in no action or possibly more precise repair of the
-    cached data.  In the above examples the cache is just cleared of all
-    data that is potentially invalid.
-    Some code is also added to FooManager to support the invalidation.
-  </p>
-
-  <source><![CDATA[
-    /**
-     * Creates a new <code>FooManager</code> instance.
-     */
-    public FooManager()
-        throws TorqueException
-    {
-        setRegion("net_bar_om_Foo");
-        validFields = new HashMap();
-        validFields.put(FooPeer.BAR_ID, null);
-    }
+/** fields which interest us with respect to cache events */
+public List getInterestedFields()
+{
+    List interestedCacheFields = new LinkedList();
+    interestedCacheFields.add(FooPeer.BAR_ID);
+    interestedCacheFields.add(XPeer.X_ID);
+    ...
+    return interestedCacheFields;
+}
+]]></source>
 
-    protected Persistent putInstanceImpl(Persistent om)
-        throws TorqueException
-    {
-        Persistent oldOm = super.putInstanceImpl(om);
-        List listeners = (List)listenersMap.get(FooPeer.BAR_ID);
-        notifyListeners(listeners, oldOm, om);
-        return oldOm;
-    }
-  ]]></source>
+    <p>
+      When a foo which is of interest to BarManager is saved, the instance is
+      passed to the appropriate listener method.  This object may contain 
+      information that could result in no action or possibly more precise
+      repair of the cached data.  In the above examples the cache is just
+      cleared of all data that is potentially invalid.
+      Some code is also added to FooManager to support the invalidation.
+    </p>
+
+<source><![CDATA[
+/**
+ * Creates a new <code>FooManager</code> instance.
+ */
+public FooManager()
+    throws TorqueException
+{
+    setRegion("net_bar_om_Foo");
+    validFields = new HashMap();
+    validFields.put(FooPeer.BAR_ID, null);
+}
+
+protected Persistent putInstanceImpl(Persistent om)
+    throws TorqueException
+{
+    Persistent oldOm = super.putInstanceImpl(om);
+    List listeners = (List)listenersMap.get(FooPeer.BAR_ID);
+    notifyListeners(listeners, oldOm, om);
+    return oldOm;
+}
+]]></source>
 
-  <p>
-    Now FooManager will notify BarManager when foo's are modified.
-  </p>
+    <p>
+      Now FooManager will notify BarManager when foo's are modified.
+    </p>
 
-</section>
+  </section>
 
-  </body>
-</document>
+ </body>
+</document>
\ No newline at end of file

Modified: db/torque/runtime/trunk/xdocs/reference/new-database-support.xml
URL: http://svn.apache.org/viewcvs/db/torque/runtime/trunk/xdocs/reference/new-database-support.xml?rev=371077&r1=371076&r2=371077&view=diff
==============================================================================
--- db/torque/runtime/trunk/xdocs/reference/new-database-support.xml (original)
+++ db/torque/runtime/trunk/xdocs/reference/new-database-support.xml Sat Jan 21 07:46:38 2006
@@ -18,102 +18,130 @@
 <document>
 
  <properties>
-  <title>DB Adapters</title>
+  <title>Torque Runtime Reference - Support for new Databases</title>
   <author email="jon@latchkey.com">Jon S. Stevens</author>
+  <author email="fischer@seitenbau.de">Thomas Fischer</author>
  </properties>
 
-<body>
+ <body>
 
-<section name="Database Adapters">
+  <section name="Introduction">
 
-<p>
-A database adapter class is a class that extends
-<code>org.apache.torque.adapter.DB</code> and encapsulates access to a specific
-RDBMS implementation. Database adapter classes already found in Torque include
-DBOracle, DBMM, DBSybase, etc. These classes allow Torque to gain access to a
-wide range of databases in a uniform manner. This allows you to easily swap
-between databases without any modification to Torque or the application built
-on top of Torque.
-</p>
-
-<p>
-Why is this necessary if Java already offers uniform database access
-in the form of JDBC? Unfortunately, underlying databases still
-use different SQL implementations and conventions. For example, the use
-of single and double quotes varies. The use of database adapter classes in
-Torque endeavors to overcome this problem.
-</p>
-
-<p>
-To add a new database adapter class to Torque you must follow these
-steps:
-</p>
-
-<p>
-<ul>
-    <li>
-        Create a new class DB&lt;dbname> that extends
-        <code>org.apache.torque.adapter.DB</code> (where dbname is the name of
-        the database or database driver you wish to add to Torque). DB is an
-        abstract class, so you need to implement a number of methods.</li>
-
-    <li>
-        Implement getStringDelimiter(). This method has to return the character
-        that the specific database implementation uses to indicate string
-        literals in SQL. This will usually be a single qoute (').</li>
-
-    <li>
-        Implement String getIdSqlForAutoIncrement(). Databases like MySQL
-        that make use of auto increment fields will implement this method.
-        For MySQL it returns "SELECT LAST_INSERT_ID()". Databases that do
-        not support this must return null.</li>
-
-    <li>
-        Implement String getSequenceSql(Object obj). Databases like Oracle
-        that support the concept of unique id generators (called sequences) will
-        implement this method. Databases that do not support this must return
-        null.</li>
-
-    <li>
-        Implement void lockTable(Connection con, String table). This method
-        should place a lock on a database table. Databases that only support
-        table level locking obviously do not require this method. Databases
-        that support row level locking must implement this method to avoid
-        synchronization problems.</li>
-
-    <li>
-        Implement void unlockTable(Connection con, String table). This method
-        should release the table lock acquired by the above-mentioned
-        method.</li>
-
-    <li>
-        Implement String ignoreCase(String in). This method should implement
-        a mechanism for case insensitive comparisons. Usually this converts
-        the string to Uppercase. Example UPPER (&lt;in>). If such a
-        mechanism does not exist in your database simple return the in parameter
-        without any modification. DO NOT return in.toUpper().</li>
-
-    <li>
-        Some databases (for example Interbase) do not support the function
-        returned by their implementation of ignoreCase() in the ORDER BY
-        clause of SELECT statements. If your database falls into this
-        category you should override the default implementation of
-        String ignoreCaseInOrderBy(String in). It is NOT required to override
-        this method for other databases--the default implementation calls
-        ignoreCase() and respectCase().</li>
-</ul>
-</p>
-
-<p>
-If you are adding support for a new RDBMS, then you will probably also
-need to create a set of Velocity templates--used by Torque to generate
-a SQL schema for your RDBMS--in the directory
-conf/torque/templates/sql/base/&lt;dbname>.  The recommend method for
-doing this is to copy an existing set of templates and adapt them to
-your RDBMS as needed.
-</p>
+    <p>
+      In the Torque Runtime, all information about a specific Database is
+      gathered in a so-called Database adapter class.  So if you want to
+      support a new database in the runtime, you need to provide a
+      Database Adapter class for this database.
+    </p>
+    
+    <p>
+      If you are adding support for a new RDBMS, then you will probably also
+      want to support the database in the Torque generator. 
+      To do this, you need to create a set of Velocity templates--used 
+      by Torque to generate a SQL schema for your RDBMS--in the templates 
+      component. The recommend method for doing this is to copy an existing set
+      of templates and adapt them to your RDBMS as needed.  This is not
+      elaborated forther here.
+    </p>
+
+  </section>
+ 
+  <section name="Database Adapters">
+
+    <p>
+      A database adapter class is a class that extends
+      <code>org.apache.torque.adapter.DB</code> and encapsulates access
+      to a specific RDBMS implementation. Database adapter classes already
+      found in Torque include DBOracle, DBMM, DBSybase, etc. 
+      These classes allow Torque to gain access to a wide range of databases
+      in a uniform manner. This allows you to easily swap between databases
+      without any modification to Torque or the application built
+      on top of Torque.
+    </p>
+
+    <p>
+      Why is this necessary if Java already offers uniform database access
+      in the form of JDBC? Unfortunately, underlying databases still
+      use different SQL implementations and conventions. For example, the use
+      of single and double quotes varies. The use of database adapter classes in
+      Torque endeavors to overcome this problem.
+    </p>
+
+    <p>
+      To add a new database adapter class to Torque you must follow these
+      steps:
+    </p>
+
+    <p>
+      <ul>
+        <li>
+          Create a new class DB&lt;dbname> that extends
+          <code>org.apache.torque.adapter.DB</code> (where dbname is the name of
+          the database or database driver you wish to add to Torque). DB is an
+          abstract class, so you need to implement a number of methods.
+        </li>
+
+        <li>
+          Implement getStringDelimiter(). This method has to return
+          the character that the specific database implementation uses to
+          indicate string literals in SQL. This will usually be a single qoute
+          (').
+        </li>
+
+        <li>
+          Implement getIdMethodType(). This method should return the method
+          the database uses to generates unique Ids.  Valid return values are
+          <code>org.apache.torque.adapter.IDMethod.AUTO_INCREMENT</code>,
+          <code>org.apache.torque.adapter.IDMethod.SEQUENCE</code>, and
+          <code>org.apache.torque.adapter.IDMethod.NO_ID_METHOD</code>.  
+        </li>
+
+        <li>
+          Implement String getIDMethodSQL(Object obj). Databases that use 
+          sequences for Id generation should return the SQL to get the next Id 
+          from the sequence, where <code>obj</code> is the name of the sequence.
+          Databases that use auto increment fields should return the last
+          generated id; <code>obj</code> is the name of the table in this case.
+          Databases that do not support this must return null.
+        </li>
+
+        <li>
+          Implement lockTable(Connection con, String table). This method
+          should place a lock on a database table, if this is possible for the 
+          database.  This method is not used internally by Torque, and was only
+          retained to provide backwards compatibility.
+        </li>
+
+        <li>
+          Implement unlockTable(Connection con, String table). This method
+          should release the table lock acquired by the above-mentioned method,
+          if possible.  This method is not used internally by Torque, 
+          and was only retained to provide backwards compatibility.
+        </li>
+
+        <li>
+          Implement ignoreCase(String in). This method should implement
+          a mechanism for case insensitive comparisons in the database. 
+          Usually this converts the string to Uppercase, for example UPPER 
+          (&lt;in&gt;). 
+          If such a mechanism does not exist in your database, 
+          simply return the in parameter without any modification. 
+          DO NOT return in.toUpper().
+        </li>
+
+        <li>
+          Some databases (for example Interbase) do not support the function
+          returned by their implementation of ignoreCase() in the ORDER BY
+          clause of SELECT statements. If your database falls into this
+          category you should override the default implementation of
+          String ignoreCaseInOrderBy(String in). It is NOT required to override
+          this method for other databases--the default implementation calls
+          ignoreCase() and respectCase().
+        </li>
+      </ul>
+    </p>
 
-</section>
+  </section>
 
-</body>
+ </body>
 </document>



---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org


Mime
View raw message