db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r1177297 - in /db/torque/torque4/trunk/torque-site/src/site: ./ xdoc/documentation/modules/generator/reference/ xdoc/documentation/modules/runtime/reference/ xdoc/documentation/modules/templates/
Date Thu, 29 Sep 2011 13:13:14 GMT
Author: tfischer
Date: Thu Sep 29 13:13:14 2011
New Revision: 1177297

URL: http://svn.apache.org/viewvc?rev=1177297&view=rev
Log:
Added various documentation:
- extending the generator to use other template languages
- using multiple databases in the runtime
- describe database independence in the templates

Added:
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/extending.xml
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/multiple-dbs.xml
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/database-independence.xml
Modified:
    db/torque/torque4/trunk/torque-site/src/site/site.xml
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/initialisation-configuration.xml

Modified: db/torque/torque4/trunk/torque-site/src/site/site.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/site.xml?rev=1177297&r1=1177296&r2=1177297&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/site.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/site.xml Thu Sep 29 13:13:14 2011
@@ -60,6 +60,7 @@
           <item name="Reference"         href="/documentation/modules/generator/reference/index.html"
collapse="true">
             <item name="Concepts"        href="/documentation/modules/generator/reference/concepts.html"/>
             <item name="Configuration"   href="/documentation/modules/generator/reference/configuration.html"/>
+            <item name="Extending"       href="/documentation/modules/generator/reference/extending.html"
collapse="true"/>
             <item name="Internals"       href="/documentation/modules/generator/reference/internals.html"
collapse="true">
               <item name="Outlet Types" href="/documentation/modules/generator/reference/internals/outletTypes.html"/>
             </item>
@@ -82,6 +83,7 @@
         </item>
         <item name="Templates"           href="/documentation/modules/templates/index.html"
collapse="true">
           <item name="Customizing the output" href="/documentation/modules/templates/customizing.html"/>
+          <item name="Database independence"  href="/documentation/modules/templates/database-independence.html"/>
           <item name="Dependencies"      href="/documentation/modules/templates/dependencies.html"/>
           <item name="Project Reports"   href="/documentation/modules/templates/reports/index.html"
collapse="true">
             <item name="Metrics"         href="/documentation/modules/templates/reports/jdepend-report.html"/>
@@ -145,6 +147,7 @@
             <item name="Writing to the DB" href="/documentation/modules/runtime/reference/write-to-db.html"/>
             <item name="Extending classes" href="/documentation/modules/runtime/reference/extend-classes.html"/>
             <item name="Connections"     href="/documentation/modules/runtime/reference/connections-transactions.html"/>
+            <item name="Multiple DBs"    href="/documentation/modules/runtime/reference/multiple-dbs.html"/>
             <item name="Managers and Cache" href="/documentation/modules/runtime/reference/managers-cache.html"/>
             <item name="Beans"           href="/documentation/modules/runtime/reference/beans.html"/>
             <item name="Relevant classes" href="/documentation/modules/runtime/reference/relevant-classes.html"/>

Added: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/extending.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/extending.xml?rev=1177297&view=auto
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/extending.xml
(added)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/extending.xml
Thu Sep 29 13:13:14 2011
@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you 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>Extending the Torque generator</title>
+ </properties>
+
+ <body>
+  <section name="Using other template languages inside the Torque generator">
+    <p>
+      If you want to extend the Torque generator in order to use another
+      template language, the following steps need to be done:
+    </p>
+    
+    <subsection name="Define a new outlet type in the configuration XML schema">
+      <p>
+        The outlets which use the new template engine need to be distinguished
+        from the existing outlets. This is done by defining a new outlet type
+        for the new template language. The outlet type is a simple string,
+        e.g. if the new template language is 
+        <a href="http://groovy.codehaus.org/">groovy</a>, a good name for the
+        outlet type would be <code>groovy</code>.
+      </p>
+      <p>
+        Before the new outlet type can be used in the configuration XML,
+        the configuration XML schema must be extended in order
+        to make the new template type definition known to the schema validator.
+        To do this, create a new schema where the standard generator XML schema
+        is included. In this schema, define a new type named ${type}Outlet
+        which extends the type baseOutlet. This type should have all
+        necessary attributes which are needed to configure the new template
+        engine.
+      </p>
+      <p>
+        An example for extending the configuration XML schema can be found
+        in the file
+        <code>src/test/otherTemplateLanguages/groovyOutlet.xsd</code>
+        in the torque generator project.
+      </p>
+    </subsection>
+    <subsection name="Write a SAX handler for configuration">
+      <p>
+        A SAX Handler needs to be written which can create and configure
+        the outlet implementation containing the new template engine.
+        The SAX handler gets called on each snippet containing an outlet
+        definition of the newly defined type.
+      </p>
+      <p>
+        The new SAX Handler must have the package
+        <code>org.apache.torque.generator.configuration.outlet</code>
+        and its name must be ${Type}OutletSaxHandler, where ${Type} is the
+        new outlet type with the first letter capitalized. For example, if
+        the new outlet type is <code>groovy</code>,
+        then the SAX Handler's class qualified name must be
+        <code>org.apache.torque.generator.configuration.outlet.GroovyOutletSaxHandler</code>.
+        You can use the class 
+        <code>org.apache.torque.generator.configuration.outlet.GroovyOutletSaxHandler</code>
+        in the generator's test classes as a starting point for your own
+        Sax Handler.
+      </p>
+      <p>
+        Conditions for the new SAX Handler are that it must not be abstract,
+        it must inherit from
+        <code>org.apache.torque.generator.configuration.outlet.OutletSaxHandler</code>.
+        The new SAX Handler must have a public constructor with four arguments
+        and the argument types
+        <code>org.apache.torque.generator.qname.QualifiedName</code>,
+        <code>org.apache.torque.generator.configuration.ConfigurationProvider</code>,
+        <code>org.apache.torque.generator.configuration.paths.ProjectPaths</code>,
+        <code>org.apache.torque.generator.configuration.ConfigurationHandlers</code>
+        which should simply be passed to the constructor of the parent class.
+      </p>
+      <p>
+        It is the SAX Handler's job to create an instance of an outlet
+        which can handle the new template language (
+        in the method <code>createOutlet</code> which needs to be implemented).
+        The outlet class itself (which then can handle templates 
+        of the new type) must also be implemented. See the class
+        <code>org.apache.torque.generator.template.groovy.GroovyOutlet.java</code>
+        in the generator's test sources as an example.
+      </p>
+    </subsection>
+    <subsection name="Referencing the extended schema">
+      <p>
+        You must reference your own schema for the 
+        <code>http://db.apache.org/torque/4.0/generator/configuration</code>
+        XML namespace wherever you use the new template type definion.
+        As an example, see the file
+        <code>src/test/otherTemplateLanguages/src/main/torque-gen/outlets/outlets.xml</code>
+        in the torque generator project.
+      </p>
+    </subsection>
+    <subsection name="Using the new template type">
+      <p>
+        And then, of course, you need to define and use the outlets with your
+        new template type. See the directory
+        <code>src/test/otherTemplateLanguages</code> and its subdirectories 
+        in the torque generator project for a simple example using groovy.
+      </p>
+    </subsection>
+  </section>
+ </body>
+</document>
\ No newline at end of file

Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/initialisation-configuration.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/initialisation-configuration.xml?rev=1177297&r1=1177296&r2=1177297&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/initialisation-configuration.xml
(original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/initialisation-configuration.xml
Thu Sep 29 13:13:14 2011
@@ -50,7 +50,7 @@
     <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,
+      <code>MapBuilder</code> classes.  This happens automatically,
       so usually you need not bother about it.
     </p>
     

Added: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/multiple-dbs.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/multiple-dbs.xml?rev=1177297&view=auto
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/multiple-dbs.xml
(added)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/multiple-dbs.xml
Thu Sep 29 13:13:14 2011
@@ -0,0 +1,76 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you 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 - Multiple Databases</title>
+ </properties>
+ 
+ <body>
+  <section name="Multiple Databases">
+    <p>
+      Torque can access multiple databases from within one Torque instance.
+      Basically this means that Torque's inbuilt connection handling can handle
+      more than one database connection pool.
+    </p>
+    <p>
+      There are three different scenarios for multiple databases,
+      with different levels of support from Torque:
+    </p>
+    <ul>
+      <li>
+        Each table has a unique name; different tables belong to different
+        databases. This situation is fully supported by the Torque runtime.
+        If the generated peer classes (generated by the torque generator 
+        using the torque templates) are used, the different databases are
+        handled automatically in the standard cases because each table has
+        a default database to which it belongs.
+      </li>
+      <li>
+        Some or all table names are not unique (there are tables with the
+        same name in different databases), and the tables with the same
+        name have the same structure (same column names and data types etc).
+        This situation is also fully supported by the Torque runtime.
+        However, the generated peer classes are not generated for this
+        situation; meaning that by default, a connection for querying and
+        saving is always opened to the default database for the given table
+        name.
+        This means you will either need to pass the correct database handle name
+        for querying and saving, or not use the connection handling
+        provided by the peer classes.
+      </li>
+      <li>
+        Some or all table names are not unique (there are tables with the
+        same name in different databases), and some of the tables with the same
+        name have a different structure than other tables with the same name.
+        This situation is not recommended, it is unclear to which extent it is
+        supported.
+      </li>
+    </ul>
+    <p>
+      The configuration of multiple databases is similar to the configurations
+      described in the section
+      <a href="initialisation-configuration.html">initialisation and configuration</a>,
+      however you will need to define more than one database handle.
+    </p>
+  </section>
+ </body>
+</document>

Added: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/database-independence.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/database-independence.xml?rev=1177297&view=auto
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/database-independence.xml
(added)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/templates/database-independence.xml
Thu Sep 29 13:13:14 2011
@@ -0,0 +1,48 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you 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 Templates - Database independence</title>
+ </properties>
+
+ <body>
+  <section name="Database independence">
+    <p>
+      The generated java code is database independent. 
+      This means that you do not have to re-generate the java code
+      in order to run it on another database.
+      However, there are a few points to observe:
+      <ul>
+        <li>Not all data types are available on all databases.</li>
+        <li>
+          The maximum length of table names and column names is different
+          between different databases. From current knowledge, table names
+          shorter than 27 characters and column names shorter than
+          31 characters are safe to use in all databases.
+        </li>
+      </ul>
+    </p>
+    <p>
+      The generated SQL is database dependent (of course).
+    </p>
+  </section>
+ </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