db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From arm...@apache.org
Subject svn commit: r562151 - in /db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs: ./ docu/guides/ docu/tutorials/
Date Thu, 02 Aug 2007 15:51:55 GMT
Author: arminw
Date: Thu Aug  2 08:51:54 2007
New Revision: 562151

URL: http://svn.apache.org/viewvc?view=rev&rev=562151
Log:
update docs

Modified:
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/basic-technique.xml
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/odmg-guide.xml
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/pb-guide.xml
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/site.xml

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/basic-technique.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/basic-technique.xml?view=diff&rev=562151&r1=562150&r2=562151
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/basic-technique.xml
(original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/basic-technique.xml
Thu Aug  2 08:51:54 2007
@@ -1297,121 +1297,206 @@
 
         <anchor id="using-proxy"/>
         <section>
-            <title>Using Proxy Classes</title>
+            <title>Lazy Loading via Proxy Classes</title>
             <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 database lookups.
                 <br/>
-                There are two kind of proxy mechanisms available:
+                There are three kind of proxy mechanisms available:
             </p>
             <ol>
                 <li>
-                    <strong>Dynamic proxies</strong> provided by OJB.
-                    They can simply be activated by setting certain switches in repository.xml.
-                    This is the solution recommemded for
-                    <strong>most</strong> cases.
+                    <strong>Dynamic proxies</strong> provided by OJB and external
libraries.
+                    They can simply be activated by setting certain switches in
+                    <a href="site:repository">repository file</a>. Replaces a
persistent object by
+                    a proxy object.
                 </li>
                 <li>
                     <strong>User defined proxies</strong>. User defined proxies
allow the user to write
-                    proxy implementations.
+                    proxy implementations. Replaces a persistent object by
+                    a proxy object.
+                </li>
+                <li>
+                    <strong>Proxy references</strong>. Replacement of referenced
objects (1:1, 1:n, m:n)
+                    by a proxy placeholder. Replaces a whole reference by a proxy object.
                 </li>
             </ol>
             <p>
-                As it is important to understand the mechanics of the proxy mechanism
-                I highly recommend to read this section before turning to the next sections
-                "using dynamic proxies", "using a single proxy for a whole collection" and
-                "using a proxy for a reference", covering dynamic proxies.
-            </p>
-            <p>
-                As a simple example we take a ProductGroup object
+                As a simple example we take a <code>ProductGroup</code> object
                 <code>pg</code> which contains a collection
-                of fifteen Article objects. Now we examine what happens when the ProductGroup
is loaded
-                from the database:
-            </p>
-            <p>
-                Without using proxies all fifteen associated Article objects are
-                immediately loaded from the db, even if you are not interested in
-                them and just want to lookup the description-attribute of the
-                ProductGroup object.
-            </p>
-            <p>
-                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 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
-                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
-                interface. Have a look at the code:
+                of fifteen <code>Article</code> objects. Now we examine what
happens when the
+                <code>ProductGroup</code> is loaded from the database:
             </p>
+            <ul>
+                <li>
+                    <p>
+                        <em>Without using proxies</em> - all fifteen associated
Article objects are
+                        immediately loaded from the db, even if you are not interested in
+                        them and just want to lookup the description-attribute of the
+                        ProductGroup object.
+                    </p>
+                </li>
+                <li>
+                    <p>
+                        <em>Use proxies for the referenced objects</em> - the
collection is filled
+                        with fifteen proxy objects, that contain only an OID and a void reference.
+                        The fifteen <code>Article</code> objects are not instantiated
when the
+                        <code>ProductGroup</code> is initially materialized.
+                        <br/>
+                        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>
+                </li>
+                <li>
+                    <p>
+                        <em>Replace the reference by a proxy object</em> - the
whole collection
+                        (1:n and  m:n references) or single reference (1:1) is replaced by
a single
+                        proxy object and fully materialized on the first reference access.
+                        <br/>
+                        This is the recommended way (in most cases) to realize lazy
+                        loading for references (1:1, 1:n and m:n).
+                    </p>
+                </li>
+            </ul>
+
+            <note>
+                In most cases the best performance results in using
+                <a href="#reference-proxy">a proxy for referenced objects</a>.
+                <br/>
+                Only in specific cases the use
+                of proxies for persistence capable classes (<a href="#dynamic-proxy">dynamic</a>
or
+                <a href="#user-defined-proxy">user defined</a> proxies) are useful.
+            </note>
+
+            <anchor id="dynamic-proxy"/>
+            <section>
+                <title>Dynamic Proxies for persistence capable objects</title>
+                <p>
+                    The implementation of a proxy class is a boring task that repeats
+                    the same delegation scheme for each new class. To liberate the
+                    developer from this unproductive job OJB provides a dynamic proxy
+                    solution based on the JDK 1.3 dynamic proxy concept.
+                    <br/>
+                    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>
+
+                <anchor id="dynamic-proxy-jdk"/>
+                <section>
+                    <title>Dynamic Proxies with JDK standard proxies</title>
+                    <p>
+                        To use a dynamic proxy for lazy materialization of <code>Article</code>
objects
+                        we have to declare it in the repository.xml file.
+                    </p>
+                <source><![CDATA[
+    <class-descriptor
+      class="org.apache.ojb.broker.Article"
+      proxy="dynamic"
+      table="Artikel"
+    >
+    ...]]></source>
+
+                <p>
+                    Just as with standard JDK proxies, the persistent class in question (in
our case
+                    the <code>Article</code> class) must implement an interface
with all getter/setter methods
+                    (for example <code>InterfaceArticle</code>) to be able to
benefit from dynamic proxies.
+                </p>
+                </section>
+
+                <anchor id="dynamic-proxy-cglib"/>
+                <section>
+                    <title>Dynamic Proxies with CGLib</title>
+                    <p>
+                        When using <a href="#cglib-proxies">CGLib</a> for proxy
generation the declaration
+                        is the same as above:
+                    </p>
+                    <source><![CDATA[
+    <class-descriptor
+      class="org.apache.ojb.broker.Article"
+      proxy="dynamic"
+      table="Artikel"
+    >
+    ...]]></source>
+                    <p>
+                        But <a href="#cglib-proxies">CGLib based proxies</a>
<strong>don't require an
+                        interface</strong> for the persistent class in question. So
we can use class
+                        <code>Article</code> without any modification.
+                    </p>
+                </section>
+
+                <p>
+                    The proxy generation implementation classes (standard JDK or CGLib) can
easily be
+                    switched - see section:
+                    <a href="#proxy-customization">customize the proxy generation implementation</a>
+                </p>
+            </section>
+
+            <anchor id="user-defined-proxy"/>
+            <section>
+                <title>User defined proxies for persistence capable objects</title>
+                <p>
+                    To use standard JDK proxies for the referenced objects, the persistent
class in question
+                    (in our case the <code>Article</code> class) must implement
an interface (for example
+                    <code>InterfaceArticle</code>). This interface is needed
to allow replacement of
+                    the proper Article object with a proxy implementing the same
+                    interface. Have a look at the code:
+                </p>
 
             <source><![CDATA[
-    public class Article implements InterfaceArticle
-    {
-        /** maps to db-column "Artikel-Nr"; PrimaryKey*/
-        protected int articleId;
-        /** maps to db-column "Artikelname"*/
-        protected String articleName;
-        ...
-
-        public int getArticleId()
-        {
-            return articleId;
-        }
-
-        public java.lang.String getArticleName()
-        {
-            return articleName;
-        }
-        ...
-    }
+public class Article implements InterfaceArticle
+{
+    protected int articleId;
+    protected String articleName;
+    ...
+    public int getArticleId()
+    {return articleId;}
 
-    public interface InterfaceArticle
-    {
-        public int getArticleId();
-        public java.lang.String getArticleName();
-        ...
-    }]]></source>
-            <p>
+    public String getArticleName()
+    {return articleName;}
+    ...
+}
 
+public interface InterfaceArticle
+{
+    public int getArticleId();
+    public String getArticleName();
+    ...
+}]]></source>
+            <p>
+                Now we have to create the proxy implementation class itself. OJB expects
that all
+                user defined proxy classes are sub-classes of
+                <code>org.apache.ojb.broker.core.proxy.VirtualProxy</code>:
             </p>
             <source><![CDATA[
 public class ArticleProxy extends VirtualProxy implements InterfaceArticle
 {
     public ArticleProxy(ojb.broker.Identity uniqueId, PersistenceBroker broker)
-    {
-        super(uniqueId, broker);
-    }
+    {super(uniqueId, broker);}
 
     public int getArticleId()
-    {
-        return realSubject().getArticleId();
-    }
+    {return realSubject().getArticleId();}
 
-    public java.lang.String getArticleName()
-    {
-        return realSubject().getArticleName();
-    }
+    public String getArticleName()
+    {return realSubject().getArticleName();}
 
     private InterfaceArticle realSubject()
     {
         try
-        {
-            return (InterfaceArticle) getRealSubject();
-        }
+        {return (InterfaceArticle) getRealSubject();}
         catch (Exception e)
-        {
-            return null;
-        }
+        {return null;}
     }
 }]]></source>
             <p>
@@ -1422,31 +1507,27 @@
                 uses getRealSubject() from the base class VirtualProxy:
             </p>
             <source><![CDATA[
-    public Object getRealSubject() throws PersistenceBrokerException
-    {
-        return indirectionHandler.getRealSubject();
-    }]]></source>
+public Object getRealSubject() throws PersistenceBrokerException
+{
+    return indirectionHandler.getRealSubject();
+}]]></source>
             <p>
                 The proxy delegates the the materialization work to its
                 <code>IndirectionHandler</code>.
-                If the real subject has not yet been materialized, a PersistenceBroker is
used to retrieve it by its OID:
+                If the real subject has not yet been materialized, a PersistenceBroker is
+                used to retrieve it by its OID:
             </p>
             <source><![CDATA[
-    public synchronized Object getRealSubject()
-                        throws PersistenceBrokerException
-    {
-        if (realSubject == null)
-        {
-            materializeSubject();
-        }
-        return realSubject;
-    }
+public synchronized Object getRealSubject() throws PersistenceBrokerException
+{
+    if (realSubject == null) materializeSubject();
+    return realSubject;
+}
 
-    private void materializeSubject()
-                        throws PersistenceBrokerException
-    {
-        realSubject = broker.getObjectByIdentity(id);
-    }]]></source>
+private void materializeSubject() throws PersistenceBrokerException
+{
+    realSubject = broker.getObjectByIdentity(id);
+}]]></source>
             <p>
                 To tell OJB to use proxy objects instead of materializing full
                 Article objects we have to add the following section to the XML
@@ -1466,68 +1547,20 @@
             <p>
                 <img src="images/proxies.gif" alt="proxy image"/>
             </p>
+            </section>
 
-            <anchor id="dynamic-proxy"/>
+
+            <anchor id="reference-proxy"/>
             <section>
-                <title>Using Dynamic Proxies</title>
-                <p>
-                    The implementation of a proxy class is a boring task that repeats
-                    the same delegation scheme for each new class. To liberate the
-                    developer from this unproductive job OJB provides a dynamic proxy
-                    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.)
-                    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>
+                <title>Proxy for referenced objects</title>
                 <p>
-                    To use a dynamic proxy for lazy materialization of Article objects
-                    we have to declare it in the repository.xml file.
+                    Beside proxies for persistence capable classes, OJB supports proxies
for
+                    a referenced object (1:1 reference) or collection (1:n, m:n reference):
                 </p>
-                <source><![CDATA[
-    <class-descriptor
-      class="org.apache.ojb.broker.Article"
-      proxy="dynamic"
-      table="Artikel"
-    >
-    ...]]></source>
-
-                <p>
-                    Just as with normal proxies, the persistent class in question (in our
case
-                    the Article class) must implement an interface (for example
-                    InterfaceArticle) to be able to benefit from dynamic proxies.
-                </p>
-                <note>
-                	As of OJB 1.0.4, a facility is now present to allow the generation of
-                	dynamic proxies that <strong>do not</strong> require the persistent
class
-                	to implement an interface. Previous versions generated Proxies using the
JDK
-                	proxy pattern. That has been extracted into a new configuration setting
named
-                	'ProxyFactoryClass'.
-                	<br/><br/>
-                	Two implementations of this ProxyClass have been provided: the previous
JDK-based version (default),
-                	and a new CGLIB-based implementation. Since the CGLIB version does byte-code
-                	manipulation to generate the proxy, your class is not required to implement
any
-                	interface. All generated Proxies will automatically be sub-classes of your
-                	persistent class.
-                	<br/><br/>
-                	See below in the section "Customizing the proxy mechanism" for how to enable
the new
-                	CGLIB Proxy generation.
-
-                </note>
-            </section>
 
             <anchor id="collection-proxy"/>
             <section>
-                <title>Using a Single Proxy for a Whole Collection</title>
+                <title>Proxy for a whole Collection (1:n, m:n references)</title>
                 <p>
                     A collection proxy represents a whole collection of objects, where
                     as a proxy class represents a single object.
@@ -1610,18 +1643,19 @@
                 </p>
             </section>
 
-            <anchor id="reference-proxy"/>
+            <anchor id="single-reference-proxy"/>
             <section>
-                <title>Using a Proxy for a Reference</title>
+                <title>Proxy for a 1:1 reference</title>
                 <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.
+                    A proxy reference is based on OJB's original <a href="#using-proxy">proxy
class concept</a>
+                    for a persistence capable object.
+                    The main difference is that the <a href="site:repository/reference-descriptor">reference-descriptor</a>
+                    defines when to use a proxy class and not the
+                    <a href="site:repository/class-descriptor">class-descriptor</a>.
                     <br/>
-                    In the following mapping the class ProductGroup is
-                    <strong>not</strong> defined to be a
-                    proxy class in its ClassDescriptor. Only for shown relationship a proxy
of
-                    ProductGroup should be used:
+                    In the following mapping the class <code>ProductGroup</code>
is
+                    <strong>not</strong> defined to be a proxy class in its class-descriptor.
+                    Only for the shown relationship a proxy of ProductGroup is used:
                 </p>
 
                 <source><![CDATA[
@@ -1639,9 +1673,9 @@
           />
           ...
           <reference-descriptor
-             name="productGroup"
-             class-ref="org.apache.ojb.broker.ProductGroup"
-         proxy="true"
+            name="productGroup"
+            class-ref="org.apache.ojb.broker.ProductGroup"
+            proxy="true"
           >
              <foreignkey field-ref="productGroupId"/>
           </reference-descriptor>
@@ -1649,10 +1683,51 @@
 
                 <p>
                     Because a proxy reference is only about the location of the definition,
the
-                    referenced class must implement a special interface (see
-                    <a href="#using-proxy">using proxy classes</a>).
+                    referenced class must implement a special interface if
+                    <a href="#dynamic-proxy-jdk">standard JDK proxies</a>
+                    are used (<a href="#cglib-proxies">CGLib based proxies</a>
do not need this).
+                </p>
+            </section>
+            </section>
+
+
+            <anchor id="cglib-proxies"/>
+            <section>
+                <title>CGLib advantages and requirements</title>
+                <p>
+                    Since version 1.0.4 OJB supports <a href="ext:cglib">CGLib</a>
based proxy generation and since
+                    version 1.0.5 this library is used as default proxy generation library.
+                    <br/>
+                    The advantages are:
+                </p>
+                <ul>
+                    <li>
+                        CGLib can generate proxy objects for all classes. Since the CGLib
version does
+                        byte-code manipulation to generate the proxy, your class is not required
to implement any
+                        interface. All generated Proxies will automatically be sub-classes
of your
+                        persistent class.
+                    </li>
+                    <li>
+                        The performance of CGLib proxies is very good and often outperform
the standard JDK proxies.
+                    </li>
+                </ul>
+                <p>
+                    The requirements are:
+                </p>
+                <ul>
+                    <li>
+                        Final declared persistence capable classes are not allowed.
+                    </li>
+                    <li>
+                        Final methods in persistence capable classes are not allowed.
+                    </li>
+                </ul>
+                <p>
+                    In <a href="site:ojb-properties">OJB's configuration file</a>
you can
+                    <a href="#proxy-customization">customize the proxy generation classes</a>.
                 </p>
             </section>
+
 
             <anchor id="proxy-customization"/>
             <section>

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/odmg-guide.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/odmg-guide.xml?view=diff&rev=562151&r1=562150&r2=562151
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/odmg-guide.xml
(original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/odmg-guide.xml
Thu Aug  2 08:51:54 2007
@@ -215,8 +215,62 @@
         <section>
             <title>Object State Detection</title>
             <p>
-                !!!TODO
+                The ODMG-API implementation supports "persistence by reachability" for all
locked objects (object locking
+                can be done by hand or let OJB handle it - see <a href="#locks">implicit
locking</a>). To realise this
+                feature OJB use object state detection based on in-memory copies of object
fields to find modfied
+                objects. For all locked objects OJB take a snapshot.
+                <br/>
+                So it's recommended to avoid large query results or to disable the implicit
locking (permanent via
+                <a href="#configuration">OJB.properties setting</a> or <a
href="#extImplicitLocking">at runtime</a>).
             </p>
+            <p>
+                If persistence capable objects with big memory footprint are used the copy
based state detection
+                cause memory overhead and slow down the performance. In this case it can
be useful to
+                disable the object state detection for this classes/fields and
+                <a href="#markDirty">mark changed objects by hand</a>.
+            </p>
+            <p>
+                OJB support three different flags:
+            </p>
+            <ul>
+                <li>
+                    StateDetection.ON
+                    <br/>
+                    State detection is enabled.
+                </li>
+                <li>
+                    StateDetection.OFF
+                    <br/>
+                    State detection is disabled.
+                </li>
+                <li>
+                    StateDetection.INHERIT
+                    <br/>
+                    State detection status will be inherited from a higher level entity.
+                </li>
+            </ul>
+            <p>
+                OJB allows fine grained state-detection declaration in the following elements
of the
+                <a href="site:repository">metadata mapping file</a>:
+            </p>
+            <ul>
+                <li>
+                    In the <a href="site:repository/descriptor-repository">descriptor-repository</a>
+                    to enable/disable state-detection for all mapped classes.
+                </li>
+                <li>
+                    In the <a href="site:repository/class-descriptor">class-descriptor</a>
+                    to enable/disable state-detection for a specific class.
+                </li>
+                <li>
+                    In the <a href="site:repository/field-descriptor">field-descriptor</a>
+                    to enable/disable state-detection for a specific field of a class.
+                </li>
+            </ul>
+            <note>
+                If <em>state-detection</em> is disabled the user is responsible
to mark changed
+                objects as dirty - see <a href="#markDirty">mark changed objects by
hand</a>.
+            </note>
         </section>
 
 
@@ -543,6 +597,7 @@
                         <a href="ext:odmg-transaction-ext">TransactionExt</a>.
                     </li>
                     <li>
+                        <anchor id="markDirty"/>
                         markDirty
                         <br/>
                         Description can be found in javadoc of
@@ -555,6 +610,7 @@
                         <a href="ext:odmg-transaction-ext">TransactionExt</a>.
                     </li>
                     <li>
+                        <anchor id="extImplicitLocking"/>
                         is/setImplicitLocking
                         <br/>
                         Description can be found in javadoc of
@@ -664,6 +720,7 @@
                 </p>
             </section>
 
+            <anchor id="locks"/>
             <section>
                 <title>Locks</title>
                 <p>

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/pb-guide.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/pb-guide.xml?view=diff&rev=562151&r1=562150&r2=562151
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/pb-guide.xml
(original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/pb-guide.xml
Thu Aug  2 08:51:54 2007
@@ -157,6 +157,43 @@
         <anchor id="questions"/>
         <section>
             <title>Questions</title>
+            
+            <anchor id="plain-store"/>
+            <section>
+                <title>How to update/insert an object without cascading the whole object
graph (referenced objects)</title>
+                <p>
+                    The PB-api supports an extended store method to suppress the cascading
update/insert of
+                    referenced objects (e.g. via 1:1, 1:n or m:n reference) independent from
the settings
+                    made in the <a href="site:repository">repository mapping file</a>:
+                </p>
+                <source><![CDATA[
+/**
+ * Makes the given object persistent in the underlying persistence system.
+ * This is usually done by issuing an INSERT ... or UPDATE ...  in an RDBMS.
+ *
+ * @param obj The object to store
+ * @param modification Specifies what operation to perform (for generating optimized SQL)
+ * @param ignoreReferences If set <em>true</em> OJB will ignore all referenced
objects
+ * and only insert/update the fields of the object.
+ */
+public void store(Object obj, ObjectModification modification, boolean ignoreReferences)
+]]></source>
+                <p>
+                    In the example below only the <code>Article</code> object
will be updated, OJB completely
+                    ignore the referenced objects.
+                </p>
+                <source><![CDATA[
+...
+article.setPrice(0.99);
+article.getProductGroup().setName("test");
+broker.store(article, ObjectModification.UPDATE, true);
+...
+]]></source>
+                <p>
+                    So the name change in <code>ProductGroup</code> will <strong>not</strong>
take effect
+                    only the new price of the article object will be persisted.
+                </p>
+            </section>
 
             <anchor id="multiple-databases"/>
             <section>
@@ -271,8 +308,7 @@
                     run.
                 </p>
                 <source><![CDATA[
-brokerLeakDetection=true
-                ]]></source>
+brokerLeakDetection=true]]></source>
                 <note>
                     The leak detection is costly, so take care to disable this property in
production environments.
                 </note>

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml?view=diff&rev=562151&r1=562150&r2=562151
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml
(original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml
Thu Aug  2 08:51:54 2007
@@ -255,8 +255,10 @@
                     </p>
                     <p>
                         The <em>state-detection</em> attribute is used by API's
supporting automatic state detection
-                        of persistence capable objects. The attribute indicate whether or
not mapped classes should
-                        be included in object state detection (automatic detection of changed
object fields).
+                        of persistence capable objects (automatic detection of changed object
fields - e.g. like the
+                        <a href="site:odmg-guide">ODMG implementation</a>).
+                        The attribute indicate whether or not the object state detection
is enabled for all
+                        mapped classes.
                     </p>
                         <source><![CDATA[
 <!ATTLIST descriptor-repository
@@ -264,7 +266,7 @@
 	isolation-level (read-uncommitted | read-committed | repeatable-read |
 	                 serializable | optimistic | none) "read-uncommitted"
 	proxy-prefetching-limit CDATA "50"
-	state-detection (true | false) "true"
+	state-detection (on | off) "on"
 >]]></source>
                 </section>
             </section>
@@ -1355,10 +1357,10 @@
                 </p>
                 <p>
                     The <em>state-detection</em> attribute is used by API's supporting
automatic state detection
-                    of persistence capable objects (e.g. odmg-api implementation does). The
attribute indicate
-                    whether or not this class should be included in object state detection
(automatic detection
-                    of changed object fields). If <em>state-detection</em> is
generally disabled, this setting
-                    will (normally) be ignored.
+                    of persistence capable objects (automatic detection of changed object
fields - e.g. like the
+                    <a href="site:odmg-guide">ODMG implementation</a>).
+                    The attribute indicate whether or not the object state detection is enabled
for this class
+	                or if it's inherited from a higher level entity.
                 </p>
                 <p>
                     The <em>field-class</em> attribute can be used to override
the
@@ -1382,7 +1384,7 @@
 	factory-class CDATA #IMPLIED
 	factory-method CDATA #IMPLIED
 	refresh (true | false) "false"
-	state-detection CDATA #IMPLIED
+	state-detection (on | off | inherit) "inherit"
 	field-class CDATA #IMPLIED
 >]]></source>
             </section>
@@ -1506,7 +1508,7 @@
                 </p>
                 <anchor id="null-check"/>
                 <p>
-                    The optional <em>null-check</em> attribute (since OJB 1.0.5)
should
+                    The optional <em>null-check</em> attribute (since OJB 1.0.5)
must
                     contain a fully qualified class name or a valid shortcut name.
                     This class must implement the interface
                     <code>org.apache.ojb.broker.accesslayer.NullCheck</code>.
@@ -1560,11 +1562,10 @@
                 </p>
                 <p>
                     The <em>state-detection</em> attribute is used by API's supporting
automatic state detection
-                    of persistence capable objects. The attribute indicate whether or not
this field should
-                    be included in object state detection (automatic detection of changed
object fields).
-                    If in the <em>state-detection</em> is generally disabled
or in the associated
-                    <a href="site:repository/class-descriptor">class-descriptor</a>,
this setting will (normally)
-                    be ignored.
+                    of persistence capable objects (automatic detection of changed object
fields - e.g. like the
+                    <a href="site:odmg-guide">ODMG implementation</a>).
+                    The attribute indicate whether or not the object state detection is enabled
for this field
+	                or if it's inherited from a higher level entity.
                 </p>
                 <p>
                     The <em>field-class</em> attribute can be used to override
the
@@ -1596,7 +1597,7 @@
 	precision CDATA #IMPLIED
 	scale CDATA #IMPLIED
 	access (readonly | readwrite | anonymous) "readwrite"
-	state-detection CDATA #IMPLIED
+	state-detection (on | off | inherit) "inherit"
 	field-class CDATA #IMPLIED
 >]]></source>
             </section>

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml?view=diff&rev=562151&r1=562150&r2=562151
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml
(original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml
Thu Aug  2 08:51:54 2007
@@ -403,7 +403,7 @@
             result.setStock(new Integer(result.getStock().intValue() - 1));
             broker.store(result);
             // alternative, more performant
-            // broker.store(result, ObjectModificationDefaultImpl.UPDATE);
+            // broker.store(result, ObjectModification.UPDATE);
             broker.commitTransaction();
             isSold = true;
         }
@@ -570,5 +570,9 @@
                 </p>
             </section>
 
+        <p>
+            That's all! Now we recommend to read the <a href="site:pb-guide">PB-guide</a>
for more detailed
+            information about the PB-api.
+        </p>
     </body>
 </document>

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewvc/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/site.xml?view=diff&rev=562151&r1=562150&r2=562151
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/site.xml
(original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/site.xml
Thu Aug  2 08:51:54 2007
@@ -467,6 +467,7 @@
         <spring href="http://www.springframework.org/"/>
         <linguine-maps href="http://www.softwaresecretweapons.com/jspwiki/Wiki.jsp?page=LinguineMaps"/>
         <clepsydra href="http://clepsydra.javaforge.com/"/>
+        <cglib href="http://cglib.sourceforge.net/"/>
 
 
         <!-- Article links used within OJB -->
@@ -475,7 +476,6 @@
             <spring-ojb-part-2 href="http://staff.osuosl.org/~mckerrj/?p=4"/>
             <spring-ojb-part-3 href="http://staff.osuosl.org/~mckerrj/?p=8"/>
             <springframework-and-ojb href="http://blogs.codepuccino.com/dude/index.php?p=23"/>
-            <cglib-pitfall href="http://blog.springframework.com/rob/archives/2005/08/18/caveats-with-class-proxying-in-spring/"/>
         </article>
     </external-refs>
 </site>



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