jvanzyl 01/05/18 09:24:57
Modified: xdocs/howto torque-howto.xml
xdocs/stylesheets project.xml
Removed: xdocs classhierarchy.xml
Log:
- merging the classhierchy document into the torque howto before
i start the revamp.
Revision Changes Path
1.4 +242 -37 jakarta-turbine/xdocs/howto/torque-howto.xml
Index: torque-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine/xdocs/howto/torque-howto.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- torque-howto.xml 2001/05/14 20:05:54 1.3
+++ torque-howto.xml 2001/05/18 16:24:52 1.4
@@ -2,37 +2,47 @@
<document>
<properties>
- <title>Turbine Torque</title>
- <author email="[EMAIL PROTECTED]">Turbine Documentation Team</author>
+ <title>Turbine Torque</title>
+ <author email="[EMAIL PROTECTED]">Turbine Documentation Team</author>
+ <author email="[EMAIL PROTECTED]">John McNally</author>
</properties>
<body>
<section name="What is Torque?">
+
<p>
-Torque is a utility packaged with <a href="http://jakarta.apache.org/turbine/";>
-Turbine</a> that generates all the database resources required by your web
-application. Torque uses a single XML database schema to generate the SQL for
-your target database, Turbine's Peer-based object relation model representing
-your XML database schema, and an HTML document describing the database. The
-HTML document is obviously not required by Turbine, but helps in describing
-your web app to other developers.
+
+ Torque is a utility packaged with <a href="http://jakarta.apache.org/turbine/";>
+ Turbine</a> that generates all the database resources required by your web
+ application. Torque uses a single XML database schema to generate the SQL for
+ your target database, Turbine's Peer-based object relation model representing
+ your XML database schema, and an HTML document describing the database. The
+ HTML document is obviously not required by Turbine, but helps in describing
+ your web app to other developers.
+
</p>
<p>
-Torque is currently deployed in two forms: a stand-alone version and a version
-that is bundled with the Turbine Developer's Kit. Both versions are identical
-in function, they just have slightly different configurations. The TDK version
-outputs the sources in a location where the project build system can find them,
-and the stand-alone version simply places the generated sources in an "output"
-directory in the Torque directory structure.
+
+ Torque is currently deployed in two forms: a stand-alone version and a version
+ that is bundled with the Turbine Developer's Kit. Both versions are identical
+ in function, they just have slightly different configurations. The TDK version
+ outputs the sources in a location where the project build system can find them,
+ and the stand-alone version simply places the generated sources in an "output"
+ directory in the Torque directory structure.
+
</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:
+
+ 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[
@@ -46,46 +56,54 @@
output/ <--- Target location for output (stand-alone version).
build.xml <--- Ant build file that controls Torque.
- build.sh <--- Unix script to start up Ant.
- build.bat <--- DOS bat file to start up Ant.
build.properties <--- Properties file that controls Torque behaviour.
]]></source>
<p>
-A typical user of Torque would really only ever need to edit the
-<em>torque.props</em> file in the <strong>config</strong> 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.
+
+ 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.
+
</p>
+
</section>
<section name="Quick Start Guide">
+
<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 run build.sh or
-build.bat. That's it!
+
+ 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 run build.sh or
+ build.bat. That's it!
+
</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! 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>.
+
+ 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! 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>.
+
</p>
+
</section>
<section name="Configuring Torque">
+
<strong>build.properties</strong>
<p>
-Here is a list of all the properties currently supported by Torque:
+ Here is a list of all the properties currently supported by Torque:
</p>
<table>
@@ -358,6 +376,193 @@
</tr>
</table>
+
+</section>
+
+<section name="The Object Relational Map">
+
+<p>
+
+ The OM/Peer (Torque) system can map a class hierarchy into a single table.
+ This is 1 of 3 methods generally described in object-relational mapping
+ designs. Its benefits include that it does not require joins in order to
+ gather the attributes for a single object. It falls short in modelling a
+ class hierarchy where the related classes have a non intersecting collection
+ of attributes, as in this case a row in the table will have several null
+ columns.
+
+</p>
+
+</section>
+
+<section name="A Class Hierarchy">
+
+<source>
+ A
+ |
+ -----
+ | |
+ B C
+ |
+ D
+</source>
+
+<p>
+
+ There are two ways that are built into the torque generated Peers in order
+ to specify what class a particular row in the table A represents. A row
+ will need to have some information that can distinguish the class. You
+ should specify the column in the table that serves this purpose with the
+ attribute "inheritance"
+
+</p>
+
+<source><![CDATA[
+<table name="A"...>
+ ...
+ <column name="FOO" inheritance="single" type="VARCHAR".../>
+</table>
+]]></source>
+
+<p>
+ In this case you would need to specify the full className in column FOO, so
+ the valid values of FOO would be:<br/>
+ <br/>
+ com.mycompany.project.om.A<br/>
+ com.mycompany.project.om.B<br/>
+ com.mycompany.project.om.C<br/>
+ com.mycompany.project.om.D<br/>
+ <br/>
+
+ This is slightly inefficient in storage and also generates some inefficient
+ code in the Peers because the Peer cannot know what classes are available
+ until it gets each record and so will call Class.forName(FOO's value) for each
+ row.
+
+</p>
+
+<p>
+ The efficiency can be improved in the case where the class hierarchy is
+ known, which would be in most circumstances. So you can specify the
+ classes in the xml specification:
+</p>
+
+<source><![CDATA[
+<table name="A"...>
+ ...
+ <column name="FOO" inheritance="single" type="CHAR" size="1"...>
+ <inheritance key="B" class="B" extends="com.mycompany.project.om.A"/>
+ <inheritance key="C" class="C" extends="com.mycompany.project.om.A"/>
+ <inheritance key="D" class="D" extends="com.mycompany.project.om.B"/>
+ </column>
+</table>
+]]></source>
+
+<p>
+
+ where in the above we are using NULL (or any other value) to stand for class
+ "A". An numeric column could also be used for the key. Using the above
+ method, torque will cache a copy of each class, so the Class.forName is only
+ done during APeer's initial load into memory.
+
+</p>
+
+</section>
+
+<section name="Overriding the Default Behavior">
+
+<p>
+
+ The following example comes from <a href="http://scarab.tigris.org";>Scarab</a>
+ (an issue tracking system). In Scarab a class hierarchy definition is
+ described in a few tables, this provides for an evolving hierarchy. This
+ arrangement can be provided for using the following extensions. In the
+ xml specification, the column responsible for determining the class
+ is marked using the inheritance="single" attribute.
+
+</p>
+
+<source><![CDATA[
+
+<table name="SCARAB_ISSUE_ATTRIBUTE_VALUE" idMethod="none"
+ javaName="AttributeValue">
+ <column name="ISSUE_ID" primaryKey="true" required="true"
+ type="INTEGER"/>
+ <column name="ATTRIBUTE_ID" primaryKey="true" required="true"
+ type="INTEGER" inheritance="single"/>
+ <column name="OPTION_ID" required="false" type="INTEGER"/>
+...
+ <foreign-key foreignTable="SCARAB_ISSUE">
+ <reference local="ISSUE_ID" foreign="ISSUE_ID"/>
+ </foreign-key>
+ <foreign-key foreignTable="SCARAB_ATTRIBUTE">
+ <reference local="ATTRIBUTE_ID" foreign="ATTRIBUTE_ID"/>
+ </foreign-key>
+ <foreign-key foreignTable="SCARAB_ATTRIBUTE_OPTION">
+ <reference local="OPTION_ID" foreign="OPTION_ID"/>
+ </foreign-key>
+...
+</table>
+
+]]></source>
+
+<p>
+
+ It might be interesting to note that the column responsible for the determining
+ the class is also a primary and foreign key. Marking the column this way
+ will cause torque to generate an BaseAttributeValuePeer.getOMClass method.The
+ code in this method will be attempting to create a class from the information
+ provided in column which is an integer. This is obviously wrong, but it
+ gives us a method to override to provide the correct information.
+
+ So in AttributeValuePeer, we override the method:
+
+</p>
+
+<source><![CDATA[
+
+/**
+ * Get the className appropriate for a row in the
+ * SCARAB_ISSUE_ATTRIBUTE_VALUE table
+ */
+public static Class getOMClass(Record record, int offset)
+ throws Exception
+{
+ NumberKey attId = new NumberKey(record.getValue(offset-1 + 2)
+ .asString());
+ Attribute attribute = Attribute.getInstance(attId);
+ String className = attribute.getAttributeType().getJavaClassName();
+
+ TurbineGlobalCacheService tgcs =
+ (TurbineGlobalCacheService)TurbineServices
+ .getInstance().getService(GlobalCacheService.SERVICE_NAME);
+
+ String key = getClassCacheKey(className);
+ Class c = null;
+ try
+ {
+ c = (Class)tgcs.getObject(key).getContents();
+ }
+ catch (ObjectExpiredException oee)
+ {
+ c = Class.forName(className);
+ tgcs.addObject(key, new CachedObject(c));
+ }
+
+ return c;
+}
+
+]]></source>
+
+<p>
+
+ where in the above method, we use the foreign key(s) to traverse
+ the tables to get the class information. Then we cache the Class to
+ avoid the inefficiency of Class.forName on each row. (We also cache
+ the contents of the class hierarchy tables, since the dataset is
+ quite small and static.)
+
+</p>
</section>
1.30 +0 -1 jakarta-turbine/xdocs/stylesheets/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-turbine/xdocs/stylesheets/project.xml,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -r1.29 -r1.30
--- project.xml 2001/05/14 18:56:12 1.29
+++ project.xml 2001/05/18 16:24:56 1.30
@@ -30,7 +30,6 @@
<item name="DB Adapters" href="/db-adapters.html"/>
<item name="J2EE Integration" href="/j2ee-integration.html"/>
<item name="Model 2+1" href="/model2+1.html"/>
- <item name="OM Class Hierarchy" href="/classhierarchy.html"/>
<item name="Pull MVC Model" href="/pullmodel.html"/>
<item name="Services" href="/services.html"/>
</menu>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
