db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From arm...@apache.org
Subject cvs commit: db-ojb/xdocs tutorial3.xml tutorial4.xml
Date Thu, 07 Aug 2003 22:50:58 GMT
arminw      2003/08/07 15:50:58

  Modified:    xdocs    tutorial3.xml tutorial4.xml
  Log:
  update by Brian McCallister
  
  Revision  Changes    Path
  1.26      +281 -232  db-ojb/xdocs/tutorial3.xml
  
  Index: tutorial3.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/xdocs/tutorial3.xml,v
  retrieving revision 1.25
  retrieving revision 1.26
  diff -u -r1.25 -r1.26
  --- tutorial3.xml	22 Jul 2003 22:59:46 -0000	1.25
  +++ tutorial3.xml	7 Aug 2003 22:50:58 -0000	1.26
  @@ -21,9 +21,9 @@
     <p>
       Throughout this tutorial I will use classes from the package
       <code>org.apache.ojb.broker</code>. This is
  -    working code from the JUnit Testsuite. Thus it's guaranteed to work.
  +    working code from the JUnit Testsuite. Thus it is guaranteed to work.
       It should be quite straightforward to reuse these samples to build up
  -    your own applications. I hope you'll find this hands on approach
  +    your own applications. I hope you will find this hands on approach
       helpful for building your own OJB based applications.
     </p>
   
  @@ -34,7 +34,8 @@
     <li>
       <A HREF="#mapping 1:n associations">mapping 1:n associations</A>
       <ul>
  -      <li><A HREF="#types allowed for implementing 1:n associations">types allowed for implementing 1:n associations</A></li>
  +      <li><A HREF="#types allowed for implementing 1:n associations">types allowed for
  +          implementing 1:n associations</A></li>
       </ul>
     </li>
     <li>
  @@ -93,7 +94,8 @@
   <section name="mapping 1:1 associations">
     <p>
       As a sample for a simple association we take the reference from an
  -    article to its productgroup.<br/>This association is navigable only
  +    article to its productgroup.<br/>
  +    This association is navigable only
       from the article to its productgroup. Both classes are modelled in
       the following class diagram. This diagram does not show methods, as
       only attributes are relevant for the O/R mapping process.<br/><br/><br/>
  @@ -210,19 +212,19 @@
   
     ]]></source>
     <p>
  -    This example does provide unidirectional navigation only. To provide
  -    bidirectional navigation by adding a reference from a ProductGroup to
  -    a single Article (say a sample article for the productgroup) we have
  -    to perform the following steps:
  +    This example provides unidirectional navigation only. Bidirectional
  +    navigation may be added by including a reference from a ProductGroup to a
  +    single Article (for example, a sample article for the productgroup). To accomplish
  +    this we need to perform the following steps:
     </p>
     <OL>
       <LI>
  -    Add an attribute private Article <code>sampleArticle</code>
  +    Add a private Article attribute named <code>sampleArticle</code>
       to the class <code>ProductGroup</code>.
       </LI>
       <LI>
  -    Add a foreignkey attribute private int <code>sampleArticleId</code>
  -    to <it>ProductGroup</it>.
  +    Add a private int attribute named <code>sampleArticleId</code>
  +    to the <it>ProductGroup</it> class representing the foreign key.
       </LI>
       <LI>
       Add a column <code>SAMPLE_ARTICLE_ID
  @@ -257,10 +259,11 @@
   
   <section name="mapping 1:n associations">
     <p>
  -  As a sample for a 1:n association we take a different
  -  perspective on the previous example. We allow to have a ProductGroup
  -  multiple Articles. This association is navigable only from the
  -  productgroup to its articles. Both classes are modelled in the
  +  We will take a different perspective from the previous exmaple for
  +  a 1:n association. We will associate multiple Articles with a
  +  single ProductGroup.
  +  This association is navigable only from the
  +  ProductGroup to its Article instances. Both classes are modelled in the
     following class diagram. This diagram does not show methods, as only
     attributes are relevant for the O/R mapping process.<br/><br/><br/>
     </p>
  @@ -269,14 +272,14 @@
     <br/>
     The
     association is implemented by the <code>Vector</code>
  -  attribute <code>allArticlesInGroup</code>.
  -  As in the previous example the Article class contains a foreignkey
  -  attribute productGroupId that identifies an articles productgroup.
  +  attribute <code>allArticlesInGroup</code> on the ProductGroup class.
  +  As in the previous example, the Article class contains a foreignkey
  +  attribute named productGroupId that identifies an Article's ProductGroup.
     The Database table are the same as above.
     </p>
     <p>
     To declare the foreign key mechanics of this collection attribute
  -  we have to add a CollectionDescriptor to the ClassDescriptor of the
  +  we must add a CollectionDescriptor to the ClassDescriptor of the
     ProductGoup class. This descriptor contains the following
     information:
     </p>
  @@ -285,11 +288,11 @@
             	The attribute implementing the association (<code>name="allArticlesInGroup"</code>)
             </LI>
             <LI>
  -          	The class of the collection elements
  +          	The class of the elements in the collection
             	(<code>element-class-ref="org.apache.ojb.broker.Article"</code>)
             </LI>
             <LI>
  -	          The names of field-descriptors of the element class
  +	          The name of field-descriptor of the element class
   	          used as foreign key attributes are defined in inverse-foreignkey elements:
   	           (<code><inverse-foreignkey field-ref="productGroupId"/></code>
   	          this is again pointing to the field-descriptor for the attribute
  @@ -340,22 +343,35 @@
     <br/>
     With the mapping shown above OJB has two possibilities to load the Articles belonging to a ProductGroup:
     <ol type = 'A'>
  -  <li>loading all Articles of the ProductGroup immediately after loading the ProductGroup. This is done with <b>two</b> SQL-calls: one for the ProductGroup and one for all Articles.
  +  <li>loading all Articles of the ProductGroup immediately after loading the ProductGroup.
  +      This is done with <b>two</b> SQL-calls: one for the ProductGroup and one for all Articles.
     </li>
  -  <li>if Article is a proxy (<A HREF="#using proxy classes">using proxy classes</A>), OJB will only load the keys of the Articles after the ProductGroup. When accessing an Article-proxy OJB will have to materialize it with another SQL-Call. Loading the ProductGroup and all it's Articles will thus produce <b>n+2</b> SQL-calls: one for the ProductGroup, one for keys of the Articles and one for each Article.</li>
  +  <li>if Article is a proxy (<A HREF="#using proxy classes">using proxy classes</A>),
  +      OJB will only load the keys of the Articles after the ProductGroup. When
  +      accessing an Article-proxy OJB will have to materialize it with another
  +      SQL-Call. Loading the ProductGroup and all it's Articles will thus produce
  +      <b>n+2</b> SQL-calls: one for the ProductGroup, one for keys of the Articles
  +      and one for each Article.</li>
     </ol>
  -  Both approaches have their benefits and drawbacks:<br/><br/>
  -  <b>A.</b> is suitable for a small number of related objects that are easily instantiated. It's efficient regarding DB-calls. The major drawback is the amount of data loaded. For example to show a list of ProductGroups the Articles may not be needed.
  +  Both approaches have their benefits and drawbacks:
     <br/><br/>
  -  <b>B.</b> is best used for a large number of related heavy objects. This solution loads the objects when they are needed (&quot;lazy loading&quot;). The price to pay is a DB-call for each object.
  +  <b>A.</b> is suitable for a small number of related objects that are easily
  +      instantiated. It's efficient regarding DB-calls. The major drawback is
  +      the amount of data loaded. For example to show a list of ProductGroups
  +      the Articles may not be needed.
  +  <br/><br/>
  +  <b>B.</b> is best used for a large number of related heavy objects. This solution
  +      loads the objects when they are needed (&quot;lazy loading&quot;). The price
  +      to pay is a DB-call for each object.
     <br/><br/>
   
  -  Further down a third solution <A HREF="#using a single proxy for a whole collection">using a single proxy for a whole collection</A> will be presented to circumvent the described drawbacks.
  +      Further down a third solution <A HREF="#using a single proxy for a whole collection">using
  +      a single proxy for a whole collection</A> will be presented to circumvent the described drawbacks.
     </p>
   
  -<subsection name="types allowed for implementing 1:n associations">
  +<subsection name="Types Allowed for Implementing 1:n Associations">
   
  -  <p>OJB supports different types to implement 1:n associations. OJB
  +  <p>OJB supports different Collection types to implement 1:n associations. OJB
     detects the used type automatically, so there is no need to declare
     it in the repository file. There is also no additional programming
     required. The following types are supported:</p>
  @@ -435,13 +451,13 @@
   </subsection>
   </section>
   
  -<section name="mapping m:n associations">
  +<section name="Mapping m:n Associations">
   
   <p>
   OJB provides support for manually decomposed m:n associations as
   well as an automated support for non decomposed m:n associations.
   </p>
  -<subsection name="Manual decomposition into two 1:n associations">
  +<subsection name="Manual Decomposition into two 1:n associations">
   <p>
   Have a look at the following class diagram:<br/><br/><br/>
   </p>
  @@ -476,7 +492,7 @@
   <p>
   This intermediary table allows to decompose the m:n association into
   two 1:n associations. The intermediary table may also hold additional
  -information. For an example the role a certain person plays for a
  +information. For example, the role a certain person plays for a
   project:
   </p>
   
  @@ -490,9 +506,9 @@
   ]]></source>
   
   <p>
  -The decomposition is mandatory on the ER model level. On the OOD
  -level it is not mandatory but may be a valid solution. It is
  -mandatory on the OOD level if the association is qualified (as in our
  +The decomposition is mandatory on the ER model level. On the object model
  +level it is not mandatory, but may be a valid solution. It is
  +mandatory on the object level if the association is qualified (as in our
   example with a rolename). This will result in the introduction of a
   association class. A class-diagram reflecting this decomposition
   looks like:<br/><br/><br/>
  @@ -509,10 +525,10 @@
   <code>Role</code> has reference attributes
   to its <code>Person</code> and to its
   <code>Project</code>.<br/>Handling of 1:n
  -mapping has been explained above. Thus I will finish this section
  -with a short look on the repository entries for the classes
  -test.ojb.broker.Person, test.ojb.broker.Project and
  -test.ojb.broker.Role:
  +mapping has been explained above. Thus we will finish this section
  +with a short look at the repository entries for the classes
  +<code>org.apache.ojb.broker.Person</code>, <code>org.apache.ojb.broker.Project</code> and
  +<code>org.apache.ojb.broker.Role</code>:
   </p>
   
   <source><![CDATA[
  @@ -619,17 +635,16 @@
   </p>
   </subsection>
   
  -<subsection name="Support for non-decomposed m:n mappings">
  +<subsection name="Support for Non-Decomposed m:n Mappings">
   <p>
  -If there is no need for an association class on the
  -OOD level (say we are not interested in role information), OJB can be
  +If there is no need for an association class at the
  +object level (we are not interested in role information), OJB can be
   configured to do the m:n mapping transparently.
  -For example a Person does not
  -have a collection of Role Objects but only a Collection of
  -<code>Project</code> objects (hold in an
  +For example, a Person does not
  +have a collection of <code>Role</code> objects but only a Collection of
  +<code>Project</code> objects (held in the
   attribute <code>projects</code>).
  -Projects
  -also are expected to contain a collection of <code>Persons</code>
  +Projects also are expected to contain a collection of <code>Person</code> objects
   (hold in attribute <code>persons</code>).
   </p>
   <p>
  @@ -713,7 +728,7 @@
      </class-descriptor>
   ]]></source>
   <p>
  -That's all that needs to be configured! See the code in class
  +That is all that needs to be configured! See the code in class
   <code>org.apache.ojb.broker.MtoNMapping</code>
   for JUnit testmethods using the classes <code>Person</code>,
   <code>Project</code> and <code>Role</code>.
  @@ -721,19 +736,19 @@
   </subsection>
   </section>
   
  -<section name="setting load-, update- and delete-cascading">
  +<section name="Setting Load, Update, and Delete Cascading">
   <p>
  -As shown in the sections on 1:1 and 1:n mappings OJB manages
  +As shown in the sections on 1:1 and 1:n mappings, OJB manages
   associations (or object references in Java terminology) by declaring
  -special Reference- and CollectionDescriptors. These Descriptor may
  +special Reference and Collection Descriptors. These Descriptor may
   contain some additional information that modifies OJB's behaviour on
  -object materialization, -updating and -deletion. If nothing is
  +object materialization, updating and deletion. If nothing is
   specified default values are assumed:</p>
   <OL>
       <LI>
         On materializing an Object from the RDBMS with
         <code>PersistenceBroker.getObjectByQuery(...)</code>all
  -      it's referenced objects (both 1:1 and 1:n associations) are
  +      its referenced objects (both 1:1 and 1:n associations) are
         materialized as well.
         (If OJB is configured to use proxies, the referenced objects are
         not materialized immmediately, but lazy loading proxy objects are used
  @@ -759,8 +774,8 @@
   </p>
   <p>
   	In the following code sample, a reference-descriptor and a collection-descriptor
  -	are configured to use cascading retrieve (<code>auto-retrieve="true"</code>),
  -	insert and update (<code>auto-update="true"</code>) and delete
  +	are configured to use cascading retrieval (<code>auto-retrieve="true"</code>),
  +	insert, and update (<code>auto-update="true"</code>) and delete
   	(<code>auto-delete="true"</code>) operations:
   </p>
   
  @@ -790,22 +805,21 @@
   
   </section>
   
  -<section name="using proxy classes">
  +<section name="Using Proxy Classes">
   <p>
   Proxy classes can be used for &quot;lazy loading&quot; aka &quot;lazy
   materialization&quot;. Using Proxy classes can help you in reducing
  -unneccessary db lookups.
  +unneccessary database lookups.
   There are two kind of proxy mechanisms available:
   <ol>
   	<li>
  -		Dynamic proxies provided by OJB.
  +		<b>Dynamic proxies</b> provided by OJB.
   		They can simply be activated by setting certain switches in repository.xml.
   		This is the solution recommemded for <b>most</b> cases.
  -		If your are in doubt use dynamic proxies.
   	</li>
   	<li>
  -		User defined proxies. They require the user to write
  -		proxy implementations
  +		<b>User defined proxies</b>. User defined proxies allow the user to write
  +		proxy implementations.
   	</li>
   </ol>
   As it is important to understand the mechanics of the proxy mechanism
  @@ -816,27 +830,28 @@
   <p>
   As a simple example we take a ProductGroup object
   <code>pg</code> which contains a collection
  -of 15 Article objects. Now we examine what happens when pg is loaded
  +of fifteen Article objects. Now we examine what happens when the ProductGroup is loaded
   from the database:
   </p>
   <p>
  -Without using proxies all 15 associated Article objects are
  +Without using proxies all fifteen associated Article objects are
   immediately loaded from the db, even if you are not interested in
  -them but just want to lookup the description-attribute of the
  -ProductGroup object pg.
  +them and just want to lookup the description-attribute of the
  +ProductGroup object.
   </p>
   <p>
  -If proxies are used, the collection is filled with 15 proxy
  +If proxies are used, the collection is filled with fifteen proxy
   objects, that implement the same interface as the &quot;real objects&quot;
  -but contain only an OID and a void reference. The 15 article objects
  -are not instantiated. Only when a method is invoked on such a proxy
  -object it loads its &quot;real subject&quot; by OID and delegates the
  +but contain only an OID and a void reference. The fifteen article objects
  +are not instantiated when the ProductGroup is initially materialized. Only
  +when a method is invoked on such a proxy
  +object will it load its &quot;real subject&quot; and delegate the
   method call to it. Using this dynamic delegation mechanism
   instantiation of persistent objects and database lookups can be
   minimized.
   </p>
   <p>
  -To use proxies the persistent class in question (in our case the
  +To use proxies, the persistent class in question (in our case the
   Article class) must implement an interface (for example
   InterfaceArticle). This interface is needed to allow replacement of
   the proper Article object with a proxy implementing the same
  @@ -910,7 +925,7 @@
   
   <p>
   The proxy is constructed from the identity of the real subject. All
  -Method calls are delegated to the object returned by
  +method calls are delegated to the object returned by
   <code>realSubject()</code>.<br/>This method
   uses getRealSubject() from the base class VirtualProxy:
   </p>
  @@ -924,7 +939,7 @@
   The proxy delegates the the materialization work to its
   <code>indirectionHandler</code>
   (<code>org.apache.ojb.broker.accesslayer.IndirectionHandler</code>).
  -If the real subject is not yet materialized, a PersistenceBroker is
  +If the real subject has not yet been materialized, a PersistenceBroker is
   used to retrieve it by its OID:
   </p>
   <source><![CDATA[
  @@ -967,7 +982,7 @@
   <br/><br/>
   </p>
   
  -<subsection name="using dynamic proxies">
  +<subsection name="Using Dynamic Proxies">
   <p>
   The implementation of a proxy class is a boring task that repeats
   the same delegation scheme for each new class. To liberate the
  @@ -977,7 +992,7 @@
   classes. Credits for this solution to ObjectMentor.) If you are
   interested in the mechanics have a look at the class
   <code>org.apache.ojb.broker.accesslayer.IndirectionHandler</code>,
  -that does all the hard work.
  +that does all of the hard work.
   </p>
   <p>
   To use a dynamic proxy for lazy materialization of Article objects
  @@ -1001,14 +1016,22 @@
   </p>
   </subsection>
   
  -<subsection name="using a single proxy for a whole collection">
  +<subsection name="Using a Single Proxy for a Whole Collection">
   <p>
  -A collection proxy represents a whole collection of objects, where as a proxy class represents a single object.<br/>
  -The advantage of this concept is a reduced number of db-calls compared to using proxy classes. A collection  proxy only needs a <b>single</b> db-call to materialize all it's objects. This happens the first time its content is accessed (ie: by calling iterator();). An additional db-call is used to calculate the size of the collection if size() is called <i>before</i> loading the data. So collection proxy is mainly used as a deferred execution of a query.
  -Have a look at class <code>ojb.broker.accesslayer.CollectionProxy</code>
  -for further details.
  -<br/><br/>
  -The following mapping shows how to use a collection proxy for a relationship:
  +    A collection proxy represents a whole collection of objects, where
  +    as a proxy class represents a single object.<br/>
  +    The advantage of this concept is a reduced number of db-calls compared
  +    to using proxy classes. A collection  proxy only needs a <b>single</b>
  +    db-call to materialize all it's objects. This happens the first time
  +    its content is accessed (ie: by calling iterator();). An additional
  +    db-call is used to calculate the size of the collection if size() is
  +    called <i>before</i> loading the data. So collection proxy is mainly
  +    used as a deferred execution of a query.
  +    Have a look at class <code>ojb.broker.accesslayer.CollectionProxy</code>
  +    for further details.
  +</p>
  +<p>
  +    The following mapping shows how to use a collection proxy for a relationship:
   </p>
   
   <source><![CDATA[
  @@ -1039,16 +1062,17 @@
   The classes participating in this relationship do not need to implement a
   special interface to be used in a collection proxy.
   <br/><br/>
  -Although it's possible to mix the collection proxy concept with the proxy class
  -concept, it's not recommended because it increases the number of db-calls.
  +Although it is possible to mix the collection proxy concept with the proxy class
  +concept, it is not recommended because it increases the number of database calls.
   </p>
   </subsection>
   
  -<subsection name="customizing collection proxy class">
  +<subsection name="Customizing a Collection Proxy Class">
   <p>
  -The optional CollectionProxy entry in <b>OJB.properties</b> defines the class to be used for CollectionProxies.
  -If this entry is null <code>org.apache.ojb.broker.accesslayer.ListProxy</code> is used for Lists
  -and <code>org.apache.ojb.broker.accesslayer.CollectionProxy</code> for Collections.
  +    The optional <code>CollectionProxy</code> entry in <b>OJB.properties</b> defines the
  +    class to be used for Collection Proxies.
  +    If this entry is null <code>org.apache.ojb.broker.accesslayer.ListProxy</code> is used for Lists
  +    and <code>org.apache.ojb.broker.accesslayer.CollectionProxy</code> for Collections.
   </p>
   
   <source><![CDATA[
  @@ -1064,14 +1088,14 @@
   
   </subsection>
   
  -<subsection name="using a proxy for a reference">
  +<subsection name="Using a Proxy for a Reference">
   <p>
   A proxy reference is based on the original proxy class concept. The main
   difference is that the ReferenceDescriptor defines when to use a proxy class and
   not the ClassDescriptor.
   <br/>
   In the following mapping the class ProductGroup is <b>not</b> defined to be a
  -proxy class in it's ClassDescriptor. Only for shown relationship a proxy of
  +proxy class in its ClassDescriptor. Only for shown relationship a proxy of
   ProductGroup should be used:
   </p>
   
  @@ -1107,41 +1131,42 @@
   </section>
   
   
  -<section name="type and value conversions">
  +<section name="Type and Value Conversions">
   <p>
   	Say your database column contains INTEGER values but you have to
  -	use boolean attributes in your Domain objects. You need a type- and
  -	value mapping described by a FieldConversion!
  -	<A HREF="jdbc-types.html">Follow this link to learn more</A>.
  +	use boolean attributes in your Domain objects. You need a type and
  +	value mapping described by a <A HREF="jdbc-types.html">FieldConversion!</A>
   </p>
   </section>
   
  -<section name="extents and polymorphism">
  -<p>Working with inheritance hierarchies is a common task in object
  -oriented design and programming. Of course any serious Java O/R tool
  -must support ineritance and interfaces for persistent classes. To see
  -how OJB does this job, I will again demonstrate some sample
  -persistent classes from the package test.ojb.broker.</p>
  -<p>There is a primary interface &quot;InterfaceArticle&quot;. This
  -interface is implemented by &quot;Article&quot; and &quot;CdArticle&quot;.
  -There is also a class &quot;BookArticle&quot; derived from &quot;Article&quot;.
  -(See the following class diagram for details)<br/><br/><br/>
  +<section name="Extents and Polymorphism">
  +<p>
  +    Working with inheritance hierarchies is a common task in object
  +    oriented design and programming. Of course, any serious Java O/R tool
  +    must support ineritance and interfaces for persistent classes. To
  +    demonstrate we will look at some of the JUnit TestSuite classes.
  +</p>
  +<p>
  +    There is a primary interface &quot;InterfaceArticle&quot;. This
  +    interface is implemented by &quot;Article&quot; and &quot;CdArticle&quot;.
  +    There is also a class &quot;BookArticle&quot; derived from &quot;Article&quot;.
  +    (See the following class diagram for details)<br/><br/><br/>
   </p>
   <p><IMG SRC="images/polymorphism.gif"/>
   <br/><br/>
   </p>
  -<subsection name="polymorphism">
  +<subsection name="Polymorphism">
   <p>
  -OJB allows to use interfaces or (possibly abstract) baseclasses in
  -queries or in type definitions of reference attributes. A Query
  -against the interface <code>InterfaceArticle</code>
  -must not only return objects of type <code>Article</code>
  -but also of <code>CdArticle</code> and
  -<code>BookArticle</code>! The following
  -test method searches for all objects implementing <code>InterfaceArticle</code>
  -with an articleName equal to &quot;Hamlet&quot;. The Collections is
  -filled with one matching <code>BookArticle
  -</code><it>object</it>.
  +    OJB allows us to use interfaces, abstract, or concrete base classes in
  +    queries, or in type definitions of reference attributes. A Query
  +    against the interface <code>InterfaceArticle</code>
  +    must not only return objects of type <code>Article</code>
  +    but also of <code>CdArticle</code> and
  +    <code>BookArticle</code>! The following
  +    test method searches for all objects implementing <code>InterfaceArticle</code>
  +    with an <code>articleName</code> equal to &quot;Hamlet&quot;. The Collection is
  +    filled with one matching <code>BookArticle
  +    </code><it>object</it>.
   </p>
   <source><![CDATA[
   public void testCollectionByQuery() throws Exception
  @@ -1160,20 +1185,19 @@
   ]]></source>
   
   <p>
  -Of course it is also possible to define reference attributes of an
  -interface or baseclass type. In all above examples Article has a
  -reference attribute of type InterfaceProductGroup.
  +    Of course it is also possible to define reference attributes of an
  +    interface or baseclass type. In all above examples Article has a
  +    reference attribute of type <code>InterfaceProductGroup</code>.
   </p>
   </subsection>
   
  -<subsection name="extents">
  +<subsection name="Extents">
   <p>
  -The query in the last example just returned one object. Now
  -imagine a query against InterfaceArticle with no selecting criteria.
  -What do you expect to happen?<br/>Right: OJB returns ALL objects
  -implementing InterfaceArticle. I.e. All Articles, BookArticles and
  -CdArticles. The following method prints out the collection of all
  -InterfaceArticle objects:
  +    The query in the last example returned just one object. Now,
  +    imagine a query against the InterfaceArticle interface with no selecting criteria.
  +    OJB returns all the objects implementing InterfaceArticle. I.e. All Articles, BookArticles and
  +    CdArticles. The following method prints out the collection of all
  +    InterfaceArticle objects:
   </p>
   <source><![CDATA[
   public void testExtentByQuery() throws Exception
  @@ -1190,11 +1214,11 @@
   }
   ]]></source>
   <p>
  -The set of all instances of a class (whether living in memory or
  -stored in a persistent medium) is called <B>Extent</B> in ODMG and
  -JDO terminology. OJB extends this notion slightly, as all objects
  -implementing a given interface are regarded as members of the
  -interfaces extent.
  +    The set of all instances of a class (whether living in memory or
  +    stored in a persistent medium) is called an <B>Extent</B> in ODMG and
  +    JDO terminology. OJB extends this notion slightly, as all objects
  +    implementing a given interface are regarded as members of the
  +    interface's extent.
   </p>
   <p>In our class diagram we find:</p>
   <OL>
  @@ -1204,9 +1228,9 @@
           <LI>An interface extent containing all Article, BookArticle and CdArticle instances.</LI>
   </OL>
   <p>
  -There is no extra coding necessary to define extents, but they
  -have to be declared in the repository file. The classes from the
  -above example require the following declarations:
  +    There is no extra coding necessary to define extents, but they
  +    have to be declared in the repository file. The classes from the
  +    above example require the following declarations:
   </p>
   <OL>
     <LI>&quot;one-class-only&quot; extents require no declaration</LI>
  @@ -1239,19 +1263,28 @@
      </class-descriptor>
   ]]></source>
   <p>
  -Why is it necessary to explicitely declare which classes implement an
  -interface and which classes are derived from a baseclass? Of course
  -it is quite simple in Java to check whether a class implements a
  -given interface or extends some other class. But sometimes it may not
  -be appropiate to treat special implementors (e.g. proxies) as proper
  -implementors. <br/>Other problems might arise because a class may
  -implement multiple interfaces, but is only allowed to be regarded as
  -member of one extent.<br/>In other cases it may be neccessary to treat
  -certain classes as implementors of an interface or as derived from a
  -base even if they are not. <br/>As an example you will find that the
  -ClassDescriptor for class org.apache.ojb.broker.Article in the
  -repository.xml contains an entry declaring class CdArticle as a
  -derived class:
  +    Why is it necessary to explicitely declare which classes implement an
  +    interface and which classes are derived from a baseclass? Of course
  +    it is quite simple in Java to check whether a class implements a
  +    given interface or extends some other class. But sometimes it may not
  +    be appropiate to treat special implementors (e.g. proxies) as proper
  +    implementors.
  +</p>
  +<p>
  +    Other problems might arise because a class may
  +    implement multiple interfaces, but is only allowed to be regarded as
  +    member of one extent.
  +</p>
  +<p>
  +    In other cases it may be neccessary to treat
  +    certain classes as implementors of an interface or as derived from a
  +    base even if they are not.
  +</p>
  +<p>
  +    As an example, you will find that the
  +    ClassDescriptor for class org.apache.ojb.broker.Article in the
  +    repository.xml contains an entry declaring class CdArticle as a
  +    derived class:
   </p>
   <source><![CDATA[
   <!-- Definitions for org.apache.ojb.ojb.broker.Article -->
  @@ -1269,21 +1302,22 @@
   </subsection>
   </section>
   
  -<section name="mapping inheritance hierarchies">
  +<section name="Mapping Inheritance Hierarchies">
   <p>
  -In the literature on object/relational mapping the
  -problem of mapping oo-inheritance hierarchies to RDBMS has been
  -widely covered. I'll give only a rough overview. Have a look at the
  -following inheritance hierarchy:<br/><br/><br/>
  +    In the literature on object/relational mapping the
  +    problem of mapping inheritance hierarchies to RDBMS has been
  +    widely covered. Have a look at the
  +    following inheritance hierarchy:<br/><br/><br/>
   </p>
   <p>
   <IMG SRC="images/inheritance-1.gif"/>
   <br/>
  -If we have to define database tables that have to contain these classes
  -we have to choose one of the following solutions:
  +    If we have to define database tables that have to contain these classes
  +    we have to choose one of the following solutions:
  +</p>
  +<p>
  +    1. Map all classes onto one table. A DDL for the table would look like:
   </p>
  -1. Map all classes onto one table. A DDL for the table would look like:
  -
   <source><![CDATA[
   CREATE TABLE A_EXTENT
   (
  @@ -1292,9 +1326,11 @@
       SOME_VALUE_FROM_B  INT
   )
   ]]></source>
  -        2. Map each class to a distinct table and have all
  -        attributes from the base class in the derived class. DDL for the
  -        table could look like:
  +<p>
  +    2. Map each class to a distinct table and have all
  +       attributes from the base class in the derived class. DDL for the
  +       table could look like:
  +</p>
   <source><![CDATA[
   CREATE TABLE A
   (
  @@ -1308,10 +1344,12 @@
       SOME_VALUE_FROM_B  INT
   )
   ]]></source>
  -        3. Map each class to a distinct table, but don't map
  -        base class fields to derived classes. Use joins to materialize over
  -        all tables to materialize objects. DDL for the table would look
  -        like:
  +<p>
  +    3. Map each class to a distinct table, but do not map
  +       base class fields to derived classes. Use joins to materialize over
  +       all tables to materialize objects. DDL for the table would look
  +       like:
  +</p>
   <source><![CDATA[
   CREATE TABLE A
   (
  @@ -1326,30 +1364,34 @@
   ]]></source>
   
   <p>
  -OJB provides direct support for all three approaches.
  -In the following I show how these mapping
  -approaches can be implemented by using OJB.
  -</p>
  -
  -<subsection name="mapping all classes on the same table">
  -<p>
  -Mapping several classes on one table works well under OJB. There is
  -only one special situation that needs some attention:
  -</p>
  -<p>
  -Say there is a baseclass AB with derived classes A and B. A and B
  -are mapped on a table AB_TABLE. Storing A and B objects to this table
  -works fine. But now consider a Query against the baseclass AB. How
  -can the correct type of the stored objects be determined? <br/>OJB
  -needs a column of type CHAR or VARCHAR that contains the classname to
  -be used for instantiation. This column must be mapped on a special
  -attribute <code>ojbConcreteClass</code>. On
  -loading objects from the table OJB checks this attribute and
  -instantiates objects of this type.<br/>
  -There is sample code for this feature in the method
  -<code>org.apache.ojb.broker.PersistenceBrokerTest.testMappingToOneTable().</code>
  -See the mapping details in the following Class
  -declaration and the respective mapping:
  +    OJB provides direct support for all three approaches.
  +    In the following we demonstrate how these mapping
  +    approaches can be implemented by using OJB.
  +</p>
  +
  +<subsection name="Mapping All Classes on the Same Table">
  +<p>
  +    Mapping several classes on one table works well under OJB. There is
  +    only one special situation that needs some attention:
  +</p>
  +<p>
  +    Say there is a baseclass AB with derived classes A and B. A and B
  +    are mapped on a table AB_TABLE. Storing A and B objects to this table
  +    works fine. But now consider a Query against the baseclass AB. How
  +    can the correct type of the stored objects be determined?
  +</p>
  +<p>
  +    OJB needs a column of type CHAR or VARCHAR that contains the classname to
  +    be used for instantiation. This column must be mapped on a special
  +    attribute <code>ojbConcreteClass</code>. On
  +    loading objects from the table OJB checks this attribute and
  +    instantiates objects of this type.
  +</p>
  +<p>
  +    There is sample code for this feature in the method
  +    <code>org.apache.ojb.broker.PersistenceBrokerTest.testMappingToOneTable().</code>
  +    See the mapping details in the following Class
  +    declaration and the respective mapping:
   </p>
   <source><![CDATA[
   public abstract class AB
  @@ -1408,14 +1450,14 @@
   	object.
   </p>
   <p>
  -	If you can't provide such an additional column, but have to
  -	use some other way of indicating the type of each object you need
  +	If you cannot provide such an additional column, but need to
  +	use some other means of indicating the type of each object you will require
   	some additional programming:
   </p>
   <p>
   	You have to derive a Class from
  -	org.apache.ojb.broker.accesslayer.RowReaderDefaultImpl and overwrite the method
  -	<code>selectClassDescriptor</code> to implement your specific type selection
  +	<code>org.apache.ojb.broker.accesslayer.RowReaderDefaultImpl</code> and overridee the method
  +	<code>RowReaderDefaultImpl.selectClassDescriptor()</code> to implement your specific type selection
   	mechanism. The code of the default implementation looks like follows:
   </p>
   <source><![CDATA[
  @@ -1462,9 +1504,9 @@
   }
   ]]></source>
   <p>
  -After implementing this Class you must edit the ClassDescriptor of
  -the respective Class in the XML repository to specify the usage of
  -your RowReader Implementation:
  +    After implementing this class you must edit the ClassDescriptor for
  +    the respective class in the XML repository to specify the usage of
  +    your RowReader Implementation:
   </p>
   <p>
   <code>row-reader="my.own.RowReaderImpl"</code>
  @@ -1475,17 +1517,18 @@
   </p>
   </subsection>
   
  -<subsection name="mapping each class on a distinct table">
  +<subsection name="Mapping Each Class to a Distinct Table">
   <p>
  -This is the most simple solution. Just write a complete
  -ClassDescriptor for each class that contains FieldDescriptors for all
  -(also inherited) attributes.
  +    This is the most simple solution. Just write a complete
  +    ClassDescriptor for each class that contains FieldDescriptors for all
  +    of the attributes, including inherited attributes.
   </p>
   </subsection>
   
  -<subsection name="mapping classes on multiple joined tables">
  +<subsection name="Mapping Classes on Multiple Joined Tables">
   <p>
   Here are the definitions for the classes A and B:
  +</p>
   <source><![CDATA[
   public class A
   {
  @@ -1551,12 +1594,13 @@
   
      </class-descriptor>
   ]]></source>
  -
  +<p>
   As you can see from this mapping we need a special reference-descriptor
   that advises OJB to load the values for the inherited
   attributes from class <code>A</code> by a JOIN using the
  -<code>(B.id == A.id)</code> foreign key reference.<br/>
  -
  +<code>(B.id == A.id)</code> foreign key reference.
  +</p>
  +<p>
   The <code>name="super"</code> is not used to address an actual
   attribute of the class <code>B</code> but as a marker
   keyword defining the JOIN to the baseclass.
  @@ -1565,10 +1609,12 @@
   The above example is based on the assumption that the primary key attribute
   <code>B.id</code> and its underlying column <code>B_TABLE.ID</code>
   is also used as the foreign key attribute.
  -<br/>
  -Now let's consider a case where <code>B_TABLE</code> contains an additional
  +</p>
  +<p>
  +Now let us consider a case where <code>B_TABLE</code> contains an additional
   foreign key column <code>B_TABLE.A_ID</code> referencing <code>A_TABLE.ID</code>.
   In this case the layout for class <code>B</code> could look like follows:
  +</p>
   <source><![CDATA[
   public class B extends A
   {
  @@ -1616,16 +1662,20 @@
   
      </class-descriptor>
   ]]></source>
  -The mapping now contains an additional field-descriptor for the
  -<code>aID</code> attribute.<br/>
  -In the <code>"super"</code> reference-descriptor the foreignkey <code>field-ref</code> attribute
  -had to be changed to <code>"aID"</code>.
  +<p>
  +    The mapping now contains an additional field-descriptor for the
  +    <code>aID</code> attribute.
  +</p>
  +<p>
  +    In the <code>"super"</code> reference-descriptor the foreignkey <code>field-ref</code> attribute
  +    had to be changed to <code>"aID"</code>.
   </p>
   
   <p>
  -It's also possible to have the extra
  -foreign key column <code>B_TABLE.A_ID</code> but without having a
  -foreign key attribute in class <code>B</code>:
  +    It is also possible to have the extra
  +    foreign key column <code>B_TABLE.A_ID</code> but without having a
  +    foreign key attribute in class <code>B</code>:
  +</p>
   <source><![CDATA[
   public class B extends A
   {
  @@ -1636,7 +1686,7 @@
       int someValueFromB;
   }
   ]]></source>
  -
  +<p>
   We can use OJB's anonymous field feature to get everything working without the
   <code>"aID"</code> attribute. We keep the field-descriptor for aID, but declare it as an
   anonymous field.
  @@ -1682,7 +1732,7 @@
   
   </section>
   
  -<section name="using rowreaders">
  +<section name="Using Rowreaders">
   <p>
   RowReaders provide a Callback mechanism that allows to interact
   with the OJB load mechanism. To understand how to use them we must
  @@ -1694,7 +1744,7 @@
   from queries against the Database.
   </p>
   <p>
  -The RsIterator.next() is used to materialize the next object from
  +The <code>RsIterator.next()</code> is used to materialize the next object from
   the underlying ResultSet. This method first checks if the underlying
   ResultSet is not yet exhausted and then delegates the construction of
   an Object from the current ResultSet row to the method
  @@ -1790,10 +1840,6 @@
   
   }
   ]]></source>
  -
  -
  -
  -
   <p>
   	In the second step OJB checks if there is
   	already a cached version of the object to materialize.
  @@ -1821,9 +1867,9 @@
   	materialization process and	provide additional features.
   </p>
   
  -<subsection name="rowreader example">
  +<subsection name="Rowreader Example">
   <p>
  -	Assume that for some reason we don't want to map a 1:1 association
  +	Assume that for some reason we do not want to map a 1:1 association
   	with a foreign key relationship to a different database table but
   	read the associated object 'inline' from some columns of the master
   	object's table. This approach is also called 'nested objects'.
  @@ -1881,13 +1927,13 @@
   
   </section>
   
  -<section name="nested objects">
  +<section name="Nested Objects">
   <p>
   	In the last section we discussed the usage of a user written RowReader
   	to implement nested objects. This approach has several disadvantages.
   	<ol>
   		<li>
  -			It's necessary to write code and to have some understanding of OJB
  +			It is necessary to write code and to have some understanding of OJB
   			internals.
   		</li>
   		<li>
  @@ -1895,7 +1941,7 @@
   			to the database on store.
   		</li>
   	</ol>
  -	In this section I show that nested objects can be implemented without
  +	This section shows that nested objects can be implemented without
   	writing code, and without any further trouble just by a few settings
   	in the repository.xml file.
   </p>
  @@ -2010,18 +2056,19 @@
   </p>
   </section>
   
  -<section name="instance callbacks">
  +<section name="Instance Callbacks">
   <p>
  -	OJB does provide transparent persistence. That is persistent classes don't
  +	OJB does provide transparent persistence. That is, persistent classes do not
   	need to implement an interface or extent a persistent baseclass.
  -	<br/>
  +</p>
  +<p>
   	For certain situations it may be neccesary to allow persistent instances to
  -	interact with OJB though. This is supported by a simple instance callback mechanism.
  -	<br/>
  +	interact with OJB. This is supported by a simple instance callback mechanism.
  +</p>
  +<p>
   	The interface <code>org.apache.ojb.PersistenceBrokerAware</code>
   	provides a set of methods that are invoked from the PersistenceBroker
   	during operations on persistent instances:
  -	<br/>
   </p>
   <source><![CDATA[
   public interface PersistenceBrokerAware
  @@ -2229,9 +2276,10 @@
   
   <section name="Customizing collection queries">
   <p>
  -Customizing the query used for collection retrieval allows a <b>developer</b> to take
  -full control of collection mechanism. For example only children having a certain attribute
  -should be loaded. This is achieved by a QueryCustomizer defined in the collection-descriptor of a relationship:
  +    Customizing the query used for collection retrieval allows a <b>developer</b> to take
  +    full control of collection mechanism. For example only children having a certain attribute
  +    should be loaded. This is achieved by a QueryCustomizer defined in the collection-descriptor
  +    of a relationship:
   </p>
   
   <source><![CDATA[
  @@ -2253,7 +2301,8 @@
   ]]></source>
   
   <p>
  -The query customizer must implement the interface <code>org.apache.ojb.broker.accesslayer.QueryCustomizer</code>.
  +The query customizer must implement the interface
  +    <code>org.apache.ojb.broker.accesslayer.QueryCustomizer</code>.
   This interface defines the single method below which is used to customize (or completely rebuild) the query
   passed as argument. The interpretation of  attribute-name and attribute-value read from the
   collection-descriptor is up to your implementation.
  
  
  
  1.12      +15 -13    db-ojb/xdocs/tutorial4.xml
  
  Index: tutorial4.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/xdocs/tutorial4.xml,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- tutorial4.xml	30 Mar 2003 20:35:09 -0000	1.11
  +++ tutorial4.xml	7 Aug 2003 22:50:58 -0000	1.12
  @@ -14,7 +14,7 @@
   <subsection name="Introduction">
   
   <p>
  -  This document demonstrates how to use ObjectRelationalBridge an the JDO API
  +  This document demonstrates how to use ObjectRelationalBridge and the JDO API
     in a simple application scenario. The tutorial application implements a
     product catalog database with some basic use cases. The source code for the
     tutorial application is shipped with the OJB source distribution and resides
  @@ -22,7 +22,7 @@
   </p>
   <p>
     The application scenario and the overall architecture have been introduced
  -  in the <A HREF="tutorial1.html">first part of this tutorial</A> and won't be
  +  in the <A HREF="tutorial1.html">first part of this tutorial</A> and will not be
     repeated here. The only modifications to the <code>org.apache.ojb.tutorial1</code>
     source code are due to the usage of the JDO Api for persistence operations.
     The present document explains these modifications.
  @@ -73,7 +73,7 @@
   </subsection>
   </section>
   
  -<section name="Using the JDO API in the UseCase implementations">
  +<section name="Using the JDO API in the UseCase Implementations">
   
   <p>
   In the <A HREF="tutorial1.html">first tutorial</A> you learned
  @@ -82,7 +82,7 @@
   </p>
   <p>
   	The first tutorial implemented the sample
  -	applications use cases with the PersistenceBroker API. This tutorial
  +	application's use cases with the PersistenceBroker API. This tutorial
   	will show how the same use cases can be implemented using the JDO
   	API.
   </p>
  @@ -97,13 +97,16 @@
   deal with a special facade object that serves as the main entry point
   to all JDO operations. This facade is specified by the Interface
   <code>javax.jdo.PersistenceManager.</code>
  -
  -A Vendor of an JDO compliant product must provide a specific
  +</p>
  +<p>
  +A Vendor of a JDO compliant product must provide a specific
   implementation of the <code>javax.jdo.PersistenceManager</code>
   interface. JDO also specifies that a JDO implementation must provide a
   <code>javax.jdo.PersistenceManagerFactory</code> implementation that is
   responsible for generating <code>javax.jdo.PersistenceManager</code>
   instances.
  +</p>
  +<p>
   So if you know how to use the JDO API you only have to learn how to obtain
   the OJB specific PersistenceManagerFactory object. Ideally this will be
   the only vendor specific operation.
  @@ -233,23 +236,22 @@
   
   <subsection name="Storing objects">
   <p>
  -	Now we'll have a look at the use case <code>UCEnterNewProduct</code>.
  +	Now we will have a look at the use case <code>UCEnterNewProduct</code>.
   	It works as follows: first create a new object, then ask the user for
   	the new product's data (productname, price and available stock).
  -	These data is stored in the new objects attributes. This part is not
  -	different from the tutorial1 implementation. (Step 1. and 2.)
  +	These data is stored in the new object's attributes. This part is no
  +	different from the <a href="tutorial1.html">tutorial1</a> implementation. (Steps 1. and 2.)
   </p>
   <p>
  -	But now we must store the newly created object in the persistent
  -	store by means of the JDO API. With JDO all persistence operations
  +	Now we will store the newly created object in the persistent
  +	store by means of the JDO API. With JDO, all persistence operations
   	must happen within a transaction. So the third step is to ask the
   	PersistenceManager object for a fresh <code>javax.jdo.Transaction</code>
   	object to work with. The <code>begin()</code>
   	method starts the transaction.
   </p>
   <p>
  -	We then have to ask the PersistenceManager to make the object persistent.
  -	This is done in step four.
  +	We then have to ask the PersistenceManager to make the object persistent in step 4.
   </p>
   <p>
   	In the last step we commit the transaction. All changes to objects
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: ojb-dev-unsubscribe@db.apache.org
For additional commands, e-mail: ojb-dev-help@db.apache.org


Mime
View raw message