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: [email protected]
For additional commands, e-mail: [email protected]
