You are viewing a plain text version of this content. The canonical link for it is here.
Posted to torque-dev@db.apache.org by tf...@apache.org on 2012/10/29 21:02:15 UTC
svn commit: r1403473 [2/2] - in /db/torque/torque4/trunk/torque-site: ./
src/site/ src/site/xdoc/ src/site/xdoc/documentation/codegen-reference/
src/site/xdoc/documentation/codegen-reference/generator-internals/
src/site/xdoc/documentation/modules/ant-...
Copied: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/read-from-db.xml (from r1398200, db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/read-from-db.xml)
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/read-from-db.xml?p2=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/read-from-db.xml&p1=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/read-from-db.xml&r1=1398200&r2=1403473&rev=1403473&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/read-from-db.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/read-from-db.xml Mon Oct 29 20:02:13 2012
@@ -20,7 +20,7 @@
<document>
<properties>
- <title>Torque Runtime Reference - Reading from the database</title>
+ <title>Torque ORM Reference - Reading from the database</title>
<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>
@@ -157,7 +157,97 @@ List authors = AuthorPeer.doSelect(crite
</source>
</section>
+
+ <section name="AND and OR operators">
+ <p>
+ If you add multiple constraints to a Criteria, they are linked by default
+ by a logical "AND" operator. For example, the code
+ </p>
+
+<source>
+Criteria criteria = new Criteria();
+Criteria.where(AuthorPeer.LAST_NAME, "Stevens");
+Criteria.where(AuthorPeer.FIRST_NAME, "W.");
+List authors = AuthorPeer.doSelect(criteria);
+</source>
+
+ <p>
+ results in the following SQL query:
+ </p>
+
+<source>
+SELECT ... from AUTHOR where LAST_NAME='Stevens' AND FIRST_NAME='W.'
+</source>
+
+ <p>
+ However, the code above is not very easy to understand if you do not
+ know how the where conditions are connected by default.
+ So it is better to specify explicitly which operator should be used
+ to link the constraints in a Criteria.
+ This can be done by using the methods
+ <code>Criteria.and()</code> and
+ <code>Criteria.or()</code>.
+ The former and's a condition with all the other conditions already in the
+ criteria, and the latter or's a condition with all
+ the other conditions already in the criteria (Note: this is different
+ for the deprecated util.Criteria).
+ </p>
+ <p>
+ For example, to produce the following SQL query:
+ </p>
+<source><![CDATA[
+select * from abc where (a < 1 and b > 2) or (a > 5)
+]]></source>
+
+ <p>
+ you can use the code
+ </p>
+
+<source><![CDATA[
+Criteria crit = new Criteria()
+ .where(ABC.A, 1, Criteria.LESS_THAN)
+ .and(ABC.B, 2, Criteria.GREATER_THAN)
+ .or(ABC.A, 5, Criteria.GREATER_THAN);
+]]></source>
+
+ <p>
+ For more complex queries, use the
+ <code>org.apache.torque.criteria.Criterion</code> object, and the methods
+ <code>Criterion.and()</code> and
+ <code>Criterion.or()</code>
+ to combine them.
+ </p>
+
+ <p>
+ For example, the Criteria which corresponds to the SQL query
+ </p>
+
+<source><![CDATA[
+select * from abc where (a < 1 and b > 2) or (a > 5 and b < 3)
+]]></source>
+
+ <p>
+ is
+ </p>
+
+<source><![CDATA[
+Criteria crit = new Criteria();
+Criterion a1 = new Criterion(ABC.A, 1, Criteria.LESS_THAN);
+Criterion b2 = new Criterion(ABC.B, 2, Criteria.GREATER_THAN);
+Criterion a5 = new Criterion(ABC.A, 5, Criteria.GREATER_THAN);
+Criterion b3 = new Criterion(ABC.B, 3, Criteria.LESS_THAN);
+
+crit.where(a1.and(b2).or(a5.and(b3)));
+]]></source>
+
+ <p>
+ (Note that the tables used in the last examples are not defined
+ in the bookstore schema in the tutorial).
+ </p>
+
+ </section>
+
<section name="Foreign keys">
<p>
@@ -202,9 +292,9 @@ List authors = AuthorPeer.doSelect(crite
]]></source>
<p>
- The foreign key defines that a book is associated to an author by setting
- the <code>author_id</code> column of the author to the id of the
- corresponding author.
+ The foreign key defines that a book is associated to an author
+ by connecting the <code>author_id</code> column of the book table
+ to the primary key of the corresponding author table.
</p>
<p>
@@ -212,21 +302,111 @@ List authors = AuthorPeer.doSelect(crite
<code>getAuthor()</code> and <code>setAuthor(Author author)</code>
which can be used to access and set the corresponding author object.
In the Author object, the methods <code>getBooks()</code> and
- <code>addBook()</code> are generated.
+ <code>addBook()</code> are generated. These methods can also be used
+ to get the connected book objects or to create a connection, respectively.
</p>
<p>
- Note that by default, the getters query the database for the
+ By default, the getters for collections query the database for the
corresponding objects if they have not been read already. For example,
the method <code>Author.getBooks()</code> silently queries the database
for the books for the author, if they have not been read before.
If you do not like this behaviour (e.g. if you want to make sure that
all reads occur within one database transaction), set the generator option
<code>torque.om.silentDbFetch</code> to <code>false</code>.
- You can also query the database for corresponding objects for several
- other objects at once, see the sections on Joins and Fillers below.
</p>
+ <p>
+ It is recommended to create an index of the referencing side of the
+ association (in the above example the book table),
+ if you want to read associated objects from the referenced side
+ (in the above example the author side) and if the referencing column is
+ not also the primary key. In the above example:
+ </p>
+
+<source><![CDATA[
+<database ...>
+
+ <table name="book" ...>
+ ...
+ <index name="book_author_id">
+ <index-column name="author_id"/>
+ </index>
+ </table>
+</database>
+]]></source>
+
+ <p>
+ You can also use more than one column in the foreign key. This is done
+ by having more than one reference XML element inside the foreign-key
+ element.
+ </p>
+ <p>
+ Also, the referenced column does not need to be a primary key
+ (although this is unusual and not recommended for the tyspical cases).
+ If you want to use a non-primary key as referenced key,
+ simply use the desired referenced column as foreign column
+ in the reference element.
+ Note that most databases require a unique index on the referenced column
+ if it is not a primary key.
+ This is usually not created automatically, so you need to specify the
+ unique constraint in the definition of the referenced column.
+ </p>
+
+ <p>
+ The book-author example above defines a 1:n association between
+ authors and books
+ (1 because the foreign key column is required, i.e not-nullable,
+ and n because many books can point to one author, so that one author
+ can be connected to many books).
+ To define a 0..1:n association, the attribute <code>required</code>
+ of the foreign key column <code>book.author_id</code> should be set
+ to false (or not set at all, because the default value is false).
+ A 1:0..1 association is a special case of a 1:n association.
+ It is defined by adding a unique index to the n side of the association
+ (in the above case, to the <code>author_id</code> column
+ of the book table).
+ A n:m association between two tables can be created by defining an
+ association table which links the two tables. E.g. for creating an
+ n:m association between authors and books, the following association
+ table can be used:
+ </p>
+
+<source><![CDATA[
+<database ...>
+
+ <table name="book_author">
+ <column
+ name="author_id"
+ required="true"
+ primaryKey="true"
+ type="INTEGER"
+ description="Link to Author Id"/>
+ <column
+ name="book_id"
+ required="true"
+ primaryKey="true"
+ type="INTEGER"
+ description="Link to Book Id"/>
+
+ <foreign-key foreignTable="author">
+ <reference
+ local="author_id"
+ foreign="author_id"/>
+ </foreign-key>
+ <foreign-key foreignTable="book">
+ <reference
+ local="book_id"
+ foreign="book_id"/>
+ </foreign-key>
+ </table>
+</database>
+]]></source>
+ <p>
+ Of course, the foreign key column in the book column must be removed
+ for the n:m association.
+ </p>
+
</section>
<section name="Joins">
@@ -404,14 +584,14 @@ criteria.addJoin(AuthorPeer.AUTHOR_ID, B
List bookAuthors = AuthorPeer.doSelect(criteria);
</source>
- <p>
- For an inner join, the database only returns an entry
- in one table if there is a corresponding entry in the other table.
- In the example above, this means that only authors
- with a book are read.
- In contrast, with an outer join, an entry in one table is also returned
- even if there is no corresponding entry in the other table:
- </p>
+ <p>
+ For an inner join, the database only returns an entry
+ in one table if there is a corresponding entry in the other table.
+ In the example above, this means that only authors
+ with a book are read.
+ In contrast, with an outer join, an entry in one table is also returned
+ even if there is no corresponding entry in the other table:
+ </p>
<source>
Criteria criteria = new Criteria();
@@ -543,93 +723,6 @@ List books = BookPeer.doSelect(criteria)
</section>
- <section name="AND and OR operators">
-
- <p>
- If you add multiple constraints to a Criteria, they are linked by default
- by a logical "AND" operator. For example, the code
- </p>
-
-<source>
-Criteria criteria = new Criteria();
-Criteria.where(AuthorPeer.LAST_NAME, "Stevens");
-Criteria.where(AuthorPeer.FIRST_NAME, "W.");
-List authors = AuthorPeer.doSelect(criteria);
-</source>
-
- <p>
- results in the following SQL query:
- </p>
-
-<source>
-SELECT ... from AUTHOR where LAST_NAME='Stevens' AND FIRST_NAME='W.'
-</source>
-
- <p>
- To explicitly specify which operator should be used
- to link the constraints in a Criteria, use the methods
- <code>Criteria.and()</code> and
- <code>Criteria.or()</code>.
- The former and's a condition with all the other conditions already in the
- criteria, and the latter or's a condition with all
- the other conditions already in the criteria (Note: this is different
- for the deprecated util.Criteria).
- </p>
- <p>
- For example, to produce the following SQL query:
- </p>
-<source><![CDATA[
-select * from abc where (a < 1 and b > 2) or (a > 5)
-]]></source>
-
- <p>
- you can use the code
- </p>
-
-<source><![CDATA[
-Criteria crit = new Criteria()
- .where(ABC.A, 1, Criteria.LESS_THAN)
- .and(ABC.B, 2, Criteria.GREATER_THAN)
- .or(ABC.A, 5, Criteria.GREATER_THAN);
-]]></source>
-
- <p>
- For more complex queries, use the
- <code>org.apache.torque.criteria.Criterion</code> object, and the methods
- <code>Criterion.and()</code> and
- <code>Criterion.or()</code>
- to combine them.
- </p>
-
- <p>
- For example, the Criteria which corresponds to the SQL query
- </p>
-
-<source><![CDATA[
-select * from abc where (a < 1 and b > 2) or (a > 5 and b < 3)
-]]></source>
-
- <p>
- is
- </p>
-
-<source><![CDATA[
-Criteria crit = new Criteria();
-Criterion a1 = new Criterion(ABC.A, 1, Criteria.LESS_THAN);
-Criterion b2 = new Criterion(ABC.B, 2, Criteria.GREATER_THAN);
-Criterion a5 = new Criterion(ABC.A, 5, Criteria.GREATER_THAN);
-Criterion b3 = new Criterion(ABC.B, 3, Criteria.LESS_THAN);
-
-crit.where(a1.and(b2).or(a5.and(b3)));
-]]></source>
-
- <p>
- (Note that the tables used in the last examples are not defined
- in the bookstore schema in the tutorial).
- </p>
-
- </section>
-
<section name="Case insensitivity">
<p>
@@ -995,6 +1088,26 @@ log4j.logger.org.apache.torque.util = DE
</section>
+ <section name="Accessing Multiple Databases">
+
+ <p>
+ By default, when querying a table using a Peer class,
+ the Peer class will use the name of the database schema file
+ as database handle to establish a database connection.
+ However, any database handle can be used by calling the method
+ <code>Criteria.setDbName(String)</code> with the database handle key
+ as argument.
+ Changing the database handle is e.g. useful in a master-slave environment
+ where tables in different databases have the same structure and thus
+ can be queried using the same peer class.
+ </p>
+
+<source>
+log4j.logger.org.apache.torque.util = DEBUG
+</source>
+
+ </section>
+
<section name="Examples">
<subsection name="Putting JOIN, DISTINCT and ORDER BY together">
Copied: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/relevant-classes.xml (from r1398200, db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/relevant-classes.xml)
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/relevant-classes.xml?p2=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/relevant-classes.xml&p1=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/relevant-classes.xml&r1=1398200&r2=1403473&rev=1403473&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/relevant-classes.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/relevant-classes.xml Mon Oct 29 20:02:13 2012
@@ -20,7 +20,7 @@
<document>
<properties>
- <title>Torque Runtime Reference - Relevant classes and Resources</title>
+ <title>Torque ORM Reference - Relevant classes and Resources</title>
<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>
Added: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/running-the-generator.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/running-the-generator.xml?rev=1403473&view=auto
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/running-the-generator.xml (added)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/running-the-generator.xml Mon Oct 29 20:02:13 2012
@@ -0,0 +1,426 @@
+<?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 ORM Reference - Running the Generator</title>
+ </properties>
+
+ <body>
+
+ <section name="Introduction to the Generator">
+ <p>
+ Torque uses the information from the database schema
+ to generate classes by which the database can be accessed.
+ Also, Torque can generate SQL scripts and documentation in
+ HTML and xdoc format from the schema.
+ The Torque generator must be invoked in order to generate these artifacts.
+ This can be done in three different ways: via Maven 2/3, via ant or via
+ plain Java.
+ </p>
+ <p>
+ As the Torque generator is a general-purpose code generator,
+ it must also knwo how to generate these classes.
+ This is done by referencing the Torque templates from the generator run.
+ </p>
+ <p>
+ In the templates, the different generation goals (om classes, sql, doc...)
+ are organized in different packages. For each generation goal,
+ the correct package needs to be accessed. This is described in detail
+ in the following sections.<br/>
+ </p>
+ </section>
+
+ <section name="Using Maven 2/3">
+ <subsection name="Preparation">
+ <p>
+ When using Maven, the Torque generator is invoked
+ by the Torque Maven Plugin.
+ There is no need to invoke the generator manually or to add
+ the generator to the runtime dependencies of your project.
+ For adding the Torque Maven plugin to your build,
+ add the following to your pom.xml:
+ </p>
+ <source><![CDATA[
+ <plugin>
+ <groupId>org.apache.torque</groupId>
+ <artifactId>torque-maven-plugin</artifactId>
+ <version>4.0-beta1</version>
+ <executions>
+ ...(see below)
+ </executions
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.torque</groupId>
+ <artifactId>torque-templates</artifactId>
+ <version>4.0-beta1</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+ ]]></source>
+ <p>
+ In the following, only basic configuration of the Torque Maven Plugin
+ is covered. For details of configuration of the Torque Maven Plugin,
+ refer to the
+ <a href="../modules/maven-plugin/reference/generate-goal.html">generate goal reference</a>.
+ </p>
+ </subsection>
+ <subsection name="Generation of om classes">
+ <p>
+ For generating the OM classes, add the following execution to the
+ executions list of the torque-generator plugin:
+ </p>
+ <source><![CDATA[
+ <execution>
+ <id>generate-sources</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ <configuration>
+ <packaging>classpath</packaging>
+ <configPackage>org.apache.torque.templates.om</configPackage>
+ <sourceDir>${torque.schema.source.dir}</sourceDir>
+ <options>
+ <torque.om.package>${torque.target.package}</torque.om.package>
+ </options>
+ </configuration>
+ </execution>
+ ]]></source>
+ <p>
+ Replace ${torque.schema.source.dir}
+ with the directory where you put your database schemata
+ (e.g. /src/main/schema). Replace ${torque.target.package}
+ with the base package for your generation, e.g. org.apache.torque.test.
+ </p>
+ <p>
+ You can add additional options to the configuration inside the options
+ tag. The available options are described below.
+ </p>
+ <p>
+ This execution will generate the om code for all source files
+ in the schema directory ending on -schema.xml,
+ but excluding id-table-schema.xml.
+ The output will be produced in the directories
+ target/generated-sources and src/main/generated-java.
+ </p>
+ <p>
+ See the <a href="customizing.html">Customizing</a> page for a
+ documentation of available options which can be used to customize
+ the generated output.
+ </p>
+ </subsection>
+ <subsection name="Generation of ddl sql">
+ <p>
+ For generating the data description language(ddl) sql for the tables,
+ add the following execution to the executions list
+ of the Torque Maven plugin:
+ </p>
+ <source><![CDATA[
+ <execution>
+ <id>generate-sql</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ <configuration>
+ <packaging>classpath</packaging>
+ <configPackage>org.apache.torque.templates.sql</configPackage>
+ <sourceDir>${torque.schema.source.dir}</sourceDir>
+ <newFileTargetDir>target/generated-sql</newFileTargetDir>
+ <compileNewFileTargetDir>false</compileNewFileTargetDir>
+ <compileModifiedFileTargetDir>false</compileModifiedFileTargetDir>
+ <options>
+ <torque.database>${torque.target.database}</torque.database>
+ </options>
+ </configuration>
+ </execution>
+ ]]></source>
+ <p>
+ Replace ${torque.target.database} with the target database type
+ (e.g. mysql, oracle). Replace ${torque.schema.source.dir}
+ with the directory where you put your database schemata
+ (e.g. /src/main/schema).
+ </p>
+ <p>
+ This will generate the sql code for all source files in the schema
+ directory ending on -schema.xml; the output goes to the directory
+ target/generated-sql.
+ </p>
+ </subsection>
+ <subsection name="Generation of html documentation">
+ <p>
+ For generating html documentation for the tables,
+ add the following execution to the executions list
+ of the Torque Maven plugin:
+ </p>
+ <source><![CDATA[
+ <execution>
+ <id>generate-html-doc</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ <configuration>
+ <packaging>classpath</packaging>
+ <configPackage>org.apache.torque.templates.doc.html</configPackage>
+ <sourceDir>${torque.schema.source.dir}</sourceDir>
+ <newFileTargetDir>target/generated-docs</newFileTargetDir>
+ <compileNewFileTargetDir>false</compileNewFileTargetDir>
+ <compileModifiedFileTargetDir>false</compileModifiedFileTargetDir>
+ <options>
+ <torque.om.package>${torque.target.package}</torque.om.package>
+ <torque.database>${torque.target.database}</torque.database>
+ </options>
+ </configuration>
+ </execution>
+ ]]></source>
+ <p>
+ Replace ${torque.target.database} with the target database type
+ (e.g. mysql, oracle). Replace ${torque.schema.source.dir}
+ with the directory where you put your database schemata
+ (e.g. /src/main/schema). Replace ${torque.target.package}
+ with the base package for your generation, e.g. org.apache.torque.test.
+ </p>
+ <p>
+ This will generate the html documentation for all source files
+ in the schema directory ending on -schema.xml.
+ The output will be produced in the directory target/generated-docs.
+ </p>
+ </subsection>
+ <subsection name="Generation of xdoc documentation">
+ <p>
+ For generating xdoc documentation for the tables
+ (to be included into your maven site),
+ add the following execution to the executions list
+ of the Torque Maven plugin:
+ </p>
+ <source><![CDATA[
+ <execution>
+ <id>generate-xdoc</id>
+ <phase>pre-site</phase>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ <configuration>
+ <packaging>classpath</packaging>
+ <configPackage>org.apache.torque.templates.doc.xdoc</configPackage>
+ <sourceDir>${torque.schema.source.dir}</sourceDir>
+ <newFileTargetDir>target/generated-xdocs</newFileTargetDir>
+ <compileNewFileTargetDir>false</compileNewFileTargetDir>
+ <options>
+ <torque.om.package>${torque.target.package}</torque.om.package>
+ <torque.database>${torque.target.database}</torque.database>
+ </options>
+ </configuration>
+ </execution>
+ ]]></source>
+ <p>
+ Replace ${torque.target.database} with the target database type
+ (e.g. mysql, oracle). Replace ${torque.schema.source.dir}
+ with the directory where you put your database schemata
+ (e.g. /src/main/schema). Replace ${torque.target.package}
+ with the base package for your generation, e.g. org.apache.torque.test.
+ </p>
+ <p>
+ This will generate the xdoc documentation
+ for all source files in the schema directory ending on -schema.xml.
+ The output is produced in the directory target/generated-xdocs.
+ You may then want to add the following configuration to your pom
+ to include this directory in your site:
+ </p>
+ <source><![CDATA[
+ <plugin>
+ <artifactId>maven-site-plugin</artifactId>
+ <groupId>org.apache.maven.plugins</groupId>
+ <configuration>
+ <xdocDirectory>target/generated-xdocs</xdocDirectory>
+ </configuration>
+ </plugin>
+ ]]></source>
+ </subsection>
+ <subsection name="Generation of XML schema from an existing database">
+ <p>
+ For extracting the structure of an existing database into
+ a schema file,
+ add the following execution to the executions list
+ of the Torque Maven plugin:
+ </p>
+ <source><![CDATA[
+ <execution>
+ <id>generate-schema-from-jdbc</id>
+ <phase>generate-test-sources</phase>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ <configuration>
+ <packaging>classpath</packaging>
+ <configPackage>org.apache.torque.templates.jdbc2schema</configPackage>
+ <newFileTargetDir>target/generated-schema</newFileTargetDir>
+ <newFileTargetDirUsage>none</newFileTargetDirUsage>
+ <options>
+ <torque.jdbc2schema.driver>${torque.driver}</torque.jdbc2schema.driver>
+ <torque.jdbc2schema.url>${torque.database.url}</torque.jdbc2schema.url>
+ <torque.jdbc2schema.user>${torque.database.user}</torque.jdbc2schema.user>
+ <torque.jdbc2schema.password>${torque.database.password}</torque.jdbc2schema.password>
+ <torque.jdbc2schema.schema>${torque.database.schema}</torque.jdbc2schema.schema>
+ </options>
+ </configuration>
+ </execution>
+ ]]></source>
+ <p>
+ Replace ${torque.driver} with the fully qualified class name of the
+ database driver. Replace ${torque.database.url}
+ with the url to connect to the database.
+ Replace ${torque.database.user} and ${torque.database.password}
+ with the database username and the corresponding password.
+ You may want to replace ${torque.database.schema} with the database
+ schema to read, if not please remove the line containing it.
+ </p>
+ </subsection>
+ </section>
+
+
+ <section name="Using Ant">
+ <subsection name="Preparation">
+ <p>
+ When using Ant, the Torque generator is invoked
+ by the generator task, which is defined in the torque-ant-tasks
+ project.
+ Thus, the generator task needs to be defined as follows in the
+ buildfile before it can be used:
+ </p>
+ <source><![CDATA[
+ <taskdef
+ name="torque-generator"
+ classpathref="ant-classpath"
+ classname="org.apache.torque.ant.task.TorqueGeneratorTask"/>
+ ]]></source>
+ <p>
+ where ant-classpath points to a path which contains all jars from the
+ binary Torque ant tasks distribution, plus the torque-templates jar.
+ </p>
+ <p>
+ In the following, only basic configuration of the Torque Ant Tasks
+ is covered. For details of configuration of the Torque Ant Tasks,
+ refer to the
+ <a href="../modules/ant-tasks/reference/generator-task.html">generator task reference</a>.
+ </p>
+ </subsection>
+ <subsection name="Generation of om classes">
+ <p>
+ A basic configuration for generating the om classes would be
+ </p>
+ <source><![CDATA[
+ <torque-generator
+ packaging="classpath"
+ configPackage="org.apache.torque.templates.om"
+ sourceDir="${torque.schema.source.dir}">
+ <option key="torque.om.package" value="${torque.target.package}"/>
+ </torque-generator>
+ ]]></source>
+ <p>
+ Replace ${torque.schema.source.dir}
+ with the directory where you put your database schemata
+ (e.g. /src/main/schema). Replace ${torque.target.package}
+ with the base package for your generation, e.g. org.apache.torque.test.
+ </p>
+ </subsection>
+ <subsection name="Other generated artifacts">
+ <p>
+ See the maven example above for the settings necessary
+ to generate the other possible artifacts and apply them to the
+ ant tasks.
+ TODO describe in detail.
+ </p>
+ <p>
+ See <a href="../tutorial/orm/step1-ant.html">the ORM tutorial</a>
+ for a complete build file example.
+ </p>
+ </subsection>
+ </section>
+
+
+ <section name="Using Java">
+ <subsection name="Preparation">
+ <p>
+ Using Java to generate classes should not normally be necessary.
+ However, it can be useful if you neither use Maven nor Ant
+ as build system.
+ To use the generator from Maven, the Torque generato jar
+ and its dependencies must be on the class path.
+ </p>
+ <p>
+ In the following, only basic configuration of the Torque Generator
+ is covered. For details of configuration of the Torque Generator,
+ refer to the
+ <a href="../modules/generator/reference/javadocs/index.html">its javadocs</a>.
+ </p>
+ </subsection>
+ <subsection name="Generation of om classes">
+ <p>
+ A basic set-up for generating the om classes would be
+ </p>
+ <source><![CDATA[
+ Controller controller = new Controller();
+ List<UnitDescriptor> unitDescriptors = new ArrayList<UnitDescriptor>();
+
+ Map<String, String> overrideOptions = new HashMap<String, String>();
+ overrideOptions.put("torque.om.package", "${torque.target.package}");
+
+ CustomProjectPaths projectPaths
+ = new CustomProjectPaths(
+ new Maven2DirectoryProjectPaths(new File(".")));
+ projectPaths.setConfigurationPackage("org.apache.torque.templates.om");
+ projectPaths.setConfigurationDir(null);
+ projectPaths.setSourceDir(new File("${sourceDir}"));
+ projectPaths.setOutputDirectory(
+ null,
+ new File("target/generated-sources"));
+ projectPaths.setOutputDirectory(
+ Maven2ProjectPaths.MODIFIABLE_OUTPUT_DIR_KEY,
+ new File("src/main/generated-java"));
+ UnitDescriptor unitDescriptor = new UnitDescriptor(
+ UnitDescriptor.Packaging.CLASSPATH,
+ projectPaths,
+ new DefaultTorqueGeneratorPaths());
+ unitDescriptor.setOverrideOptions(
+ new MapOptionsConfiguration(overrideOptions));
+ unitDescriptors.add(unitDescriptor);
+
+ controller.run(unitDescriptors);
+ ]]></source>
+ <p>
+ Replace ${torque.schema.source.dir}
+ with the directory where you put your database schemata
+ (e.g. /src/main/schema). Replace ${torque.target.package}
+ with the base package for your generation, e.g. org.apache.torque.test.
+ </p>
+ </subsection>
+ <subsection name="Other generated artifacts">
+ <p>
+ See the maven example above for the settings necessary
+ to generate the other possible artifacts and apply them to the
+ ant tasks.
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>
Added: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/supported-databases.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/supported-databases.xml?rev=1403473&view=auto
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/supported-databases.xml (added)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/supported-databases.xml Mon Oct 29 20:02:13 2012
@@ -0,0 +1,269 @@
+<?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>Database information</title>
+ </properties>
+
+ <body>
+
+ <section name="Introduction">
+ This document contains informations on compatible versions of supported
+ databases and other database-specific information.
+ </section>
+
+ <section name="Supported RDBMS">
+ <table>
+ <tr>
+ <th>RDBMS</th>
+ <th>Driver</th>
+ <th>Tester</th>
+ </tr>
+ <tr>
+ <td><a href="#Apache_Derby">Apache Derby</a></td>
+ <td>org.apache.derby.jdbc.EmbeddedDriver</td>
+ <td>Thomas Fox</td>
+ </tr>
+ <tr>
+ <td><a href="#Hsqldb">Hsqldb</a></td>
+ <td>org.hsql.jdbcDriver</td>
+ <td>Thomas Fox</td>
+ </tr>
+ <tr>
+ <td><a href="#MySQL">MySQL</a></td>
+ <td>org.gjt.mm.mysql.Driver</td>
+ <td><a href="mailto:seade@backstagetech.com.au">Scott Eade</a></td>
+ </tr>
+ <tr>
+ <td><a href="#PostgreSQL">Postgres</a></td>
+ <td>org.postgresql.Driver</td>
+ <td><a href="mailto:seade@backstagetech.com.au">Scott Eade</a></td>
+ </tr>
+ <tr>
+ <td><a href="#Oracle">Oracle</a></td>
+ <td>oracle.jdbc.driver.OracleDriver</td>
+ <td>Thomas Fox</td>
+ </tr>
+ <tr>
+ <td><a href="#Microsoft_SQL_Server">MS SQL</a></td>
+ <td>net.sourceforge.jtds.jdbc.Driver</td>
+ <td><a href="mailto:Greg.Monroe@DukeCE.com">Greg Monroe</a></td>
+ </tr>
+ </table>
+
+ <p>
+ If your RDBMS is not listed here, please read the document about
+ <a href="new-database-support.html">writing DB Adapters</a>.
+ </p>
+ </section>
+
+ <section name="Apache Derby">
+ <subsection name="Supported Versions">
+ <p>
+ Derby 10.5.1.1 introduced support for limit and offset.
+ This is used in within Torque 4, so limit and offset does not
+ work for Derby < 10.5.1.1
+ </p>
+ </subsection>
+ </section>
+
+ <section name="HSQLDB">
+ <subsection name="Supported Versions">
+ <p>
+ Torque 4 was tested against HSQLDB 2.2.8.
+ It is unknown whether Torque 4 still works with hsqldb 1.x.-
+ </p>
+ </subsection>
+ </section>
+
+ <section name="MySQL" >
+ <subsection name="Supported Versions">
+ <p>
+ Torque 4 was tested against MySQL 5.5.
+ Subselects are known not to work for MySQL < 4.1.
+ There are no other known issues for old MySQL versions.
+ </p>
+ </subsection>
+ <subsection name="Table create options">
+ <p>
+ The MySQL templates can handle create options for tables.
+ For example, the desired create-sql output is
+ </p>
+<source><![CDATA[
+CREATE TABLE book
+(
+ ...
+) COLLATE=latin1_german2_ci ENGINE=InnoDB;
+]]></source>
+ <p>
+ For this, specify the desired options in the option elements of the
+ table to create:
+ </p>
+<source><![CDATA[
+ <table name="book" description="Book table">
+ <option key="COLLATE" value="latin1_german2_ci"/>
+ <option key="ENGINE" value="InnoDB"/>
+ ...
+ </table>
+]]></source>
+ <p>
+ Torque recognizes the following keys to be separated with an equals
+ character("=") between key and value:
+ <ul>
+ <li>ENGINE</li>
+ <li>AVG_ROW_LENGTH</li>
+ <li>CHARACTER SET</li>
+ <li>DEFAULT CHARACTER SET</li>
+ <li>CHECKSUM</li>
+ <li>COLLATE</li>
+ <li>DEFAULT COLLATE</li>
+ <li>CONNECTION</li>
+ <li>DATA DIRECTORY</li>
+ <li>DELAY_KEY_WRITE</li>
+ <li>INDEX DIRECTORY</li>
+ <li>INSERT_METHOD</li>
+ <li>KEY_BLOCK_SIZE</li>
+ <li>MAX_ROWS</li>
+ <li>MIN_ROWS</li>
+ <li>PACK_KEYS</li>
+ <li>PASSWORD</li>
+ <li>ROW_FORMAT</li>
+ <li>TABLESPACE</li>
+ <li>UNION</li>
+ </ul>
+ </p>
+ <p>
+ Torque recognizes the following keys to be separated with a space
+ character(" ") between key and value:
+ <ul>
+ <li>PARTITION BY</li>
+ </ul>
+ </p>
+ <p>
+ All other keys are ignored.
+ </p>
+ </subsection>
+ </section>
+
+ <section name="PostgreSQL">
+ <subsection name="Supported Versions">
+ <p>
+ Torque 4 was tested against PostgreSQL 9.1.
+ The CASCADE option for the drop table commands in the generated SQL
+ will only work for PostgreSQL 7.3 and later.
+ There are no other known issues for old PostgreSQL versions.
+ </p>
+ </subsection>
+ </section>
+
+ <section name="Oracle Howto" >
+
+ <subsection name="Supported Versions">
+ <p>
+ Torque 4 was tested against Oracle 11g.
+ There are no known issues for Oracle 9i and later.
+ The following issues exist for older versions of Oracle:
+ </p>
+
+ <p>
+ The data type TIMESTAMP is not supported up to and including
+ Oracle 8.1.7. Use the types DATE or TIME instead of TIMESTAMP.
+ </p>
+
+ </subsection>
+
+ <subsection name="Oracle peculiarities">
+ <p>
+ TODO check for Torque 4
+ The data type TIME only has day accuracy for Oracle. This is due to
+ the fact that oracle does not support a SQL type TIME.
+ If you are using Oracle 9i and later, you can use the type TIMESTAMP
+ instead which gives you millisecond accuracy.
+ </p>
+
+ <p>
+ Oracle does not distinguish between empty strings and null strings.
+ If an empty string is inserted into a table, it will be treated as null.
+ If you want to re-read this column by selecting records which contain
+ an empty string, oracle will return no columns. The only way to select
+ the column is to query for records which contain null in that column.
+ <br/>
+ This behaviour is different in most other databases. So if you
+ want to write code which works for other databases and oracle, you need
+ to consider both cases - the column might be null and it might contain
+ an empty string. For example:
+ </p>
+
+<source>
+Criterion c1 = new Criterion(COLUMN, "", Criteria.EQUAL);
+Criterion c2 = new Criterion(COLUMN, null, Criteria.ISNULL);
+criteria.and(c1.or(c2));
+</source>
+ </subsection>
+ </section>
+
+ <section name="Microsoft SQL Server">
+ <subsection name="Supported Versions">
+ <p>
+ Torque 4 was tested against MSSQL 2012.
+ There are no known issues for MSSQL versions >= MSSQL 2000.
+ See the jira issue
+ <a href="http://issues.apache.org/jira/browse/TORQUE-46">TORQUE-46</a>
+ for the issues with MSSQL 7.
+ </p>
+ </subsection>
+
+
+ <subsection name="Database Creation">
+ <p>
+ It helps to name the database the same name as your project.
+ If the name is not the same, you will need to manually change
+ the database name in your properties files.
+ After the database is created, you will need to create a new user, or
+ give an existing user permissions to the new database.
+ Create the new user with SQL Server Authentication,
+ and assign the users default database to the newly created database.
+ Make sure the database user has the db_owner role.
+ Please refer to SQL Server documentation for further details.
+ </p>
+ </subsection>
+
+ <subsection name="JDBC Driver">
+ <p>
+ There is an excellent open source driver for MS SQL called
+ <a href="http://jtds.sourceforge.net/">jTDS</a>. This driver is
+ being used in production mode with Torque and many other JDBC applications.
+ This driver is used for testing Torque with MSSQL, other
+ drivers should work the same, but your milage may vary.
+ </p>
+ </subsection>
+
+ <subsection name="Generated SQL Code">
+ <p>
+ SQL Scripts generated by the Ant sql target do not contain
+ the fully qualified table names, e.g. user.table.
+ When manually running these scripts, do this as the user
+ you want to own the tables.
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>
Copied: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/write-to-db.xml (from r1398200, db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/write-to-db.xml)
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/write-to-db.xml?p2=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/write-to-db.xml&p1=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/write-to-db.xml&r1=1398200&r2=1403473&rev=1403473&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/write-to-db.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/orm-reference/write-to-db.xml Mon Oct 29 20:02:13 2012
@@ -20,7 +20,7 @@
<document>
<properties>
- <title>Torque Runtime Reference - Writing to the database</title>
+ <title>Torque ORM Reference - Writing to the database</title>
<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>
@@ -155,5 +155,36 @@ AuthorPeer.doDelete(criteria);
</source>
</section>
+
+ <section name="Default values">
+ <p>
+ If a default is specified, the default value is used on both
+ a new java object and as column default value in the sql script
+ for the database.
+ However, when a java object is saved, the database value is always
+ overwritten because the normal behavior for saving a new object
+ is to write all fields.
+ This behavior can be overwritten by setting the column attribute
+ useDatabaseDefaultValue to true. In this case, the column is not
+ written on inserts if the value of the corresponding java field
+ is equal to the default.<br/>
+ It is a good idea to have a non-primary key field in each table where
+ useDatabaseDefaultValue is not set because otherwise you could run into
+ SQL syntax errors when an unchanged new object is changed
+ (because there are no values to insert).
+ </p>
+ <p>
+ One can use CURRENT_DATE, CURRENT_TIME and CURRENT_TIMESTAMP
+ as default for Date fields.
+ Setting the attribute useDatabaseDefaultValue to false
+ or not setting it makes Torque use the current java time
+ as initial field value when constructing the object
+ and saving it to the database, not considering the database default.
+ Setting the attribute useDatabaseDefaultValue to true
+ makes Torque setting the initial field value to null
+ and using the database default when the object is first
+ saved to the database.
+ </p>
+ </section>
</body>
</document>
Copied: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step2.xml (from r1402323, db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step2.xml)
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step2.xml?p2=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step2.xml&p1=db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step2.xml&r1=1402323&r2=1403473&rev=1403473&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/tutorial/orm/step2.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step2.xml Mon Oct 29 20:02:13 2012
@@ -232,8 +232,7 @@
<p>
For additional information on
the XML elements and attributes, please refer to the
- <a href="../../documentation/modules/templates/database-4-0.xsd">
- Torque Schema XSD</a>.
+ <a href="../../documentation/modules/templates/database-4-0.xsd">Schema XSD</a>.
</p>
</section>
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step3-ant.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step3-ant.xml?rev=1403473&r1=1402320&r2=1403473&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step3-ant.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step3-ant.xml Mon Oct 29 20:02:13 2012
@@ -56,7 +56,7 @@
<em>Author</em>, <em>AuthorPeer</em>,
<em>AuthorPeerImpl</em>, <em>AuthorPeerRecordMapper</em>,
<em>BaseAuthor</em>, <em>BaseAuthorPeer</em>,
- <em>BaseAuthorPeerImpl</em>, and <em>BaseAuthorPeerRecordMapper</em>.
+ <em>BaseAuthorPeerImpl</em>, and <em>BaseAuthorPeerRecordMapper</em>
(a discussion on the use of these classes is deferred
until we write our sample application).
</p>
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step3-maven.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step3-maven.xml?rev=1403473&r1=1402320&r2=1403473&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step3-maven.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/tutorial/orm/step3-maven.xml Mon Oct 29 20:02:13 2012
@@ -56,7 +56,7 @@
<em>Author</em>, <em>AuthorPeer</em>,
<em>AuthorPeerImpl</em>, <em>AuthorPeerRecordMapper</em>,
<em>BaseAuthor</em>, <em>BaseAuthorPeer</em>,
- <em>BaseAuthorPeerImpl</em>, and <em>BaseAuthorPeerRecordMapper</em>.
+ <em>BaseAuthorPeerImpl</em>, and <em>BaseAuthorPeerRecordMapper</em>
(a discussion on the use of these classes is deferred
until we write our sample application).
</p>
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/index.xml?rev=1403473&r1=1403472&r2=1403473&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/index.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/index.xml Mon Oct 29 20:02:13 2012
@@ -78,20 +78,22 @@
<dl>
<dt>torque-runtime</dt>
<dd>
- The Torque runtime contains everything to allow an
+ The Torque Runtime contains everything to allow an
application to access the database. It is the only component of Torque
needed in your application and can be used standalone.
</dd>
<dt>torque-generator</dt>
<dd>
- The generator generates the java sources for the database access
- classes used in your application.
- If you use the Maven plugin or Ant tasks, you do not need to use the
- generator directly.
+ The Torque Generator is a general-purpose code generator
+ which can be used to generate the O/R classes, SQL scripts
+ etc for OR Mapping, but can also be used for other code generation
+ purposes.
+ If you use the Torque Maven Plugin or Torque Ant Tasks,
+ you do not need to use the generator directly.
</dd>
<dt>maven-torque-plugin</dt>
<dd>
- The Torque Maven plugin makes the Torque generator accessible
+ The Torque Maven Plugin makes the Torque generator accessible
in a Maven 2/3 build.
</dd>
<dt>torque-ant-tasks</dt>
@@ -100,8 +102,8 @@
</dd>
<dt>torque-templates</dt>
<dd>
- The templates contain the building blocks used by the generator
- to create the O/R peer and object classes, SQL scripts and the like.
+ The Torque Templates contain the building blocks used by the generator
+ to create the O/R classes, SQL scripts and the like.
You can extend or change the templates if you want to customize
the output of the generator, or even write templates of your own.
</dd>
---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org