I sent this to turbine-user, but didn't see a response (and the Peers Howto
on the website is unchanged), so I figured I should send it to the dev list
as well.
Since the Peers Howto was out of date and much of what it described is
now done automatically by Torque I rewrote some of the latter sections.
This mostly involved the deletion of descriptions of how to write helper
methods. These were replaced with a description of how to use the
auto-generated Base*Peer methods that do the same thing.
Hopefully someone on the Turbine team will apply the patch.
-F
Index: jakarta-turbine/xdocs/howto/peers-howto.xml
===================================================================
RCS file: /home/cvspublic/jakarta-turbine/xdocs/howto/peers-howto.xml,v
retrieving revision 1.9
diff -u -r1.9 peers-howto.xml
--- jakarta-turbine/xdocs/howto/peers-howto.xml 2001/07/06 18:24:13 1.9
+++ jakarta-turbine/xdocs/howto/peers-howto.xml 2001/08/01 19:55:29
@@ -195,6 +195,10 @@
happen often) you are still free to use raw sql queries.
</p>
+<p>
+There is more information on the use of the Criteria class in a seperate <a href
+="./criteria-howto.html">Criteria Howto</a>.
+</p>
+
</section>
<section name="ID Broker">
@@ -420,72 +424,28 @@
</p>
<p>
- <strong>Note:</strong> some information here is out of date (Subclassing).
- The <a href="../classhierarchy.html">Class Hierarchy</a> document provides
- more current information regarding mapping a hierarchy in the OM/Peer
- system.
+ <strong>Note:</strong> The <a href="../classhierarchy.html">Class
+ Hierarchy</a> document provides more information regarding mapping a
+ hierarchy in the OM/Peer system.
</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 Peer
- classes we will loose everything if (and trust me this does happen) we
- need to regenerate the classes.
+ 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 create new classes that inherits from the generated
- classes and to add the extensions here. This has the benefit that we can
- generate new classes at any time and still maintain any changes we added.
- </p>
- <p>
- To subclass successfully we need two new subclasses for each table. One
- for the data object and one for the peer class. <strong>Very Important:</strong>
- you need to override the doSelect() method of the Peer class to make sure
- that it creates objects of your new data object. If you don't do this you
- will still end up with instances of the original class and not your new
- class.
- </p>
<p>
- Here's how we are create new classes for the Category and Item tables.
+ 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>
-
-<source>
-public class MyCategoryPeer extends CategoryPeer
-{
- static public Vector doSelect (Criteria criteria) throws Exception
- {
- // Be sure to add the new class here
- return doSelect (criteria,"com.mycompany.om.MyCategory",null);
- }
-}
-
-public class MyItemPeer extends ItemPeer
-{
- static public Vector doSelect (Criteria criteria) throws Exception
- {
- // Be sure to add the new class here
- return doSelect (criteria,"com.mycompany.om.MyItem",null);
- }
-}
-</source>
-
-<source>
-public class MyCategory extends Category
-{
-}
-
-public class MyItem extends Item
-{
-}
-</source>
- <p>
- That is all there is to it, now we can start to write some code.
- </p>
</section>
<section name="Useful Methods">
@@ -497,14 +457,8 @@
</p>
<source>
-public class MyCategoryPeer extends CategoryPeer
+public class CategoryPeer extends BaseCategoryPeer
{
- static public Vector doSelect (Criteria criteria) throws Exception
- {
- // Be sure to add the new class here
- return doSelect (criteria,"com.mycompany.om.MyCategory",null);
- }
-
static public Vector doSelectAll() throws Exception
{
Criteria crit = new Criteria();
@@ -520,14 +474,8 @@
add a doSelectForCategory to the ItemPeer class.
</p>
<source>
-public class MyItemPeer extends ItemPeer
+public class ItemPeer extends BaseItemPeer
{
- static public Vector doSelect (Criteria criteria) throws Exception
- {
- // Be sure to add the new class here
- return doSelect (criteria,"com.mycompany.om.MyCategory",null);
- }
-
static public Vector doSelectForCategory(int categoryid) throws Exception
{
Criteria crit = new Criteria();
@@ -541,72 +489,42 @@
<section name="Joins and linking objects">
<p>
Sometimes you would like to have relations between tables be available
- in the Peer objects. For example you want the category of an item to be
- available through a getCategory() method.
+ in the Peer objects. We defined a foreign key relationship
+ in the Item table in the XML schema. This means getCategory() and
+ setCategory() methods are generated in the BaseItem class. In a
+ relational database the foreign key allows us to access the Category
+ row that is associated with a specific Item row. In the object model,
+ an Item class represents one row from the Item table. The getCategory()
+ method will return a reference to a Category class that represents
+ the associated row from the Category table.
</p>
- <p>
- The first thing we need to do is to add getCategory() and setCategory()
- methods to the MyItem class.
- </p>
-<source>
-public class MyItem extends Item
-{
- private MyCategory category;
- public MyCategory getCategory()
- {
- return this.category;
- }
-
- public void setCategory (MyCategory category)
- {
- this.category = category;
- }
-}
+ <p>
+ A doSelectJoinCategory() method is generated for the BaseItemPeer
+ class. It creates the join between tables and sets the Category
+ reference in the Item class. It can be used like this:
+ </p>
+<source>
+// select all Items with their associated Category
+Criteria crit = new Criteria();
+Vector v = ItemPeer.doSelectJoinCategory(crit);
+// access the Category associated with the first Item in the vector
+Item itm = (Item)v.elementAt(0);
+Category cat = itm.getCategory();
</source>
<p>
- Next we need to create a doSelectWithCategory() method for the ItemPeer
- class that creates the join between tables and inserts the category. We
- do it like this:
+ We can also constrain the selected rows just as we would with a normal
+ doSelect() method:
</p>
<source>
-public Vector doSelectWithCategory (Criteria crit) throws Exception
-{
- crit.addJoin (ItemPeer.CATEGORY_ID, CategoryPeer.CATEGORY_ID);
-
- addSelectColumns ( criteria );
- CategoryPeer.addSelectColumns ( criteria );
-
- // BasePeer returns a Vector of Value (Village) arrays. The array
- // order follows the order columns were placed in the Select clause.
-
- Vector rows = BasePeer.doSelect(criteria);
-
- Vector results = new Vector();
-
- // populate the object(s)
- for ( int i=0; i<rows.size(); i++ )
- {
- Record row = (Record)rows.elementAt(i);
-
- MyItem itm = row2Object (row,
- 1,
- Class.forName
- ("com.mycompany.om.MyItem"));
-
- MyCategory cat = CategoryPeer.row2Object
- (row,
- numColumns+1,
- Class.forName
- ("com.mycompany.om.MyCategory"));
-
- itm.setCategory (cat);
- results.add (itm);
- }
-
- return results;
-
-}
+// select only Items with a category of 2
+Criteria crit = new Criteria();
+crit.add(Item.CATEGORY_ID, 2);
+Vector v = ItemPeer.doSelectJoinCategory(crit);
+// get the name of category 2
+Item itm = (Item)v.elementAt(0);
+Category cat = itm.getCategory();
+String name = cat.getName();
</source>
</section>
@@ -633,6 +551,10 @@
crit.add( a1.and(b2).or(a5.and(b3)) );
]]></source>
+
+ <p>
+ There are a lot more examples of how to use the Criteria class in the <a href
+="./criteria-howto.html">Criteria Howto</a>.
+ </p>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
