You are viewing a plain text version of this content. The canonical link for it is here.
Posted to ojb-dev@db.apache.org by to...@apache.org on 2004/05/09 13:10:07 UTC
cvs commit: db-ojb/forrest/src/documentation/content/xdocs/docu basic-technique.xml
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