You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@turbine.apache.org by dl...@apache.org on 2001/08/08 19:29:51 UTC
cvs commit: jakarta-turbine/docs/howto peers-howto.html
dlr 01/08/08 10:29:51
Modified: docs/howto Tag: T_2_1_BRANCH peers-howto.html
Log:
HTML corresponding to recent patch.
Revision Changes Path
No revision
No revision
1.2.2.4 +172 -202 jakarta-turbine/docs/howto/peers-howto.html
Index: peers-howto.html
===================================================================
RCS file: /home/cvs/jakarta-turbine/docs/howto/peers-howto.html,v
retrieving revision 1.2.2.3
retrieving revision 1.2.2.4
diff -u -u -r1.2.2.3 -r1.2.2.4
--- peers-howto.html 2001/05/28 15:02:36 1.2.2.3
+++ peers-howto.html 2001/08/08 17:29:51 1.2.2.4
@@ -38,7 +38,7 @@
<tr>
<!-- LEFT SIDE NAVIGATION -->
- <td valign="top" nowrap="true">
+ <td width="20%" valign="top" nowrap="true">
<p><strong>Essentials</strong></p>
<ul>
<li> <a href="../index.html">Overview</a>
@@ -139,14 +139,13 @@
</li>
</ul>
</td>
- <td align="left" valign="top">
+ <td width="80%" align="left" valign="top">
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Working With Peers"><strong>Working With Peers</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
@@ -159,8 +158,8 @@
<p>
Peers use Turbine's Database adaptor classes that make uniform connection
to a wide range of databases possible. If your database is not supported
-you can read the Database Adapter docs on how to create a new adaptor for
-your database.
+you can read the <a href="../db-adapters.html">Database Adapter</a> docs on
+how to create a new adaptor for your database.
</p>
<p>
NOTE: If you would like to use Peers outside of the Turbine Servlet
@@ -177,10 +176,108 @@
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
- <a name="Database Maps"><strong>Database Maps</strong></a>
+ <a name="Capabilities"><strong>Capabilities</strong></a>
</font>
</td></tr>
+ <tr><td>
+ <blockquote>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+> I'm looking for an O-R layer for the next version of our system;
+> somebody recommended that I evaluate Peers. I've identified 7
+> structural cases and a few other criteria that I'd like in an O-R tool.
+> Can an experienced Peers user or developer tell me how well it handles
+> these situations?
+>
+> O-R structures:
+> 1) simple (1 class, 1 table)
+
+You use a tool called Torque to generate Peer classes for you. There
+are 4 classes for each table. Base<table-name>Peer, Base<table-name>,
+<table-name>Peer and Base<table-name>
+
+The Base* classes contains all the functionality and should not be
+change. The other two classes are empty and this is where your
+application business logic goes. If you regenerate with torque only the
+Base* classes changes. This allows you to change the schema, but still
+keep your existing code.
+
+> 2) 1:n
+
+Torque will generate methods for you to access the relevant objects.
+
+For example Category and Item. Category.getItems() will give all the
+items for a category or Item.getCategory() will give the associated
+Category for an Item.
+
+Torque also generates methods for joining all objects with less db hits
+as to improve performance.
+
+> 3) n:m
+
+You can use the methods generated by Torque for this, but it would
+probably be more efficient to use a Criteria object. Joins are very
+easy to do and you'll find that you'll be able to do complex multi-table
+joins without a problem.
+
+> 4) self join 1:n (object trees)
+
+Same as (3). I have very efficient code that loads a tree from a table
+into a in memory tree representation with a single db hit. If you're
+interested I can give it to you.
+
+> 5) self join n:m (object maps)
+
+Same as (3).
+
+> 6) simple inheritance (S extends B, each maps to a table with a shared
+> primary key)
+
+I don't think there is any support for this at the moment, but it could
+probably be done.
+
+> 7) polymorphic inheritance (S and T extend B, the application works with
+> a collection of B)
+
+Same as (6)
+
+> The only other real requirement I've got is good documentation.
+
+As an added bonus Peer allows you to create objects from a standard SQL
+query. This gives you the opportunity to do things by hand wherever you
+might find Peers lacking (which isn't a lot :-)
+
+The documentation is coming along nicely, but there is room for
+improvement. We'll help you with Peer if you help out with docs :-)
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ </blockquote>
+ </p>
+ </td></tr>
<tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Database Maps"><strong>Database Maps</strong></a>
+ </font>
+ </td></tr>
<tr><td>
<blockquote>
<p>
@@ -191,7 +288,7 @@
</p>
<p>
There is exactly one DatabaseMap for each relational database that you
-connect to. You may wish to connect to more that one database in your
+connect to. You may wish to connect to more than one database in your
application. You should then have one DatabaseMap for each of the
databases.
</p>
@@ -214,11 +311,10 @@
<a name="Peer Classes"><strong>Peer Classes</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
-Everything in Peers resolve around Peer classes. A Peer class have a
+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
for you automatically.
@@ -226,7 +322,7 @@
<p>
Peer classes have static methods only, so you would never create objects of
Peer classes. It is not necessary to have objects on this level because
-of the one-to-one mapping with a table. Peer methods are thread-save.
+of the one-to-one mapping with a table. Peer methods are thread safe.
</p>
</blockquote>
</p>
@@ -239,7 +335,6 @@
<a name="Data Objects"><strong>Data Objects</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
@@ -249,8 +344,8 @@
</p>
<p>
Data Objects are used almost exclusively with their related Peer classes.
-Where peer classes "wraps around" around a database table, a Data Object
-"wraps around" individual rows of the table. The two always go together.
+Where peer classes "wrap around" around a database table, a Data Object
+"wrap around" individual rows of the table. The two always go together.
</p>
<p>
You normally use Data Objects in one of two ways. The most common way
@@ -270,7 +365,6 @@
<a name="Criteria Objects"><strong>Criteria Objects</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
@@ -289,6 +383,9 @@
DISTINCT. If Criteria is too limited for your purposes (which should not
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>
</blockquote>
</p>
</td></tr>
@@ -300,7 +397,6 @@
<a name="ID Broker"><strong>ID Broker</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
@@ -358,7 +454,6 @@
<a name="Typical Peer Usage"><strong>Typical Peer Usage</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
@@ -409,22 +504,24 @@
<a name="Schema Definition"><strong>Schema Definition</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
-Peer classes are typically generated by invoking one of the
-<i>build-project</i> scripts that are provided by the TDK. On a unix
-host, for example, the relevant script is called
-<code>build-project.sh</code> and this should be invoked with the
-<code>init</code> argument to generate the peers.
+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.
</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. For the schema described above, the XML would
-look something like
+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.
</p>
+ <p>
+For the schema described above, the XML would look something like
+</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
@@ -483,7 +580,6 @@
<a name="Selects"><strong>Selects</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
@@ -558,7 +654,6 @@
<a name="Inserts"><strong>Inserts</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
@@ -656,7 +751,7 @@
<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 and id column if you wish to do Updates.
+must add an id column if you wish to do updates.
</p>
</blockquote>
</p>
@@ -669,11 +764,10 @@
<a name="Deletes"><strong>Deletes</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
-Deletes work much in the same way than a select. If you for example
+Deletes work much in the same way as a select. If you, for example,
want to delete the item with id = 3 then you simply add it to the
Criteria and call doDelete.
</p>
@@ -711,20 +805,18 @@
<a name="Advanced Peer Techniques"><strong>Advanced Peer Techniques</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
- In this doc I'm going to try and explain a bit more about using Peers than
- just run of the mill selects, inserts and updates. However, this is by no
- means the be-all and end-all of Peer usage. It is just some ideas that I
- have found to work well.
+ In this section I'm going to try and explain a bit more about using
+ Peers than just run of the mill selects, inserts and updates.
+ However, this is by no means the be-all and end-all of Peer usage.
+ It is just some ideas that I have found to work well.
</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>
</blockquote>
</p>
@@ -737,99 +829,20 @@
<a name="Subclassing"><strong>Subclassing</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
- Usually when we begin to 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.
+ 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>
- <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>
- Using the example in the <a href="peers.html">Peers docs</a> we are
- going to create new classes for the Category and Item tables.
- </p>
- <div align="left">
- <table cellspacing="4" cellpadding="0" border="0">
- <tr>
- <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- </tr>
- <tr>
- <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- <td bgcolor="#ffffff"><pre>
-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 ItemPeer 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);
- }
-}
-</pre></td>
- <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- </tr>
- <tr>
- <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- </tr>
- </table>
- </div>
- <div align="left">
- <table cellspacing="4" cellpadding="0" border="0">
- <tr>
- <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- </tr>
- <tr>
- <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- <td bgcolor="#ffffff"><pre>
-public class MyCategory extends Category
-{
-}
-
-public class MyItem extends Item
-{
-}
-</pre></td>
- <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- </tr>
- <tr>
- <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
- </tr>
- </table>
- </div>
- <p>
- That is all there is to it, now we can start to write some code.
- </p>
</blockquote>
</p>
</td></tr>
@@ -841,7 +854,6 @@
<a name="Useful Methods"><strong>Useful Methods</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
@@ -860,14 +872,8 @@
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>
-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();
@@ -900,14 +906,8 @@
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>
-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();
@@ -936,18 +936,24 @@
<a name="Joins and linking objects"><strong>Joins and linking objects</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
- Sometimes you would like to have relations between tables to be available
- in the Peer objects. For example you want the category of an item to be
- available through a getCategory() method.
+ Sometimes you would like to have relations between tables be available
+ 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>
+ 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>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
@@ -958,20 +964,12 @@
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>
-public class MyItem extends Item
-{
- private MyCategory category;
-
- public MyCategory getCategory()
- {
- return this.category;
- }
-
- public void setCategory (MyCategory category)
- {
- this.category = category;
- }
-}
+// 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();
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
@@ -983,9 +981,8 @@
</table>
</div>
<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>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
@@ -997,43 +994,14 @@
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>
-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();
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
@@ -1055,7 +1023,6 @@
<a name="Examples"><strong>Examples</strong></a>
</font>
</td></tr>
- <tr><td><br/></td></tr>
<tr><td>
<blockquote>
<p>
@@ -1114,6 +1081,9 @@
</tr>
</table>
</div>
+ <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>
</blockquote>
</p>
</td></tr>
---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-dev-help@jakarta.apache.org