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 se...@apache.org on 2004/08/19 16:34:37 UTC
cvs commit: db-torque/xdocs criteria-howto.xml user-guide.xml developer-guide.xml managers-cache.xml peers-howto.xml maven-howto.xml
seade 2004/08/19 07:34:37
Modified: xdocs criteria-howto.xml user-guide.xml
developer-guide.xml managers-cache.xml
peers-howto.xml maven-howto.xml
Log:
A vast array of documentation updates - long overdue.
Revision Changes Path
1.4 +13 -13 db-torque/xdocs/criteria-howto.xml
Index: criteria-howto.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/criteria-howto.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- criteria-howto.xml 5 Dec 2003 05:04:37 -0000 1.3
+++ criteria-howto.xml 19 Aug 2004 14:34:36 -0000 1.4
@@ -23,7 +23,8 @@
<section name="Using Criteria to create Joins ">
<p>
- This example will use the related tables in the Turbine Security system
+ This example will use the related tables in the
+ <a href="http://jakarta.apache.org/turbine/">Turbine</a> Security system
between the Turbine_Role and Turbine_Permission tables, with the bridging
table, Turbine_Role_Permission. The relationship between these tables are in
the Core Schema document, with Turbine_Role and Turbine_Permission both
@@ -99,8 +100,10 @@
<p>
One of the common clauses in an SQL Query is the ORDER BY clause. This can
- be emulated with the Criteria Object via the addOrderByColumn(String
- columnname) method. For the Role example, the Role OM Objects in the
+ be emulated with the Criteria Object via the
+ addAscendingOrderByColumn(String columnname) and
+ addDescendingOrderByColumn(String columnname) methods. For the Role
+ example, the Role OM Objects in the
returned Vector can be ordered by the TURBINE_ROLE columns, ROLE_ID or
NAME. If the column chosen to order by is the ROLE_ID, the returned Vector
is ordered in numbers, if the NAME is the ordered column, the Vector
@@ -112,7 +115,7 @@
criteria.addJoin(PermissionPeer.PERMISSION_ID,RolePermissionPeer.PERMISSION_ID);
criteria.addJoin(RolePermissionPeer.ROLE_ID, RolePeer.ROLE_ID);
criteria.setDistinct();
-criteria.addOrderByColumn(RolePeer.NAME);
+criteria.addAscendingOrderByColumn(RolePeer.NAME);
List roles = RolePeer.doSelect(criteria);
</source>
@@ -144,7 +147,7 @@
criteria.addJoin(GroupPeer.GROUP_ID, UserGroupRolePeer.GROUP_ID);
criteria.addJoin(UserGroupRolePeer.USER_ID, TurbineUserPeer.USER_ID);
criteria.add(TurbineUserPeer.USERNAME, user.getUserName());
- criteria.addOrderByColumn(GroupPeer.NAME);
+ criteria.addAscendingOrderByColumn(GroupPeer.NAME);
criteria.setDistinct();
groups = GroupPeer.doSelect(criteria);
@@ -398,18 +401,15 @@
<p>
Criteria contains a toString() method which will output a representation of
- the Criteria as a String. As the Criteria to a large extent represents the
- statements in a WHERE clause of SQL, the LoggingService can output the SQL.
- In the TurbineResources.properties file, under the directive;
+ the Criteria as a String. A Criteria to a large extent represents the
+ statements in a WHERE clause of SQL. To see the queries being processed by
+ your application you can configure the logging system to capture the SQL
+ by adding the following to your <code>log4j.properties</code> file:
</p>
<source>
-services.LogginService.sql.level = DEBUG
+log4j.logger.org.apache.torque.util.BasePeer = DEBUG
</source>
-
- <p>
- Set the level to DEBUG.
- </p>
</section>
1.14 +222 -53 db-torque/xdocs/user-guide.xml
Index: user-guide.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/user-guide.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- user-guide.xml 13 Aug 2004 05:58:19 -0000 1.13
+++ user-guide.xml 19 Aug 2004 14:34:36 -0000 1.14
@@ -6,6 +6,7 @@
<title>Torque User's Guide</title>
<author email="jvanzyl@apache.org">Jason van Zyl</author>
<author email="mpoeschl@marmot.at">Martin Poeschl</author>
+ <author email="seade@backstagetech.com.au">Scott Eade</author>
</properties>
<body>
@@ -18,13 +19,13 @@
<a href="#About this Guide">About this Guide</a>
</li>
<li>
- <a href="#Torque Directory Structure">Torque Directory Structure</a>
+ <a href="#Torque components">Torque components</a>
</li>
<li>
- <a href="#Quick Start Guide">Quick Start Guide</a>
+ <a href="#Installing Torque">Installing Torque</a>
</li>
<li>
- <a href="#Configuring Torque">Configuring Torque</a>
+ <a href="#Quick Start Guide">Quick Start Guide</a>
</li>
</ol>
</p>
@@ -34,76 +35,72 @@
<section name="About this Guide">
<p>
- The Torque User's guide is intended to help those who intend
+ This User Guide is intended to help those who want
to incorporate Torque into their project to provide a means
of persistence for application objects.
</p>
</section>
-<section name="Torque Directory Structure">
-
-<p>
- Here is what the Torque directory structure looks like. There are slight
- differences between the stand-alone and TDK versions but nothing
- significant:
-</p>
-
-<source><![CDATA[
-torque/
- lib/ <-- Jar files required by Torque (stand-alone version)
- schema/ <--- Project specific XML database descriptor.
- templates/ <--- Velocity templates used for source generation.
- src/ <--- Target location for output (stand-alone version).
-
- build-torque.xml <--- Ant build file that controls Torque.
- (not named build.xml to make it easier to use it
- from your projects build.xml)
- build.properties <--- Properties file that controls Torque behaviour.
-]]></source>
+<section name="Torque components">
<p>
- A typical user of Torque would really only ever need to edit the
- <em>build.properties</em> file in base directory, and the
- <em>project-schema.xml</em> in the <strong>schema</strong> directory. We'll
- quickly go over each of these files and some of options you have using Torque.
+ Torque consists of two main components:
+ <ul>
+ <li>
+ <a href="/generator/">Generator</a> - The Torque generator uses a single XML
+ database schema file to generate the SQL for your target database and
+ Torque's Peer-based object relational model. The generator can be
+ executed using the Torque <a href="/maven-plugin/">maven-plugin</a> or
+ an <a href="http://ant.apache.org/">Ant</a> build file.
+ </li>
+ <li>
+ <a href="/">Runtime</a> - The Torque runtime is required in order to
+ compile and use of the classes produced by the generator.
+ </li>
+ </ul>
</p>
</section>
-<section name="Quick Start Guide">
+<section name="Installing Torque">
<p>
- For those who just want to see Torque go all you have to do is select your
- target database and target package in <em>build.properties</em>, edit the
- <em>project-schema.xml</em> to suit your needs, then type
- <strong>ant -f build-torque.xml</strong>.
- That's it!
+ If you have not already done so, download and install
+ <a href="http://maven.apache.org/">Maven</a>. You then need to obtain the
+ Torque maven plugin. The <a href="../maven-howto.html">Maven Howto</a>
+ includes details of how to build the maven plugin from source, but you can
+ easily install a binary distribution thus:
</p>
-<p>
- You will probably want to set the <em>project</em> property in the
- <em>build.properties</em> file eventually so that your generated sources have names
- that reflect your project name, but you can do that later :-). You also have to
- remember that if you change the <em>project</em> property that you have to
- change the name of your project XML database schema to match!
-</p>
+<source><![CDATA[
+!!! TO DO - The binary plugn is yet to be deployed, in the mean time you must build the plugin from source. !!!
+!!! TO DO - Confirm these values !!!
+maven plugin:download -DartifactId=maven-torque-plugin -DgroupId=maven-torque-plugin -Dversion=3.1.1
+]]></source>
<p>
- For example if you change the <em>project</em> property from the default
- value of "project" to "killerapp" then you must change the name of the default
- schema in the <strong>schema</strong> directory from <em>project-schema.xml</em>
- to <em>killerapp-schema.xml</em>.
+ At runtime the generated object model classes need access to the Torque
+ runtime distribution and associated libraries - these are available from the
+ <a href="http://jakarta.apache.org/builds/jakarta-turbine/torque/release/3.1.1/">
+ Downloads page</a> (the file to download is torque-3.1.1.tar.gz or
+ torque-3.1.1.zip, depending on your development platform). We will cover
+ what to do with this file in a later step.
</p>
</section>
-<section name="Configuring Torque">
+<section name="Quick Start Guide">
-<subsection name="build.properties">
+<p>
+ For those who just want to see Torque here we will race our way through all
+ that needs to be done to define, generate and use a Torque object model.\
+</p>
+
+<subsection name="Configure Torque Generator (project.properties)">
<p>
- For a complete list of build properties, please refer to the
+ For a complete list of generator properties, please refer to the
<a href="generator/properties-reference.html">properties reference</a>. Below
is a short list of the primary properties you should be interested in.
</p>
@@ -119,6 +116,12 @@
<td>torque.targetPackage</td>
</tr>
<tr>
+ <td>torque.database.createUrl</td>
+ </tr>
+ <tr>
+ <td>torque.database.buildUrl</td>
+ </tr>
+ <tr>
<td>torque.database.url</td>
</tr>
<tr>
@@ -130,11 +133,14 @@
<tr>
<td>torque.database.password</td>
</tr>
+ <tr>
+ <td>torque.database.host</td>
+ </tr>
</table>
</subsection>
-<subsection name="project-schema.xml">
+<subsection name="Define Database Schema (project-schema.xml)">
<p>
This is an example of what the XML database schema might look like. This
@@ -143,7 +149,7 @@
</p>
<source><![CDATA[
-<database>
+<database name="my_project">
<table name="ID_TABLE">
<column name="ID_TABLE_ID" required="true" primaryKey="true" type="INTEGER"/>
@@ -184,12 +190,177 @@
]]></source>
<p>
- Please refer to <a href="schema-reference.html">Torque Schema Reference</a>
+ Please refer to <a href="generator/schema-reference.html">Torque Schema Reference</a>
to find out more about the the different elements and attributes.
</p>
</subsection>
+<subsection name="Torque Runtime Configuration (Torque.properties)">
+
+<p>
+ The runtime distribution archive includes an Ant build file that can be used
+ to generate your Torque runtime configuration - see the Torque
+ <a href="tutorial/step2.html#Torque_Run-Time_Properties">tutSorial</a> for
+ details.
+</p>
+
+<source><![CDATA[
+torque.database.default = my_project
+torque.database.my_project.adapter = mysql
+
+# Using commons-dbcp
+torque.dsfactory.my_project.factory = org.apache.torque.dsfactory.SharedPoolDataSourceFactory
+torque.dsfactory.my_project.connection.driver = org.gjt.mm.mysql.Driver
+torque.dsfactory.my_project.connection.url = jdbc:mysql://localhost:3306/my_project
+torque.dsfactory.my_project.connection.user = user
+torque.dsfactory.my_project.connection.password = password
+ ]]></source>
+
+ <p>
+ The above example uses the commons-dbcp connection pool - see
+ <a href="configuration-howto.html">Pool-config Howto</a>
+ details of the available <code>DataSource</code> factories.
+ </p>
+
+</subsection>
+
+<subsection name="Add Libraries">
+
+ <p>
+ In order to be able to compile and use the generated class files it is
+ necessary to include the Torque runtime jar file and jar files for all of
+ the necessary dependencies in the classpath of your project. The necessary
+ jars are included in the <code>torque/lib</code> directory of the Torque
+ runtime. If you are using Maven to build your project it may be easiest to
+ copy the necessary <a href="../dependencies.html">dependencies</a> from the
+ <a href="http://cvs.apache.org/viewcvs.cgi/db-torque/project.xml?only_with_tag=TORQUE_3_1_BRANCH">Torque
+ runtime POM</a>.
+ </p>
+
+</subsection>
+
+<subsection name="Object Model and SQL Generation">
+
+<p>
+ Generate the object model and associated SQL:
+</p>
+
+<source><![CDATA[
+maven torque
+]]></source>
+
+<p>
+ <b>
+ Note: Torque will <em>drop</em> the database and
+ tables that it is about to create if they exist!
+ You should skip the next two steps if you are working
+ with an existing database full of data.
+ </b>
+</p>
+
+<p>
+ To creating the database:
+</p>
+
+<source><![CDATA[
+maven torque:create-db
+]]></source>
+
+<p>
+ To create the tables:
+</p>
+
+<source><![CDATA[
+maven torque:id-table-init-sql
+maven torque:insert-sql
+]]></source>
+
+</subsection>
+
+<subsection name="Using the Torque Object Model Classes">
+
+<p>
+ The following is an example of using the Torque object model classes - it is
+ adapted from the Torque <a href="tutorial/">tutorial</a>.
+</p>
+
+<source><![CDATA[
+import java.util.*;
+import ...om.*;
+import org.apache.torque.Torque;
+import org.apache.torque.util.Criteria;
+
+public class Bookstore
+{
+ public static void main(String[] args)
+ {
+ try
+ {
+ /* Initialize Torque */
+ Torque.init("Torque.properties");
+
+ /* Creating new objects */
+ Publisher addison = new Publisher();
+ addison.setName("Addison Wesley Professional");
+ addison.save();
+
+ Author bloch = new Author();
+ bloch.setFirstName("Joshua");
+ bloch.setLastName("Bloch");
+ bloch.save();
+
+ /* Foreign keys provided using convenience methods and manually. */
+ Book tcpip = new Book();
+ tcpip.setTitle("TCP/IP Illustrated, Volume 1");
+ tcpip.setISBN("0-201-63346-9");
+ effective.setPublisher(addison);
+ tcpip.setAuthorId(stevens.getAuthorId());
+ tcpip.save();
+
+ /* Selecting all books */
+ List booklist = BookPeer.doSelectAll();
+ // iterate over booklist, casting the items to Book
+
+ /* Selecting specific objects */
+ Criteria crit = new Criteria();
+ crit.add(BookPeer.ISBN, "0-201-63346-9");
+ booklist = BookPeer.doSelect(crit);
+ // iterate over booklist, casting the items to Book
+
+ /* Updating data */
+ effective.setAuthor(stevens);
+ effective.save();
+
+ tcpip.setAuthor(bloch);
+ BookPeer.doUpdate(tcpip);
+
+ /* Deleting data */
+ crit = new Criteria();
+ crit.add(BookPeer.ISBN, "0-618-12902-2");
+ BookPeer.doDelete(crit);
+
+ crit = new Criteria();
+ crit.add(BookPeer.ISBN, "0-201-63346-9");
+ crit.add(BookPeer.TITLE, "TCP/IP Illustrated, Volume 1");
+ BookPeer.doDelete(crit);
+
+ AuthorPeer.doDelete(bloch);
+ AuthorPeer.doDelete(stevens);
+ PublisherPeer.doDelete(addison);
+ }
+ catch (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+ ]]></source>
+
+</subsection>
+
+</section>
+
<!--
<p>
@@ -321,8 +492,6 @@
</table>
-->
-
-</section>
</body>
</document>
1.15 +2 -1 db-torque/xdocs/developer-guide.xml
Index: developer-guide.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/developer-guide.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- developer-guide.xml 19 Aug 2004 01:38:45 -0000 1.14
+++ developer-guide.xml 19 Aug 2004 14:34:36 -0000 1.15
@@ -89,7 +89,8 @@
]]></source>
<p>
- Please report any problems to the turbine-dev mailing list.
+ Please report any problems to the
+ <a href="mailto:torque-dev@db.apache.org">torque-dev</a> mailing list.
</p>
</section>
1.5 +4 -16 db-torque/xdocs/managers-cache.xml
Index: managers-cache.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/managers-cache.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- managers-cache.xml 13 Apr 2002 04:37:53 -0000 1.4
+++ managers-cache.xml 19 Aug 2004 14:34:36 -0000 1.5
@@ -54,33 +54,29 @@
</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 Stratum JCS
- <a href="http://jakarta.apache.org/turbine/stratum/index.html">
+ to store objects for which it is responsible. See the JCS
+ <a href="http://jakarta.apache.org/turbine/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[
-
jcs.region.net_bar_om_Foo=
jcs.region.net_bar_om_Foo.cacheattributes=
- org.apache.stratum.jcs.engine.CompositeCacheAttributes
+ org.apache.jcs.engine.CompositeCacheAttributes
jcs.region.net_bar_om_Foo.cacheattributes.MaxObjects=1200
jcs.region.net_bar_om_Foo.cacheattributes.MemoryCacheName=
- org.apache.stratum.jcs.engine.memory.lru.LRUMemoryCache
-
+ org.apache.jcs.engine.memory.lru.LRUMemoryCache
]]></source>
<p>
@@ -123,7 +119,6 @@
</p>
<source><![CDATA[
-
public List getFoos(FooType type, boolean deleted)
{
List result = null;
@@ -144,7 +139,6 @@
</p>
<source><![CDATA[
-
public List getFoos(FooType type, boolean deleted)
{
List result = null;
@@ -165,7 +159,6 @@
}
return result;
}
-
]]></source>
<p>
@@ -202,7 +195,6 @@
</p>
<source><![CDATA[
-
/**
* Method should be overridden to notify other managers with
* relevant CacheEvents.
@@ -214,7 +206,6 @@
...
}
-
// -------------------------------------------------------------------
// CacheListener implementation
@@ -246,7 +237,6 @@
...
return interestedCacheFields;
}
-
]]></source>
<p>
@@ -260,7 +250,6 @@
</p>
<source><![CDATA[
-
/**
* Creates a new <code>FooManager</code> instance.
*/
@@ -280,7 +269,6 @@
notifyListeners(listeners, oldOm, om);
return oldOm;
}
-
]]></source>
<p>
1.5 +54 -127 db-torque/xdocs/peers-howto.xml
Index: peers-howto.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/peers-howto.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- peers-howto.xml 28 Jul 2002 06:36:03 -0000 1.4
+++ peers-howto.xml 19 Aug 2004 14:34:36 -0000 1.5
@@ -5,6 +5,7 @@
<title>Peers Howto</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>
</properties>
<body>
@@ -12,9 +13,12 @@
<section name="Working With Peers">
<p>
-Peers are an Object Relation mapping tool, built on top of Village that gives
+Peers are an Object Relation mapping tool, built on top of
+<a href="http://share.whichever.com/village/">Village</a> that gives
you access to a relational database via Java objects. Peers act on a somewhat
-lower level than other O-R mapping tools like Castor or Osage. This means that
+lower level than other O-R mapping tools like
+<a href="http://www.castor.org/">Castor</a> or
+<a href="http://osage.sourceforge.net/">Osage</a>. This means that
you have to do some coding by hand, but it allows for the most flexible
solution.
</p>
@@ -26,14 +30,6 @@
how to create a new adaptor for your database.
</p>
-<p>
-NOTE: If you would like to use Peers outside of the Turbine Servlet
-(this is very common), then you need to use the TurbineConfig object to
-initialize Turbine's code with the right TurbineResources.properties
-file <strong>before</strong> you execute your Peer code. Please see the
-javadoc for the TurbineConfig object for more details.
-</p>
-
</section>
<section name="Capabilities">
@@ -126,12 +122,8 @@
</p>
<p>
-DatabaseMaps are constructed by classes called MapBuilders. Turbine has
-a default MapBuilder, called TurbineMapBuilder, that creates a
-DatabaseMap for Turbine's internal database structure. Again you should
-seldom work with MapBuilder classes. They are used internally by Peers.
-Usually there is a MapBuilder for each table in your database.
-MapBuilder classes for new schemas can be generated for you automatically.
+DatabaseMaps are constructed by classes called MapBuilders. Torque
+generates MapBuilder classes for each of the tables in your schema.
</p>
</section>
@@ -140,7 +132,7 @@
<p>
Everything in Peers resolve around Peer classes. A Peer class has a
one-to-one mapping to a Database table. You use each table's associated
-Peer class to do operations on that table. Peer classes can be generated
+Peer class to do operations on that table. Peer classes are generated
for you automatically.
</p>
@@ -186,7 +178,7 @@
<p>
Criteria is in effect a map of field names and values that forms the
criteria of a query. By default the comparison is equals (=) but you
-can define any comparison operator (<,>,<=,>=,IN,etc.).
+can define any comparison operator (<, >, <=, > =, IN, etc.).
</p>
<p>
@@ -213,28 +205,14 @@
</p>
<p>
-You use the MapBuilder to specify which of the techniques you want to use
-with your system. By default the id_table is used, because it is the
-only common denominator.
+Of course Torque also supports using the ID generation provided by the
+underlying database system - just set the <code>idMethod</code> attributes
+as desired in your schema.
</p>
<p>
-For example if you wish to set up the MapBuilder to take advantage of an
-auto-incrementing Primary Key, you can change the entry in your MapBuilder class
-from:
-</p>
-
-<source>
-tMap.setPrimaryKeyMethod(TableMap.IDBROKERTABLE);
-
-to
-
-tMap.setPrimaryKeyMethod(TableMap.AUTOINCREMENT);
-</source>
-
-<p>
-The ID Broker is used in the underlying Peer code. After you have set it
-up you need not worry about it anymore.
+The ID Broker is used in the underlying Peer code. After you have generated
+your object model classes you need not worry about it anymore.
</p>
@@ -246,38 +224,36 @@
</p>
<source>
-create table category (
- category_id int not null,
- name varchar (100) not null,
-primary key (category_id));
-
-create table item (
- item_id int not null,
- name varchar (100) not null,
- price int not null,
- category_id int,
-primary key (item_id),
-foreign key (category_id) references category (category_id)
- on delete set null
- on update cascade);
+CREATE TABLE category
+(
+ category_id INTEGER NOT NULL AUTO_INCREMENT,
+ name VARCHAR (100),
+ PRIMARY KEY(category_id)
+);
+
+CREATE TABLE item
+(
+ item_id INTEGER NOT NULL AUTO_INCREMENT,
+ name VARCHAR (100),
+ price INTEGER NOT NULL,
+ category_id INTEGER NOT NULL,
+ PRIMARY KEY(item_id),
+ FOREIGN KEY (category_id) REFERENCES category (category_id)
+);
</source>
</section>
<section name="Schema Definition">
<p>
-Peer classes are typically generated by invoking the init task in
-the ant build file (build.xml) provided with an application generated by
-the TDK. This file is located in the WEB-INF/build directory of a generated
-application.
+Peer classes are typically generated by invoking the <code>torque:om</code>
+goal using the Torque maven-plugin.
</p>
<p>
Peer class source code is generated based on the project database
schema. The definition of this schema is in XML, and the associated DTD
-is included with the TDK. In the TDK, the project schema is located in
-the WEB-INF/conf directory of the project in a file called
-<i>project</i>-schema.xml.
+is included with the Torque generator.
</p>
<p>
@@ -286,12 +262,12 @@
<source><![CDATA[
<database>
- <table name="category" idMethod="autoincrement">
+ <table name="category" idMethod="native">
<column name="category_id" required="true" autoIncrement="true"
primaryKey="true" type="INTEGER"/>
<column name="name" size="100" type="VARCHAR"/>
</table>
- <table name="item" idMethod="autoincrement">
+ <table name="item" idMethod="native">
<column name="item_id" required="true" autoIncrement="true"
primaryKey="true" type="INTEGER"/>
<column name="name" size="100" type="VARCHAR"/>
@@ -305,14 +281,6 @@
]]>
</source>
-<p>
-Note that the XML will vary according to the target database - for
-example, the autoincrement value may be used with mysql, and causes
-generation of peer source which keeps keys up to date in the associated
-java objects during inserts, etc. For more information, refer to the
-DTD which is shipped with Turbine and the TDK.
-</p>
-
</section>
<section name="Selects">
@@ -325,7 +293,7 @@
<source>
Criteria crit = new Criteria();
-Vector v = CategoryPeer.doSelect (crit);
+List categories = CategoryPeer.doSelect(crit);
</source>
<p>
@@ -340,12 +308,6 @@
List items = ItemPeer.doSelect(crit);
</source>
-<p>
-After you obtained the Vector of Data Objects you can add it to the
-Context if you're using WebMacro or Velocity. This will allow you to use
-#foreach in the template to display all the selected items.
-</p>
-
</section>
<section name="Inserts">
@@ -353,19 +315,19 @@
<p>
To do an insert we need to add all the fields to the criteria objects.
Note that the id field is not added to the Criteria. It is taken care of
-by the ID BROKER. The object that is returned by doInsert is the id of
-the newly added row.
+by underlying database system (or perhaps the ID BROKER when it is in use).
+The object that is returned by doInsert is the id of the newly added row.
</p>
<source>
Criteria crit = new Criteria();
-crit.add(CategoryPeer.NAME,"New Category");
+crit.add(CategoryPeer.NAME, "New Category");
Object o = CategoryPeer.doInsert(crit);
</source>
<p>
We can also use the overloaded method to add a new Data Object. Note
-that once again we don't set the id - the ID BROKER does this for us.
+that once again we don't set the id - this is done for us automatically.
</p>
<source>
@@ -377,24 +339,6 @@
</source>
<p>
-I saved the best for last. Say that you want to create a new database
-entry from an html form. You can use the ParameterParser object (see
-the getParameters method of RunData in the api docs) to automatically
-fill in your fields. All that you need to do is to give your html form
-fields the same name as the corresponding property in the generated Data
-Object. For example a database field ITEM_ID will cause the generated
-Data Object to have getItemId and setItemId methods. Here the property
-name is ItemId, so that should be the form field name. Then you can
-have code like this:
-</p>
-
-<source>
-Item itm = new Item()
-data.getParameters().setProperties(itm);
-Object o = ItemPeer.doInsert(itm);
-</source>
-
-<p>
Updates works pretty much the same as inserts. You just need to call
the doUpdate method from your Peer class. Just keep in mind that you
must add an id column if you wish to do updates.
@@ -410,7 +354,7 @@
<source>
Criteria crit = new Criteria();
-crit.add(ItemPeer.ITEM_ID,3);
+crit.add(ItemPeer.ITEM_ID, 3);
ItemPeer.doDelete(crit);
</source>
</section>
@@ -424,26 +368,7 @@
It is just some ideas that I have found to work well.
</p>
- </section>
-
- <section name="Subclassing">
- <p>
- Usually when we begin to add extra code for Peer classes we end up with
- the problem of where to add the code. If we add it to the generated
- BaseItemPeer and BaseCategoryPeer classes we will lose everything if
- (and trust me this does happen) we need to regenerate these classes.
- </p>
-
- <p>
- The solution is to add the extensions to the subclasses ItemPeer and
- CategoryPeer. We can regenerate the Peer classes at any time and still
- maintain any changes we add. Regenerating the Peers from the XML schema
- only affects the Base classes. The other classes are left untouched.
- </p>
-
- </section>
-
- <section name="Useful Methods">
+ <subsection name="Useful Methods">
<p>
I found that it saves a bit of duplicate work if you add some utility
methods to your Peer class. The first method is very straightforward.
@@ -474,14 +399,14 @@
static public List doSelectForCategory(int categoryid) throws Exception
{
Criteria crit = new Criteria();
- crit.add(CATEGORY_ID,categoryid);
+ crit.add(CATEGORY_ID, categoryid);
return doSelect(crit);
}
}
</source>
- </section>
+ </subsection>
- <section name="Joins and linking objects">
+ <subsection name="Joins and linking objects">
<p>
Sometimes you would like to have relations between tables be available
in the Peer objects. We defined a foreign key relationship
@@ -503,8 +428,8 @@
// select all Items with their associated Category
Criteria crit = new Criteria();
List items = ItemPeer.doSelectJoinCategory(crit);
-// access the Category associated with the first Item in the vector
-Item itm = (Item)items.get(0);
+// access the Category associated with the first Item in the list
+Item itm = (Item) items.get(0);
Category cat = itm.getCategory();
</source>
<p>
@@ -517,20 +442,20 @@
crit.add(Item.CATEGORY_ID, 2);
List items = ItemPeer.doSelectJoinCategory(crit);
// get the name of category 2
-Item itm = (Item)items.get(0);
+Item itm = (Item) items.get(0);
Category cat = itm.getCategory();
String name = cat.getName();
</source>
- </section>
+ </subsection>
- <section name="Examples">
+ <subsection name="Examples">
<p>
This is an example of a complex SQL query and the code you should use
to create it:
</p>
<source><![CDATA[
-select * from abc where (a < 1 and b > 2) or ( a > 5 and b < 3)
+select * from abc where (a < 1 and b > 2) or (a > 5 and b < 3)
]]></source>
<source><![CDATA[
@@ -547,6 +472,8 @@
There are a lot more examples of how to use the Criteria class in the
<a href ="./criteria-howto.html">Criteria Howto</a>.
</p>
+
+ </subsection>
</section>
1.7 +33 -6 db-torque/xdocs/maven-howto.xml
Index: maven-howto.xml
===================================================================
RCS file: /home/cvs/db-torque/xdocs/maven-howto.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- maven-howto.xml 13 Aug 2004 05:58:19 -0000 1.6
+++ maven-howto.xml 19 Aug 2004 14:34:36 -0000 1.7
@@ -19,6 +19,9 @@
<a href="#Installation">Installation</a>
</li>
<li>
+ <a href="#Building from Source">Building from Source</a>
+ </li>
+ <li>
<a href="#Configuration">Configuration</a>
</li>
<li>
@@ -49,15 +52,39 @@
<section name="Installation">
<p>
- Currently you must manually build the plugin by checking out Torque from CVS
- and running <code>maven plugin:install</code> from the
- <code>src/maven-plugin</code> directory. This will jar together
- the various plugin files copy it into your <code>${maven.home}/plugins</code>
- directory.
+ The maven plugin is installed thus:
+ </p>
+
+<source><![CDATA[
+!!! TO DO - The binary plugn is yet to be deployed, in the mean time you must build the plugin from source. !!!
+!!! TO DO - Confirm these values !!!
+maven plugin:download -DartifactId=maven-torque-plugin -DgroupId=maven-torque-plugin -Dversion=3.1.1
+]]></source>
+
+</section>
+
+<section name="Building from Source">
+
+ <p>
+ Building the maven plugin from source is relatively easy - you might want
+ to do this if there are fixes or enhancements in CVS that you want to make
+ use of. Another reason you might want to do this is if you wish to
+ make your own copy of the plugin that includes a set of customized
+ generator templates to modify the object model class files that will be
+ produced.
+ </p>
+
+ <p>
+ The first thing to do is to check out Torque from CVS (make sure you use
+ branch tag you desire). If you want to modify any of the generator
+ templates you would do this before running <code>maven
+ plugin:install</code> from the <code>src/maven-plugin</code> directory.
+ This will jar together the various plugin files copy it into your
+ <code>${maven.home}/plugins</code> directory.
</p>
<p>
- For consistency you should probably also install the corresponding
+ For consistency you should also install the corresponding
generator and runtime jars in your local maven repository by running
<code>maven jar:install</code> from the <code>src/generator</code>
and <code>src</code> directories respectively.
---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org