Return-Path: <brj@apache.org>
Mailing-List: contact ojb-dev-help@db.apache.org; run by ezmlm
Delivered-To: mailing list ojb-dev@db.apache.org
Received: (qmail 35804 invoked by uid 500); 3 Mar 2003 20:08:50 -0000
Received: (qmail 35801 invoked from network); 3 Mar 2003 20:08:50 -0000
Received: from icarus.apache.org (208.185.179.13)
  by daedalus.apache.org with SMTP; 3 Mar 2003 20:08:50 -0000
Received: (qmail 24021 invoked by uid 1513); 3 Mar 2003 20:08:50 -0000
Date: 3 Mar 2003 20:08:50 -0000
Message-ID: <20030303200850.24020.qmail@icarus.apache.org>
From: brj@apache.org
To: db-ojb-cvs@apache.org
Subject: cvs commit: db-ojb/xdocs features.xml tutorial3.xml
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N

brj         2003/03/03 12:08:50

  Modified:    xdocs    features.xml tutorial3.xml
  Log:
  description of QueryCustomizer
  
  Revision  Changes    Path
  1.8       +2 -0      db-ojb/xdocs/features.xml
  
  Index: features.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/xdocs/features.xml,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- features.xml	27 Aug 2002 06:43:38 -0000	1.7
  +++ features.xml	3 Mar 2003 20:08:49 -0000	1.8
  @@ -25,6 +25,8 @@
       <li>Mapping support for 1:1, 1:n and m:n <a href="tutorial3.html#mapping 1:1 associations">
         associations</a>.
       </li>
  +    <li>Configurable collection queries to control loading of relationships. See <a href="tutorial3.html#Customizing collection queries"> QueryCustomizer</a>.
  +    </li>
       <li>Automatic assignment of foreign key values.</li>
       <li>
         The Object / Relational mapping is defined in an XML Repository. The
  
  
  
  1.17      +50 -0     db-ojb/xdocs/tutorial3.xml
  
  Index: tutorial3.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/xdocs/tutorial3.xml,v
  retrieving revision 1.16
  retrieving revision 1.17
  diff -u -r1.16 -r1.17
  --- tutorial3.xml	6 Jan 2003 14:09:20 -0000	1.16
  +++ tutorial3.xml	3 Mar 2003 20:08:49 -0000	1.17
  @@ -77,6 +77,9 @@
     <li>
     	<A HREF="#instance callbacks">instance callbacks</A>
     </li>
  +  <li>
  +  	<A HREF="#Customizing collection queries">customizing collection queries</A>
  +  </li>
   </ul>
   
   </subsection>
  @@ -1853,8 +1856,55 @@
   }
   ]]></source>
   
  +</section>
  +
  +<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:
  +</p>
  +
  +<source><![CDATA[
  +     <collection-descriptor
  +         name="allArticlesInGroup"
  +		 ...
  +     >
  +         <inverse-foreignkey field-ref="productGroupId"/>
  +
  +         <query-customizer
  +         	class="org.apache.ojb.broker.accesslayer.QueryCustomizerDefaultImpl">
  +          <attribute
  +            attribute-name="attr1"
  +            attribute-value="value1"
  +          />
  +         </query-customizer>
   
  +      </collection-descriptor>
  +]]></source>
  + 
  +<p>
  +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.
  +</p>
  +
  +<source><![CDATA[
  +   /**
  +    * Return a new Query based on the original Query, the originator object and
  +    * the additional Attributes
  +    *
  +    * @param anObject the originator object
  +    * @param aBroker the PersistenceBroker
  +    * @param aCod the CollectionDescriptor
  +    * @param aQuery the original 1:n-Query
  +    * @return Query the customized 1:n-Query
  +    */
  +   public Query customizeQuery(Object anObject, PersistenceBroker aBroker, CollectionDescriptor aCod, Query aQuery); 
  +]]></source>
  + 
  +<p>
  +The class <code>org.apache.ojb.broker.accesslayer.QueryCustomizerDefaultImpl</code> provides a default implentation without any functionality, it simply returns the query.
  +</p> 
  + 
   </section>
  +
   
   </body>
   </document>