db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From to...@apache.org
Subject cvs commit: db-ojb/forrest/src/documentation/content/xdocs/docu basic-technique.xml
Date Sun, 09 May 2004 11:10:07 GMT
tomdz       2004/05/09 04:10:07

  Modified:    forrest/src/documentation/content/xdocs/docu
                        basic-technique.xml
  Log:
  Added proxy customization stuff
  
  Revision  Changes    Path
  1.5       +112 -39   db-ojb/forrest/src/documentation/content/xdocs/docu/basic-technique.xml
  
  Index: basic-technique.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/docu/basic-technique.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- basic-technique.xml	5 May 2004 13:15:30 -0000	1.4
  +++ basic-technique.xml	9 May 2004 11:10:07 -0000	1.5
  @@ -1376,10 +1376,17 @@
                       solution based on the JDK 1.3 dynamic proxy concept. (For JDK1.2 we
                       ship a replacement for the required
                       <code>java.lang.reflect</code>
  -                    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.core.proxy.IndirectionHandler</code>,
  -                    that does all of the hard work.
  +                    classes. Credits for this solution to ObjectMentor.)
  +                    The basic idea of the dynamic proxy concept is to catch all method
  +                    invocations on the not-yet materialized (loaded from database) object.
  +                    When a method is called on the object, Java directs this call to the
  +                    invocation handler registered for it (in OJB's case a class implementing
  +                    the <code>org.apache.ojb.broker.core.proxy.IndirectionHandler</code>
  +                    interface). This handler then materializes the object from the
  +                    database and replaces the proxy with the real object.
  +                    By default OJB uses the class
  +                    <code>org.apache.ojb.broker.core.proxy.IndirectionHandlerDefaultImpl</code>.
  +                    If you are interested in the mechanics have a look at this class.
                   </p>
                   <p>
                       To use a dynamic proxy for lazy materialization of Article objects
  @@ -1394,15 +1401,13 @@
       ...]]></source>
   
                   <p>
  -                    To use dynamic proxies the persistent class in question (in our case
  +                    Just as with normal 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 dynamic proxy implementing the same
  -                    interface.
  +                    InterfaceArticle) to be able to benefit from dynamic proxies.
                   </p>
               </section>
   
  -            <anchor id="single-proxy"/>
  +            <anchor id="collection-proxy"/>
               <section>
                   <title>Using a Single Proxy for a Whole Collection</title>
                   <p>
  @@ -1418,9 +1423,38 @@
                       called
                       <em>before</em> 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>
  +                    OJB uses three specific proxy classes for collections:
  +                </p>
  +	            <ol>
  +	                <li>
  +	                    <strong>List proxies</strong> are specific <code>java.util.List</code>
  +                        implementations that are used by OJB to replace lists. The default
  +                        set proxy class is
  +                        <code>org.apache.ojb.broker.core.proxy.ListProxyDefaultImpl</code>
  +                        
  +	                </li>
  +	                <li>
  +                        <strong>Set proxies</strong> are specific <code>java.util.Set</code>
  +                        implementations that are used by OJB to replace sets. The default
  +                        set proxy class is
  +                        <code>org.apache.ojb.broker.core.proxy.SetProxyDefaultImpl</code>
  +	                </li>
  +                    <li>
  +                        <strong>Collection proxies</strong> are collection
classes
  +                        implementing the more generic <code>java.util.Collection</code>
  +                        interface and are used if the collection is neither a list nor
a set.
  +                        The default collection proxy class is
  +                        <code>org.apache.ojb.broker.core.proxy.CollectionProxyDefaultImpl</code>
  +                    </li>
  +	            </ol>
  +                <p>
  +                    Which of these proxy class is actually used, is determined by the
  +                    <code>collection-class</code> setting of this collection.
If none is
  +                    specified in the repository descriptor, or if the specified class does
  +                    not implement <code>java.util.List</code> nor <code>java.util.Set</code>,
  +                    then the generic collection proxy is used.
                   </p>
                   <p>
                       The following mapping shows how to use a collection proxy for a relationship:
  @@ -1458,31 +1492,7 @@
                   </p>
               </section>
   
  -            <anchor id="collection-proxy"/>
  -            <section>
  -                <title>Customizing a Collection Proxy Class</title>
  -                <p>
  -                    The optional
  -                    <code>CollectionProxy</code> entry in
  -                    <strong>OJB.properties</strong> defines the
  -                    class to be used for Collection Proxies.
  -                    If this entry is null
  -                    <code>org.apache.ojb.broker.core.proxy.ListProxy</code>
is used for Lists
  -                    and
  -                    <code>org.apache.ojb.broker.core.proxy.CollectionProxy</code>
for Collections.
  -                </p>
  -                <source><![CDATA[
  -    ...
  -    #-----------------------------------------------
  -    # CollectionProxy class
  -    #-----------------------------------------------
  -    #
  -    #CollectionProxyClass=
  -    #
  -    ...]]></source>
  -
  -            </section>
  -
  +            <anchor id="reference-proxy"/>
               <section>
                   <title>Using a Proxy for a Reference</title>
                   <p>
  @@ -1525,8 +1535,71 @@
                       <link href="#using-proxy">using proxy classes</link>).
                   </p>
               </section>
  -        </section>
   
  +            <anchor id="proxy-customization"/>
  +            <section>
  +                <title>Customizing the proxy mechanism</title>
  +                <p>
  +                    Both the dynamic and the collection proxy mechanism can be customized
by
  +                    supplying a user-defined implementation.
  +                </p>
  +                <p>
  +                    For dynamic proxies you can provide your own invocation handler which
  +                    implements the
  +                    <code>org.apache.ojb.broker.core.proxy.IndirectionHandler</code>
  +                    interface. See OJB's default implementation
  +                    <code>org.apache.ojb.broker.core.proxy.IndirectionHandlerDefaultImpl</code>
  +                    for details on how to implement such an invocation handler.
  +                </p>
  +                <p>
  +                    Each of the three collection proxy classes can be replaced by a
  +                    user-defined class. The only requirement is that such a class
  +                    implements both the corresponding interface (<code>java.util.Collection</code>,
  +                    <code>java.util.List</code>, or <code>java.util.Set</code>)
as well as
  +                    the <code>org.apache.ojb.broker.ManageableCollection</code>
  +                    interface.
  +                </p>
  +                <p>
  +                    Proxy implementations are configured in the ojb properties file. These
  +                    are the relevant settings:
  +                </p>
  +                <source><![CDATA[
  +    ...
  +	#----------------------------------------------------------------------------------------
  +	# IndirectionHandler
  +	#----------------------------------------------------------------------------------------
  +	# The IndirectionHandlerClass entry defines the class to be used by OJB's proxies to
  +	# handle method invocations
  +	#
  +	IndirectionHandlerClass=org.apache.ojb.broker.core.proxy.IndirectionHandlerDefaultImpl
  +	#
  +	#----------------------------------------------------------------------------------------
  +	# ListProxy
  +	#----------------------------------------------------------------------------------------
  +	# The ListProxyClass entry defines the proxy class to be used for collections that
  +	# implement the java.util.List interface.
  +	#
  +	ListProxyClass=org.apache.ojb.broker.core.proxy.ListProxyDefaultImpl
  +	#
  +	#----------------------------------------------------------------------------------------
  +	# SetProxy
  +	#----------------------------------------------------------------------------------------
  +	# The SetProxyClass entry defines the proxy class to be used for collections that
  +	# implement the java.util.Set interface.
  +	#
  +	SetProxyClass=org.apache.ojb.broker.core.proxy.SetProxyDefaultImpl
  +	#
  +	#----------------------------------------------------------------------------------------
  +	# CollectionProxy
  +	#----------------------------------------------------------------------------------------
  +	# The CollectionProxyClass entry defines the proxy class to be used for collections that
  +	# do not implement java.util.List or java.util.Set.
  +	#
  +	CollectionProxyClass=org.apache.ojb.broker.core.proxy.CollectionProxyDefaultImpl
  +    ...]]></source>
  +
  +            </section>
  +        </section>
   
           <section>
               <title>Type and Value Conversions</title>
  
  
  

---------------------------------------------------------------------
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