db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From arm...@apache.org
Subject svn commit: r386233 [1/2] - in /db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs: ./ docu/ docu/guides/ docu/tutorials/
Date Thu, 16 Mar 2006 01:20:11 GMT
Author: arminw
Date: Wed Mar 15 17:20:09 2006
New Revision: 386233

URL: http://svn.apache.org/viewcvs?rev=386233&view=rev
Log:
update and add new documentation

Modified:
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/getting-started.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/performance.xml
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/platforms.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/guides/sequencemanager.xml
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/jdo-tutorial.xml
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.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/index.xml
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/site.xml
    db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/status.xml

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml
URL: http://svn.apache.org/viewcvs/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml?rev=386233&r1=386232&r2=386233&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/faq.xml Wed Mar 15 17:20:09 2006
@@ -15,11 +15,11 @@
   limitations under the License.
 -->
 <!-- @version $Id$ -->
-<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.2//EN" "http://apache.org/forrest/dtd/faq-v12.dtd">
+<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V2.0//EN" "faq-v20.dtd">
 
-<faqs title="Frequently Asked Questions">
-
-    <part id="General">
+<faqs>
+    <title>Frequently Asked Questions</title>
+    <faqsection id="General">
         <title>General</title>
         <faq id="whyOJB">
             <question>
@@ -129,20 +129,20 @@
                         app-server scenarios.
                         <br/>
                         This API can also be used directly by applications that don't need full
-                        fledged object level transactions (see <link href="site:pb-tutorial">PB tutorial</link> for details).
+                        fledged object level transactions (see <a href="site:pb-tutorial">PB tutorial</a> for details).
                     </li>
 
                     <li>
                         An Object Transaction Manager (OTM) layer that contains all features that
                         JDO and ODMG have in common as Object level transactions, lock-management,
-                        instance lifecyle etc. (See <link href="site:otm-tutorial">OTM tutorial</link> for details.)
+                        instance lifecyle etc. (See <a href="site:otm-tutorial">OTM tutorial</a> for details.)
                         The OTM is work in progress.
                     </li>
 
                     <li>
                         A full featured
                         <strong>ODMG 3.0</strong> compliant API. (See
-                        <link href="site:odmg-tutorial">ODMG tutorial</link> for an introduction.)
+                        <a href="site:odmg-tutorial">ODMG tutorial</a> for an introduction.)
                         <br/> Currently this API is implemented on top the PersistenceBroker. Once the
                         OTM layer is finished ODMG will be implemented on top of OTM.
                     </li>
@@ -150,7 +150,7 @@
                     <li>
                         A
                         <strong>JDO</strong> compliant API. This is work in progress.
-                        (See <link href="site:jdo-tutorial">JDO tutorial</link> for an introduction.)
+                        (See <a href="site:jdo-tutorial">JDO tutorial</a> for an introduction.)
                         <br/> Currently this API is implemented on top the PersistenceBroker. Once the
                         OTM layer is finished JDO will be implemented on top of OTM.
                     </li>
@@ -175,7 +175,7 @@
             <answer>
                 <p>
                     OJB has a "pattern driven" design.
-                    <link href="site:links/design">Please refer to this document for more details</link>
+                    <a href="site:links/design">Please refer to this document for more details</a>
                 </p>
             </answer>
         </faq>
@@ -186,7 +186,7 @@
             </question>
             <answer>
                 <p>
-                    <link href="site:links/more-or">We have a link list pointing to further readings.</link>
+                    <a href="site:links/more-or">We have a link list pointing to further readings.</a>
                 </p>
             </answer>
         </faq>
@@ -197,7 +197,7 @@
             </question>
             <answer>
                 <p>
-                    See page <link href="site:performance">Performance</link>.
+                    See page <a href="site:performance">Performance</a>.
                 </p>
             </answer>
         </faq>
@@ -208,7 +208,7 @@
             </question>
             <answer>
                 <p>
-                    See page <link href="site:performance">Performance</link>.
+                    See page <a href="site:performance">Performance</a>.
                 </p>
             </answer>
         </faq>
@@ -236,7 +236,7 @@
                     We provide a regression test suite for Quality Assurance. You can use this testsuite to check if
                     OJB works smoothly in your target environment.
                     (see
-                    <link href="site:platform">supported platforms documentation</link>)
+                    <a href="site:platform">supported platforms documentation</a>)
                     <br/>
                     <br/>
 
@@ -244,19 +244,19 @@
                     This test will give you an impression of the performance impact OJB will have in your target
                     environment.
                     (see
-                    <link href="site:performance">Performance testsuite documentation</link>)
+                    <a href="site:performance">Performance testsuite documentation</a>)
                     <br/>
                     <br/>
 
                     OJB is also the persistence layer of choice in several books on
                     programming J2EE based enterprise business systems.
                     (see
-                    <link href="site:links">our links and references section</link>)
+                    <a href="site:links">our links and references section</a>)
                     <br/>
                     <br/>
 
                     Reference projects and user testimonials are listed
-                    <link href="site:references">here.</link>
+                    <a href="site:references">here.</a>
                 </p>
             </answer>
         </faq>
@@ -268,14 +268,14 @@
             <answer>
                 <p>
                     Short answer is yes. To get a detailed answer, please read the
-                    <link href="site:object-cache">caching guide</link>.
+                    <a href="site:object-cache">caching guide</a>.
                 </p>
             </answer>
         </faq>
-    </part>
+    </faqsection>
 
 
-    <part id="gettingStarted">
+    <faqsection id="gettingStarted">
         <title>Getting Started</title>
         <faq id="installingProblems">
             <question>
@@ -284,7 +284,7 @@
             <answer>
                 <p>
                     Please read the
-                    <link href="site:getting-started">Getting Started</link> document. OJB is a
+                    <a href="site:getting-started">Getting Started</a> document. OJB is a
                     powerful and complex system - installing and configuring OJB is not a trivial task.
                     Be sure to follow <strong>all the steps</strong> mentioned in that document - don't skip any steps
                     when first installing OJB on your systems.
@@ -292,9 +292,9 @@
                 <p>
                     If you are having problems running OJB against your target database, read the
                     respective
-                    <link href="site:platform">platform documentation</link>.  Before you
+                    <a href="site:platform">platform documentation</a>.  Before you
                     try to deploy OJB to your environment, read the
-                    <link href="site:deployment">deployment guide</link>.
+                    <a href="site:deployment">deployment guide</a>.
                 </p>
             </answer>
         </faq>
@@ -339,7 +339,7 @@
                     you configure to make OJB connect to your database. Starting with your
                     application side, all that is needed is to use the interface you wish. I
                     use ODMG because JDO is not complete yet. Here's a
-                    <link href="site:odmg-tutorial">link to the ODMG part</link>
+                    <a href="site:odmg-tutorial">link to the ODMG part</a>
                     with some code for examples.
                     <br/>
                     That's all you need on the application side. Next there's the configuration
@@ -380,7 +380,7 @@
                 </p>
                 <p>
                     The final thing to do is to make sure the OJB core tables are in your
-                    database. Look on this page for <link href="site:platform">the core tables</link>. These core tables are used by
+                    database. Look on this page for <a href="site:platform">the core tables</a>. These core tables are used by
                     OJB to store internal data while it's running. It needs these. Then there's
                     the tables you define. The ones you mapped in the repository_user.xml file.
                 </p>
@@ -400,9 +400,9 @@
             </question>
             <answer>
                 <p>
-                    If you carefully attended the <link href="#installingProblems">installing hints</link>
+                    If you carefully attended the <a href="#installingProblems">installing hints</a>
                     there may be something wrong with your metadata mapping defined in the
-                    <link href="ext:repository.xml">repository file</link> or one the included sub files.
+                    <a href="ext:repository.xml">repository file</a> or one the included sub files.
                 </p>
                 <ul>
                     <li>Are you included all configuration files in classpath?</li>
@@ -417,7 +417,7 @@
                 </p>
                 <note>
                     If OJB default logging was used, change entries for these classes in
-                    <link href="ext:ojb.properties">OJB.properties</link> file (this may change in future).
+                    <a href="ext:ojb.properties">OJB.properties</a> file (this may change in future).
                 </note>
             </answer>
         </faq>
@@ -428,7 +428,7 @@
             </question>
             <answer>
                 <p>
-                    <link href="site:platform">please refer to this document</link>.
+                    <a href="site:platform">please refer to this document</a>.
                 </p>
             </answer>
         </faq>
@@ -439,7 +439,7 @@
             </question>
             <answer>
                 <p>
-                    <link href="site:platform">Please refer to this document</link>.
+                    <a href="site:platform">Please refer to this document</a>.
                 </p>
             </answer>
         </faq>
@@ -461,14 +461,14 @@
             </question>
             <answer>
                 <p>
-                    <link href="site:large-metadata">Please refer to this document</link>.
+                    <a href="site:large-metadata">Please refer to this document</a>.
                 </p>
             </answer>
         </faq>
-    </part>
+    </faqsection>
 
 
-    <part id="apis">
+    <faqsection id="apis">
         <title>OJB APIs</title>
         <faq id="differencesBetweenAPI">
             <question>
@@ -477,30 +477,32 @@
             </question>
             <answer>
                 <p>
-                    The PersistenceBroker (PB) provides a minimal API for transparent
+                    The <a href="site:pb-guide">PersistenceBroker (PB)</a> provides a minimal API for transparent
                     persistence:
                 </p>
                 <ul>
                     <li>O/R mapping</li>
-                    <li>Retrieval of objects with a simple query interface from RDBMS</li>
+                    <li>Retrieval of objects with a criteria based query interface from RDBMS</li>
                     <li>storing (insert, update) of objects to RDBMS</li>
                     <li>deleting of objects from RDBMS</li>
                 </ul>
 
-                <p>This is all you need for simple applications as in tutorial1.</p>
+                <p>This is all you need for simple applications as shown in
+                    <a href="site:pb-tutorial">tutorial</a>.</p>
                 <p>
-                    The OJB ODMG implementation uses the PB as its persistence kernel.
+                    The <a href="site:odmg-guide">OJB ODMG</a> implementation uses the
+                    PersistenceBroker layer as its persistence kernel.
                     But it provides much more functionality to the application developer.
                     ODMG is a full fledged API for Object Persistence, including:
                 </p>
                 <ul>
                     <li>OQL Query interface</li>
-                    <li>real Object Transactions</li>
+                    <li>Object state detection, automatic detection of new/deleted objects ("unit of work")</li>
                     <li>
-                        A Locking Mechanism for management of concurrent threads (apps)
-                        accessing the same objects
+                        A locking mechanism (based on OJB's <a href="site:lock-manager">locking-api</a>)
+                        for management of concurrent threads (apps) accessing the same objects
                     </li>
-                    <li>predefined persistent capable Collections and Hashtables</li>
+                    <li>Named Objects</li>
                 </ul>
 
                 <p>
@@ -508,44 +510,78 @@
                 </p>
                 <ol>
                     <li>
-                        Say you use the PB to query an object O that has a collection
-                        attribute col with five elements a,b,c,d,e. Next you delete Objects
-                        d and e from col and store O again with
-                        PersistenceBroker.store(O);
-                        <br/>
-                        PB will store the remaining objects a,b,c. But it will not delete d and
-                        e ! If you then requery object O it will again contain a,b,c,d,e !!!
-                        <br/>
-                        The PB keeps no transactional state of the persistent Objects, thus it
-                        does not know that d and e have to be deleted. (as a side note: deletion
-                        of d and e could also be an error, as there might be references to them
-                        from other objects !!!)
-                        <br/>
-                        Using ODMG for the above scenario will eliminate all trouble: Objects
-                        are registered to a transaction so that on commit of the transaction it
-                        knows that d and e do not longer belong to the collection. the ODMG
-                        collection will not delete the objects d and e but only the REFERENCES
-                        from the collection to those objects!
-                    </li>
-                    <li>
-                        Say you have two threads (applications) that try to access
-                        and modify the same object O. The PB has no means to check whether
-                        objects are used by concurrent threads. Thus it has no locking
-                        facilities. You can get all kind of trouble by this situation. The
-                        ODMG implementation has a Lockmanager that is capable of
-                        synchronizing concurrent threads. You can even use four transaction
-                        isolation levels:
-                        <br/>read-uncommitted, read-committed,
-                        repeatable-read, serializable.
+                        <p>
+                            Say you use the PB to query an object 'O' that has a collection
+                            attribute 'col' with five elements a,b,c,d,e. Next you delete Objects
+                            d and e from col and store O again with
+                            <br/>
+                            <code>PersistenceBroker.store(O);</code>
+                            <br/>
+                            The PB instance has no object state detection, thus it update all
+                            specified objects. So the unchanged object O will be updated and
+                            dependend on the used <a href="site:basic-technique/cascading">reference settings</a>
+                            (cascading update enabled or not) the remaining objects a,b,c be updated too.
+                            Again dependend on the used settings
+                            (<a href="site:advanced-technique/which-collection-type">collection types</a>)
+                            the deleted objects d and e can be detected by the PB and removed from the datastore.
+                            <br/>
+                            The PB keeps no transactional state of the persistence capable objects, thus it
+                            does not know that only d and e have to be deleted. In this case the user
+                            have to take care of object management and should remove both objects
+                            d, e from the collection and then delete both objects itself (as a side note: deletion
+                            of d and e could also be an error, as there might be references to them
+                            from other objects !!!):
+                            <br/>
+                            <code>PersistenceBroker.delete(d);</code>
+                            <br/>
+                            <code>PersistenceBroker.delete(e);</code>
+                        </p>
+                        <p>
+                            Using ODMG for the above scenario will eliminate all trouble: Objects
+                            have to be locked/registered to a transaction before any modification is done,
+                            so that on transaction commit OJB knows that d and e do not longer
+                            belong to the collection. OJB will dependend on the used
+                            <a href="site:odmg-guide/metadata">reference metadata setting</a> delete the
+                            objects d and e from the datastore or only the REFERENCES from the
+                            collection to those objects! All other unmodified registered objects will
+                            be ignored on commit.
+                        </p>
+                    </li>
+                    <li>
+                        <p>
+                            Say you have two threads (applications) that try to access
+                            and modify the same object 'O'. The PB has no opportunity to check whether
+                            objects are used by concurrent threads, because it has no (automatic)
+                            pessimistic locking facilities (alternative
+                            <a href="site:lock-manager/optimistic-locking">optimistic locking</a>
+                            is supported by all API's). So you can get all kind of trouble by
+                            this situation.
+                        </p>
+                        <p>
+                            The ODMG implementation has a build in <em>Lockmanager</em> that is capable of
+                            synchronizing access to objects by concurrent threads.
+                        </p>
+                        <p>
+                            By the way it's possible to use OJB's
+                            <a href="site:lock-manager/pessimistic-locking">pessimistic locking api</a>
+                            by your own + PB-api.
+                        </p>
                     </li>
                 </ol>
 
                 <p>
-                    In my eyes the PB is a persistence kernel that can be used to
-                    build high-level PersistenceManagers like an ODMG or JDO
-                    implementation. It can also be used to write simple applications, but
-                    you have to do all management things (locking, tracking objects
-                    state, object transactions) on your own.
+                    In my eyes the PB can be used to write applications for small projects
+                    (accept some overhead caused by absence of object state detection) and
+                    if you do all management things (locking if needed, tracking objects state)
+                    on  your own it can be used as persistence layer for all kind of projects
+                    or proprietary O/R mapper.
+                    <br/>
+                    Therefore OJB use the PB-api as persistence kernel to
+                    build the high-level PersistenceManagers like ODMG and JDO.
+                </p>
+                <p>
+                    It is also possible to use
+                    <a href="site:odmg-guide/pb-access">both API's in the same application</a>. 
                 </p>
             </answer>
         </faq>
@@ -556,7 +592,7 @@
             </question>
             <answer>
                 <p>
-                    Please refer to the <link href="site:odmg-guide/no-oql">ODMG-guide</link>.
+                    Please refer to the <a href="site:odmg-guide/no-oql">ODMG-guide</a>.
                 </p>
             </answer>
         </faq>
@@ -616,10 +652,10 @@
                 </p>
             </answer>
         </faq>
-    </part>
+    </faqsection>
 
 
-    <part id="howto">
+    <faqsection id="howto">
         <title>Howto</title>
         <faq id="withRDBMS">
             <question>
@@ -627,7 +663,7 @@
             </question>
             <answer>
                 <p>
-                    <link href="site:platform">please refer to this document</link>.
+                    <a href="site:platform">please refer to this document</a>.
                 </p>
             </answer>
         </faq>
@@ -650,7 +686,7 @@
                 	    it once you're done.</li>
                 </ul>
                 <p>
-                    See <link href="site:deployment">deployment doc</link> for more information.
+                    See <a href="site:deployment">deployment doc</a> for more information.
                 </p>
             </answer>
         </faq>
@@ -661,7 +697,7 @@
             </question>
             <answer>
                 <p>
-                    See <link href="site:performance">performance section</link>.
+                    See <a href="site:performance">performance section</a>.
                 </p>
             </answer>
         </faq>
@@ -706,8 +742,8 @@
                         The returned Iterator is lazy and does not materialize Objects in
                         advance. Objects are only materialized if you call the Iterators
                         next() method. Thus you have total control about when and how many
-                        Objects get materialized! Please see <link href="#itOrCol">here for
-                        proper handling</link>.
+                        Objects get materialized! Please see <a href="#itOrCol">here for
+                        proper handling</a>.
                     </li>
                     <li>
                         You can define Proxy Objects as placeholder for your
@@ -719,7 +755,7 @@
                         are accessed directly. Thus you can build similar lazy paging as
                         with the Iterator. You will find examples in the OJB test suite
                         (src-distribution only: [db-ojb]/src/test). More info about
-                        <link href="site:basic-technique/using-proxy">Proxy object here</link>.
+                        <a href="site:basic-technique/using-proxy">Proxy object here</a>.
                     </li>
                 </ol>
                 <p>
@@ -760,8 +796,8 @@
                 </p>
                 <p>
                     have a look at section
-                    <link href="site:basic-technique/using-proxy">proxy usage</link> of page
-                    <link href="site:basic-technique">basic technique</link>.
+                    <a href="site:basic-technique/using-proxy">proxy usage</a> of page
+                    <a href="site:basic-technique">basic technique</a>.
                 </p>
             </answer>
         </faq>
@@ -777,7 +813,7 @@
                 </p>
                 <p>
                     OJB provides a concept of ConversionStrategies that can be used for such
-                    conversion tasks. <link href="site:jdbc-types">Have a look at the respective document</link>.
+                    conversion tasks. <a href="site:jdbc-types">Have a look at the respective document</a>.
                 </p>
             </answer>
         </faq>
@@ -788,14 +824,14 @@
             </question>
             <answer>
                 <p>
-                    OJB  ships with out of the box support for <link href="ext:p6spy">P6Spy</link>.
+                    OJB  ships with out of the box support for <a href="ext:p6spy">P6Spy</a>.
                     P6Spy is a JDBC proxy which delegates all JDBC calls to the
                     real JDBC driver and traces all calls to a log file.
                 </p>
                 <p>
                     P6Spy is contained in the p6spy.jar, which you'll find in the <code>lib</code>
                     folder of your OJB distribution. Add this to the classpath of your app
-                    (if you're using the <link href="site:getting-started">ojb-blank</link>
+                    (if you're using the <a href="site:getting-started">ojb-blank</a>
                     project, then simply copy the jar into the <code>lib</code> folder of the project
                     and if you're using Eclipse then also add it to the project build path).
                 </p>
@@ -853,8 +889,8 @@
                 </p>
                 <p>
                     Please refer to
-                    <link href="site:basic-technique">basic technique</link> and
-                    <link href="site:repository">xml-metadata repository</link> for details.
+                    <a href="site:basic-technique">basic technique</a> and
+                    <a href="site:repository">xml-metadata repository</a> for details.
                 </p>
             </answer>
         </faq>
@@ -869,7 +905,7 @@
                     Primitive values (int, long, ...) can't be <code>null</code>, so OJB interpret '0' as <code>null</code>
                     for primitive PK/FK fields in persistent objects. Thus primitive PK fields of persistent objects should
                     never be represented by a '0' value in DB and never used as a
-                    <link href="site:sequence-manager">sequence key</link> value.
+                    <a href="site:sequence-manager">sequence key</a> value.
                     <br/>
                     This is only true for primitive PK/FK fields (e.g. <code>Integer(0)</code> is allowed).
                     All other fields have 'normal' behavior.
@@ -884,7 +920,7 @@
             </question>
             <answer>
                 <p>
-                    Please see <link href="site:pb-tutorial/find-by-pk">PB tutorial section</link>.
+                    Please see <a href="site:pb-tutorial/find-by-pk">PB tutorial section</a>.
                 </p>
             </answer>
         </faq>
@@ -985,7 +1021,7 @@
                         of
                         <code>myClass</code> in repository.xml.
                         Follow the steps in
-                        <link href="site:basic-technique">basic technique</link> on 1:n and m:n.
+                        <a href="site:basic-technique">basic technique</a> on 1:n and m:n.
                     </li>
                 </ul>
 
@@ -998,7 +1034,7 @@
             </question>
             <answer>
                 <p>
-                    Please refer to <link href="site:pb-guide/lookup-pb">PB-guide</link>.
+                    Please refer to <a href="site:pb-guide/lookup-pb">PB-guide</a>.
                 </p>
             </answer>
         </faq>
@@ -1010,7 +1046,7 @@
             </question>
             <answer>
                 <p>
-                    Please refer to <link href="site:odmg-guide/lookup-odmg">ODMG-guide</link>.
+                    Please refer to <a href="site:odmg-guide/lookup-odmg">ODMG-guide</a>.
                 </p>
             </answer>
         </faq>
@@ -1025,7 +1061,7 @@
                     There is no need to put user/password in the repository file (more exact in the
                     <code>jdbc-connection-descriptor</code>). You can pass this
                     information at runtime. See
-                    <link href="#differentDBUsers">Many different database user - How do they login?</link>.
+                    <a href="#differentDBUsers">Many different database user - How do they login?</a>.
                 </p>
                 <p>
                     Only if you want to use convenience
@@ -1033,14 +1069,14 @@
                     of
                     <code>PersistenceBrokerFactory</code>, OJB needs
                     all database connection information in the configuration files. More details see
-                    <link href="site:repository">repository file doc - section jdbc-connection-descriptor
+                    <a href="site:repository">repository file doc - section jdbc-connection-descriptor
                         <code>default-connection</code> attribute
-                    </link>
+                    </a>
                 </p>
                 <p>
-                    See <link href="#lookupPB">lookup PB api</link>.
+                    See <a href="#lookupPB">lookup PB api</a>.
                     <br/>
-                    See <link href="#lookupODMG">lookup ODMG api</link>.
+                    See <a href="#lookupODMG">lookup ODMG api</a>.
                 </p>
                 <source>
 PBKey pbKey = new PBKey(jcdAlias, user, passwd);
@@ -1095,7 +1131,7 @@
                     Keep in mind, when the
                     <code>connection-pool</code> element enables connection pooling, every user get its separate pool.
                     See
-                    <link href="#connectionPooling">How does OJB handle connection pooling?</link>.
+                    <a href="#connectionPooling">How does OJB handle connection pooling?</a>.
                 </p>
             </answer>
         </faq>
@@ -1109,7 +1145,7 @@
                     Define for each database a
                     <code>jdbc-connection-descriptor</code>, use the
                     different
-                    <code>jcdAlias</code> names in the <link href="site:repository">repositry file</link>
+                    <code>jcdAlias</code> names in the <a href="site:repository">repositry file</a>
                     to match the according database.
                 </p>
                 <source><![CDATA[
@@ -1127,13 +1163,13 @@
     ...
 </jdbc-connection-descriptor>]]></source>
                 <p>
-                    Specific notes related to the <link href="site:pb-guide/multiple-databases">PB-api here</link>.
+                    Specific notes related to the <a href="site:pb-guide/multiple-databases">PB-api here</a>.
                     <br/>
-                    Specific notes related to the <link href="site:odmg-guide/multiple-databases">ODMG-api here</link>.
+                    Specific notes related to the <a href="site:odmg-guide/multiple-databases">ODMG-api here</a>.
                 </p>
                 <note>
                     OJB does not provide distributed transactions by itself. To use distributed transactions,
-                    OJB have to be <link href="site:deployment/j2ee-server">integrated in an j2ee conform environment</link>
+                    OJB have to be <a href="site:deployment/j2ee-server">integrated in an j2ee conform environment</a>
                     (or made work with an JTA/JTS implementation).
                 </note>
             </answer>
@@ -1146,7 +1182,7 @@
             <answer>
                 <p>
                     Please have a look in section
-                    <link href="site:connection/connection-pooling">Connection Handling</link>.
+                    <a href="site:connection/connection-pooling">Connection Handling</a>.
                 </p>
             </answer>
         </faq>
@@ -1159,7 +1195,7 @@
             <answer>
                 <p>
                     Please have a look in section
-                    <link href="site:connection/obtain-connection">Connection Handling</link>.
+                    <a href="site:connection/obtain-connection">Connection Handling</a>.
                 </p>
             </answer>
         </faq>
@@ -1173,7 +1209,7 @@
                     There are serveral ways in OJB to do that.
                     <br/>
                     If you completely want to bypass the OJBquery-api see
-                    <link href="#obtainConnection">Can I directly obtain a java.sql.Connection within OJB?</link>.
+                    <a href="#obtainConnection">Can I directly obtain a java.sql.Connection within OJB?</a>.
                     <br/>
                     A more elegant way is to use a <code>QueryBySQL</code> object:
                 </p>
@@ -1197,7 +1233,7 @@
             </question>
             <answer>
                 <p>
-                    Please see <link href="site:connection/open-close-connection">Connection handling guide</link>.
+                    Please see <a href="site:connection/open-close-connection">Connection handling guide</a>.
                 </p>
             </answer>
         </faq>
@@ -1208,7 +1244,7 @@
             </question>
             <answer>
                 <p>
-                    See section <link href="site:metadata/without-repository">Metadata Handling</link>.
+                    See section <a href="site:metadata/without-repository">Metadata Handling</a>.
                 </p>
             </answer>
         </faq>
@@ -1219,7 +1255,7 @@
             </question>
             <answer>
                 <p>
-                    See section <link href="site:metadata/connect-at-runtime">Metadata Handling</link>.
+                    See section <a href="site:metadata/connect-at-runtime">Metadata Handling</a>.
                 </p>
             </answer>
         </faq>
@@ -1230,7 +1266,7 @@
             </question>
             <answer>
                 <p>
-                    See <em>Listener/Callback</em> section in <link href="site:pb-guide/listener">PB-Guide</link>.
+                    See <em>Listener/Callback</em> section in <a href="site:pb-guide/listener">PB-Guide</a>.
                 </p>
             </answer>
         </faq>
@@ -1242,7 +1278,7 @@
             </question>
             <answer>
                 <p>
-                    See section <link href="site:metadata/metadata-at-runtime">Metadata Handling</link>.
+                    See section <a href="site:metadata/metadata-at-runtime">Metadata Handling</a>.
                 </p>
             </answer>
         </faq>
@@ -1254,7 +1290,7 @@
             <answer>
                 <p>
                     Please see section
-                    <link href="site:metadata">Metadata Handling</link>.
+                    <a href="site:metadata">Metadata Handling</a>.
                 </p>
             </answer>
         </faq>
@@ -1266,7 +1302,7 @@
             <answer>
                 <p>
                     Please see section
-                    <link href="site:metadata">Metadata Handling</link>.
+                    <a href="site:metadata">Metadata Handling</a>.
                 </p>
             </answer>
         </faq>
@@ -1278,7 +1314,7 @@
             <answer>
                 <p>
                     Yes, see
-                    <link href="site:deployment">deployment</link> instructions in the docs.
+                    <a href="site:deployment">deployment</a> instructions in the docs.
                     Additional you can find some EJB example beans in package
                     <code>org.apache.ojb.ejb</code>
                     under
@@ -1506,7 +1542,7 @@
             </question>
             <answer>
                 <p>
-                    Please see <link href="site:lock-manager/optimistic-locking">locking section</link>.
+                    Please see <a href="site:lock-manager/optimistic-locking">locking section</a>.
                 </p>
             </answer>
         </faq>
@@ -1528,21 +1564,21 @@
                     <strong>transactional isolation and locking</strong>
                     <br/>
                     If you are using the PersistenceBroker API
-                    use <link href="#optimisticLocking">optimistic locking</link> (OL) to let
+                    use <a href="#optimisticLocking">optimistic locking</a> (OL) to let
                     OJB handle write conflicts.
                     To use OL define a TIMESTAMP or INTEGER column and the respective Java attribute for it.
                     In the field-descriptor of this attribute set the attribute
                     <em>locking="true"</em>.
                     <br/>
                     If you are working with the ODMG API
-                    <link href="site:lock-manager">distributed pessemistic locking</link> should
+                    <a href="site:lock-manager">distributed pessemistic locking</a> should
                     be used, by setting the respective flag in OJB.properties.
                 </p>
 
                 <p>
                     <strong>sequence numbers</strong>
                     <br/>
-                    Use a <link href="site:sequence-manager">SequenceManager</link> that is safe
+                    Use a <a href="site:sequence-manager">SequenceManager</a> that is safe
                     across multiple JVMs. The NextVal based SequenceManagers or any other SequenceManager
                     based on database mechanisms will be fine.
                 </p>
@@ -1550,7 +1586,7 @@
                 <p>
                     <strong>caching</strong>
                     <br/>
-                    You could use different <link href="site:object-cache">caching implementations</link>
+                    You could use different <a href="site:object-cache">caching implementations</a>
                 </p>
                 <ol>
                     <li>
@@ -1566,7 +1602,7 @@
                 </ol>
                 <p>
                     There is also a
-                    <link href="site:clustering">complete howto document</link>
+                    <a href="site:clustering">complete howto document</a>
                     available that covers these topics.
                 </p>
             </answer>
@@ -1579,7 +1615,7 @@
             <answer>
                 <p>
                     Declare an no-op implementation of the <code>ObjectCache</code> interface as
-                    cache. See <link href="site:object-cache/turn-off-caching">detailed description here</link>.
+                    cache. See <a href="site:object-cache/turn-off-caching">detailed description here</a>.
                 </p>
             </answer>
         </faq>
@@ -1616,5 +1652,5 @@
                 </p>
             </answer>
         </faq>
-    </part>
+    </faqsection>
 </faqs>

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/getting-started.xml
URL: http://svn.apache.org/viewcvs/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/getting-started.xml?rev=386233&r1=386232&r2=386233&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/getting-started.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/getting-started.xml Wed Mar 15 17:20:09 2006
@@ -171,6 +171,7 @@
         <section>
             <title>The build files</title>
 
+            <anchor id="ojb-blank-build-properties"/>
             <section>
                 <title>Configuration via <code>build.properties</code></title>
                 <p>

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/viewcvs/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/odmg-guide.xml?rev=386233&r1=386232&r2=386233&view=diff
==============================================================================
--- 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 Wed Mar 15 17:20:09 2006
@@ -81,8 +81,8 @@
                     auto_update="none"
                 </li>
                 <li>
-                    auto-delete="none" or auto-delete="object"
-                    (to enable cascading delete, since OJB 1.0.4!)
+                    auto-delete="none" (in this case the reference between the objects, the foreign key entry will 
+                    be nullified) or auto-delete="object" (to enable cascading delete, since OJB 1.0.4!)
                 </li>
             </ul>
             <note>
@@ -562,13 +562,12 @@
             <section>
                 <title>Access the PB-api within ODMG</title>
                 <p>
-                    As the
-                    <a href="site:pb-guide">PB-api</a> was used by OJB's
-                    <em>ODMG-api</em>
-                    implementation, thus it is possible to get access of the used
-                    <code>PersistenceBroker</code>
-                    instance using the extended Transaction interface class
-                    <a href="ext:odmg-transaction-ext">TransactionExt</a>:
+                    The <a href="site:pb-guide">PB-api</a> was used as persistence kernel
+                    by OJB's <em>ODMG-api</em> implementation, thus it is possible to get
+                    access of the used <code>PersistenceBroker</code>
+                    instance using <a href="#extensions">OJB's ODMG extensions</a>. The extended Transaction interface
+                    class <a href="ext:odmg-transaction-ext">TransactionExt</a> allow to lookup
+                    the current <code>PersistenceBroker</code> instance:
                 </p>
                 <source><![CDATA[
 Implementation odmg = ...;

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/performance.xml
URL: http://svn.apache.org/viewcvs/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/performance.xml?rev=386233&r1=386232&r2=386233&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/performance.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/performance.xml Wed Mar 15 17:20:09 2006
@@ -94,7 +94,7 @@
                 </p>
                 <ul>
                     <li>
-                        <code>perf-test</code>  multi-threaded performance/stress test of PB/OTM/ODMG api against native JDBC
+                        <code>perf-test</code>  single/multi-threaded performance (stress) test of PB/ODMG api against native JDBC
                     </li>
                     <li>
                         <code>performance</code>  single-threaded test, OJB API implementations (PB, ODMG) against native JDBC
@@ -137,121 +137,18 @@
             </section>
 
 
-            <anchor id="compares-to-native"/>
-            <section>
-                <title>How OJB compares to native JDBC programming - single-threaded</title>
-                <p>
-                    OJB is shipped with tests compares native JDBC with ODMG and
-                    PB-API implementation.
-                    This part of the test suite is integrated into the OJB build mechanism.
-                    <br/>
-                    A single client test you can
-                    invoke it by typing
-                    <code>ant performance</code> or
-                    <code>ant performance</code>.
-                </p>
-
-                <p>
-                    If running OJB out of the box the tests will be performed against
-                    the Hypersonic SQL (in-memory mode) shipped with OJB.
-                    A typical console output looks like follows:
-                    </p>
-                    <source><![CDATA[
-performance:
-      [ojb] .[performance] INFO: Test for PB-api
-      [ojb] [performance] INFO:
-      [ojb] [performance] INFO: inserting 1500 Objects: 188 msec
-      [ojb] [performance] INFO: updating 1500 Objects: 265 msec
-      [ojb] [performance] INFO: querying 1500 Objects: 0 msec
-      [ojb] [performance] INFO: querying 1500 Objects: 0 msec
-      [ojb] [performance] INFO: fetching 1500 Objects: 16 msec
-      [ojb] [performance] INFO: deleting 1500 Objects: 63 msec
-....
-      [ojb] Time: 5,672
-      [ojb] OK (1 test)
-
-     [jdbc] .[performance] INFO: Test for JDBC
-     [jdbc] [performance] INFO:
-     [jdbc] [performance] INFO: inserting 1500 Objects: 157 msec
-     [jdbc] [performance] INFO: updating 1500 Objects: 187 msec
-     [jdbc] [performance] INFO: querying 1500 Objects: 94 msec
-     [jdbc] [performance] INFO: querying 1500 Objects: 94 msec
-     [jdbc] [performance] INFO: fetching 1500 Objects: 16 msec
-     [jdbc] [performance] INFO: deleting 1500 Objects: 62 msec
-....
-     [jdbc] Time: 8,75
-     [jdbc] OK (1 test)
-
-     [odmg] .[performance] INFO: Test for ODMG-api
-     [odmg] [performance] INFO:
-     [odmg] [performance] INFO: inserting 1500 Objects: 266 msec
-     [odmg] [performance] INFO: updating 1500 Objects: 359 msec
-     [odmg] [performance] INFO: querying 1500 Objects: 531 msec
-     [odmg] [performance] INFO: querying 1500 Objects: 531 msec
-     [odmg] [performance] INFO: fetching 1500 Objects: 47 msec
-     [odmg] [performance] INFO: deleting 1500 Objects: 125 msec
-....
-     [odmg] Time: 13,75
-     [odmg] OK (1 test)]]></source>
-                <p>
-                    Some notes on these test results:
-                    </p>
-                    <ul>
-                        <li>
-                            You see a consistently better performance in the second and third run.
-                            this is caused by warming up effects of JVM and OJB.
-                        </li>
-                        <li>
-                            PB and native JDBC need about the same time for the three runs although JDBC
-                            performance is better for most operations.
-                            This is caused by the second run of the querying operations.
-                            In the second run OJB can load all objects from the cache, thus the time is
-                            <strong>much</strong> shorter.
-                            Hence the interesting result: if you have an application that has a lot of lookups,
-                            OJB can be faster than a native JDBC application (without caching extensions)!
-                        </li>
-                        <li>
-                            ODMG is much slower than PB or JDBC. This is due to the complex object level
-                            transaction management it is doing and the fact that ODMG doesn't have a specific
-                            method to lookup objects by it's identity. The second reason is responsible for
-                            slow <em>querying</em> results, because in test always a complex query is done for
-                            each object. It is possible to use the PB-api within ODMG, then the query by identity
-                            will be as fast as in PB-api.
-                        </li>
-                        <li>
-                            You can see that for HSQLDB operations like insert and update are faster with
-                            JDBC than with PB. This performance difference strongly depends on the used
-                            <a href="site:object-cache">cache implementation</a> and can rise up
-                            to 50% when the cache operate on object copies.
-                            This ratio is so high, because HSQLDB was running with <em>in memory mode</em> and
-                            is much faster than ordinary database servers.
-                            If you work against Oracle or DB2 the percentual OJB overhead is going down a
-                            lot (10 - 15 %), as the database latency is much longer than the OJB overhead.
-                        </li>
-                    </ul>
-                <p>
-                    It's easy to change target database. Please
-                    refer to this
-                    <a href="site:platform/select-profile">document for details</a>.
-                    <br/>
-                    Also it's possible to change the number of test objects by
-                    editing the ant-target in build.xml.
-                </p>
-                <p>
-                    Another test compares PB-api,ODMG-api and native JDBC you can find
-                    <a href="#multithreaded-performance">next section</a>.
-                </p>
-            </section>
 
 
             <anchor id="multithreaded-performance"/>
             <section>
                 <title>OJB performance in multi-threaded environments</title>
                 <p>
-                    This test was created to check the performance and stability of the
-                    supported API's (PB-api, ODMG-api and future API's) in a single/multithreaded
-                    environment and to compare the different api's against native JDBC calls.
+                    We created a simple multithreaded performance test application to check the
+                    performance and stability of the supported API's (PB-api, ODMG-api and future API's)
+                    in a single/multithreaded environment and to compare the different api's against
+                    native JDBC calls.
                     <br/>
+                    This performance test is integrated into the OJB build mechanism.
                     Running this test out of the box (a virgin OJB version against hsql)
                     shouldn't cause any problems.
                 </p>
@@ -259,8 +156,9 @@
                     Per default OJB use a in-memory hsql database, by changing the
                     <a href="site:repository/jdbc-connection-descriptor">JdbcConnectionDescriptor</a>
                     in the <em>repository.xml</em> file or modify the <em>build.properties</em> file when
-                    running OJB out of the box you can point to your specific RDBMS. Please
-                    refer to this
+                    running OJB out of the box you can point to your specific RDBMS.
+                    <br/>
+                    Please refer to this
                     <a href="site:platform/select-profile">document for details</a>.
                 </p>
 
@@ -270,11 +168,13 @@
                 <source><![CDATA[
     ant perf-test]]></source>
                 <p>
-                    A typical output of this test, using OJB against in-memory hsql looks like this
+                    A typical output of this test, using OJB against in-memory hsql
+                    (batch statements and pooled prepared statements are not used)
+                    looks like this:
                     </p>
                 <source><![CDATA[
 [ojb] ================================================================================================
-[ojb]             OJB PERFORMANCE TEST SUMMARY, Thu Dec 29 23:42:20 CET 2005
+[ojb]             OJB PERFORMANCE TEST SUMMARY, Fri Feb 03 12:21:30 CET 2006
 [ojb] ------------------------------------------------------------------------------------------------
 [ojb]   12 concurrent threads, handle 500 objects per thread
 [ojb]   500 INSERT operations per test instance
@@ -288,18 +188,44 @@
 [ojb] API         Total       Insert      Fetch       Fetch 2     by Id       Update      Delete
 [ojb]             [%]         [msec]      [msec]      [msec]      [msec]      [msec]      [msec]
 [ojb] ------------------------------------------------------------------------------------------------
-[ojb] JDBC        100         475(100%)   26(100%)    23(100%)    209(836%)   477(100%)   197(100%)
-[ojb] PB          203         1341(282%)  153(588%)   151(656%)   25(100%)    648(135%)   239(121%)
-[ojb] ODMG        250         1469(309%)  104(400%)   105(456%)   527(2108%)  800(167%)   569(288%)
+[ojb] JDBC        100         587(100%)   25(100%)    26(100%)    255(5100%)  531(100%)   211(100%)
+[ojb] PB          164         1362(232%)  80(320%)    75(288%)    5(100%)     897(168%)   269(127%)
+[ojb] ODMG        233         1716(292%)  102(408%)   98(376%)    9(180%)     1276(240%)  604(286%)
 [ojb] ================================================================================================
-[ojb] PerfTest takes 70 [sec]]]></source>
+[ojb] PerfTest takes 72 [sec]]]></source>
                 <p>
                     This test run shows the overhead caused by the O/R layer compared to handcoded sql
-                    statements. Most overheads results in populate the two-level cache which is useless
-                    when using a in-memory database.
+                    statements. Most overhead result in populate the two-level cache which is useless
+                    when using a in-memory database and the persistenece capable object state detection
+                    specific to the ODMG implementation.
+                </p>
+                <p>
+                    Below you can see the result of the same test against "a real database" <em>MaxDB</em>.
+                    However the database is running on the same machine.
+                </p>
+                <source><![CDATA[
+....
+[ojb] ================================================================================================
+[ojb] API         Total       Insert      Fetch       Fetch 2     by Id       Update      Delete
+[ojb]             [%]         [msec]      [msec]      [msec]      [msec]      [msec]      [msec]
+[ojb] ------------------------------------------------------------------------------------------------
+[ojb] JDBC        100         6064(100%)  56(107%)    55(100%)    1326(14733%)6259(154%)  3973(125%)
+[ojb] PB          105         11143(183%) 62(119%)    80(145%)    9(100%)     4062(100%)  3178(100%)
+[ojb] ODMG        113         11055(182%) 52(100%)    67(121%)    44(488%)    5067(124%)  3741(117%)
+[ojb] ================================================================================================
+[ojb] PerfTest takes 430 [sec]]]></source>
+                <p>
+                    You can see that the overhead caused by the O/R layer disappears bit by bit because
+                    the database latency and the network traffic is much longer than the OJB overhead.
                 </p>
                 <p>
-                    Below you can see the same test against <em>MaxDB</em> running on the same machine
+                    If we now enable prepared statement pooling (for OJB and the JDBC layer) and batch
+                    statements (for OJB only - unfair game but adding all these features to the sample
+                    JDBC-layer is too complex) the result will be completely different.
+                    <br/>
+                    The JDBC-layer show about 50% better performance because of the prepared statement
+                    pooling. OJB with prepared stament pooling and enabled batch mode shows about five
+                    times better performance for insert, update and delete operations.
                 </p>
                 <source><![CDATA[
 ....
@@ -307,17 +233,81 @@
 [ojb] API         Total       Insert      Fetch       Fetch 2     by Id       Update      Delete
 [ojb]             [%]         [msec]      [msec]      [msec]      [msec]      [msec]      [msec]
 [ojb] ------------------------------------------------------------------------------------------------
-[ojb] JDBC        100         5855(100%)  55(100%)    38(100%)    1628(5087%) 5588(184%)  4084(136%)
-[ojb] ODMG        117         12043(205%) 180(327%)   294(773%)   754(2356%)  3027(100%)  2988(100%)
-[ojb] PB          123         11577(197%) 94(170%)    84(221%)    32(100%)    4240(140%)  3193(106%)
+[ojb] PB          100         2176(100%)  41(100%)    45(100%)    8(100%)     311(104%)   52(100%)
+[ojb] ODMG        117         2428(111%)  80(195%)    70(155%)    18(225%)    297(100%)   182(350%)
+[ojb] JDBC        417         4078(187%)  69(168%)    65(144%)    1432(17900%)4224(1422%) 1110(2134%)
 [ojb] ================================================================================================
-[ojb] PerfTest takes 440 [sec]
+[ojb] PerfTest takes 139 [sec]]]></source>
+                <p>
+                    Now OJB trounce the JDBC-layer when running a mass test.
+                </p>
+                <p>
+                    Most perfomance comparison tests of O/R mapper against a JDBC-layer are unrealistic
+                    mass tests. A typical web-app or client-app will not handle thousands of objects
+                    per transaction. But mass tests are O/R mappers friends, because they mask the overhead
+                    of the O/R mapper compared with a JDBC-layer. So to show the performance of OJB overall
+                    and against a JDBC-layer the test should reflect a "real world application" - many threads,
+                    a few objects per transaction.
+                    <br/>
+                    If we chose a more realistic scenario e.g. 30 threads handle 20 objects per thread
+                    (same configuration settings as above, OJB batch mode enabled) nevertheless the result
+                    is near-balance:
+                </p>
+                <source><![CDATA[
+[ojb] ================================================================================================
+[ojb]             OJB PERFORMANCE TEST SUMMARY, Fri Feb 17 13:08:27 CET 2006
+[ojb] ------------------------------------------------------------------------------------------------
+[ojb]   30 concurrent threads, handle 20 objects per thread
+[ojb]   20 INSERT operations per test instance
+[ojb]   FETCH collection of 20 objects per test instance
+[ojb]   Repeat FETCH collection of 20 objects per test instance
+[ojb]   5 get by Identity calls  per test instance
+[ojb]   20 UPDATE operations per test instance
+[ojb]   20 DELETE operations per test instance
+[ojb]   - performance mode - results per test instance (average)
+[ojb] ================================================================================================
+[ojb] API         Total       Insert      Fetch       Fetch 2     by Id       Update      Delete
+[ojb]             [%]         [msec]      [msec]      [msec]      [msec]      [msec]      [msec]
+[ojb] ------------------------------------------------------------------------------------------------
+[ojb] PB          100         135(100%)   14(280%)    11(183%)    3(100%)     19(100%)    11(100%)
+[ojb] ODMG        123         151(111%)   11(220%)    14(233%)    4(133%)     43(226%)    16(145%)
+[ojb] JDBC        170         137(101%)   5(100%)     6(100%)     35(1166%)   124(652%)   25(227%)
+[ojb] ================================================================================================
+[ojb] PerfTest takes 144 [sec]]]></source>
+                <p>
+                    Even if we disable the OJB batch mode to make the test fair, the result is near-balance:
+                </p>
+                <source><![CDATA[
+[ojb] ================================================================================================
+[ojb] API         Total       Insert      Fetch       Fetch 2     by Id       Update      Delete
+[ojb]             [%]         [msec]      [msec]      [msec]      [msec]      [msec]      [msec]
+[ojb] ------------------------------------------------------------------------------------------------
+[ojb] JDBC        100         174(100%)   10(100%)    8(100%)     51(5100%)   196(175%)   39(100%)
+[ojb] ODMG        126         384(220%)   15(150%)    11(137%)    0(0%)       124(110%)   69(176%)
+[ojb] PB          158         510(293%)   18(180%)    19(237%)    7(700%)     112(100%)   91(233%)
+[ojb] ================================================================================================
+[ojb] PerfTest takes 215 [sec]
                 ]]></source>
+                <p>
+                    As you can see OJB show a overall good performance compared with a JDBC-layer
+                    against a RDMS.
+                    Hence the interesting result: if you have an application that has a lot of object lookups,
+                    OJB can be faster than a native JDBC application (without caching extensions) or if
+                    the JDBC-layer doesn't use batch statements, OJB can overall show a better performance.
+                </p>
                 <note>
                     The <em>performance test</em> output is written to console and in a
                     file called <em>OJB-Performance-Result.txt</em>.
+                    <br/>
+                    <br/>
+                    This simple test only compares the power of OJB and a JDBC-layer
+                    relating to a simple "flat" POJO object. Dealing with complex object graphs
+                    could give different results.
                 </note>
                 <p>
+                    If you want to play with different test settings, e.g. settings conform to
+                    your requirement, modify the ant target for this test.
+                    <br/>
                     To change the test properties go to target
                     <code>perf-test</code>
                     in the
@@ -362,6 +352,11 @@
     <!-- do some cleanup -->
     <ant target="copy-testdb"/>
 </target>]]></source>
+                <p>
+                    It's easy to change target database. Please
+                    refer to this
+                    <a href="site:platform/select-profile">document for details</a>.
+                </p>
             </section>
 
         </section>
@@ -459,7 +454,8 @@
 [number of insert/fetch/delete loops per thread]
 [optional boolean - run in stress mode if set true,
 run in performance mode if set false, default false]
-[optional boolean - if 'true' all log messages will be print, else only a test summary, default 'true']]]></source>
+[optional boolean - if 'true' all log messages will be print,
+    else only a test summary, default 'true']]]></source>
             <p>
                 For example:
             </p>
@@ -485,6 +481,106 @@
         </section>
 
 
+        <anchor id="compares-to-native"/>
+            <section>
+                <title>How OJB compares to native JDBC programming - single-threaded</title>
+                <p>
+                    OJB is shipped with another test compares native JDBC with ODMG and
+                    PB-API implementation.
+                    This part of the test suite is also integrated into the OJB build mechanism.
+                    <br/>
+                    A single client test you can invoke it by typing <code>ant performance</code>.
+                </p>
+
+                <p>
+                    If running OJB out of the box the tests will be performed against
+                    the Hypersonic SQL (in-memory mode) shipped with OJB.
+                    A typical console output looks like follows:
+                    </p>
+                    <source><![CDATA[
+performance:
+
+    [jdbc] .[performance] INFO: Test for JDBC
+    [jdbc] [performance] INFO:
+    [jdbc] [performance] INFO: inserting 1500 Objects: 78 msec
+    [jdbc] [performance] INFO: updating 1500 Objects: 47 msec
+    [jdbc] [performance] INFO: querying 1500 Objects: 31 msec
+    [jdbc] [performance] INFO: querying 1500 Objects: 31 msec
+    [jdbc] [performance] INFO: fetching 1500 Objects: 16 msec
+    [jdbc] [performance] INFO: deleting 1500 Objects: 15 msec
+....
+    [jdbc] Time: 8,75
+    [jdbc] OK (1 test)
+
+    [ojb] .[performance] INFO: Test for PB-api
+    [ojb] [performance] INFO:
+    [ojb] [performance] INFO: inserting 1500 Objects: 93 msec
+    [ojb] [performance] INFO: updating 1500 Objects: 94 msec
+    [ojb] [performance] INFO: querying 1500 Objects: 16 msec
+    [ojb] [performance] INFO: querying 1500 Objects: 16 msec
+    [ojb] [performance] INFO: fetching 1500 Objects: 62 msec
+    [ojb] [performance] INFO: deleting 1500 Objects: 32 msec
+....
+    [ojb] Time: 5,672
+    [ojb] OK (1 test)
+
+    [odmg] .[performance] INFO: Test for ODMG-api
+    [odmg] [performance] INFO:
+    [odmg] [performance] INFO: inserting 1500 Objects: 188 msec
+    [odmg] [performance] INFO: updating 1500 Objects: 250 msec
+    [odmg] [performance] INFO: querying 1500 Objects: 531 msec
+    [odmg] [performance] INFO: querying 1500 Objects: 516 msec
+    [odmg] [performance] INFO: fetching 1500 Objects: 47 msec
+    [odmg] [performance] INFO: deleting 1500 Objects: 171 msec
+....
+     [odmg] Time: 13,75
+     [odmg] OK (1 test)]]></source>
+                <p>
+                    Some notes on these test results:
+                    </p>
+                    <ul>
+                        <li>
+                            If you execute the test you can see a consistently better performance for
+                            OJB and the JDBC-layer in the second and third run.
+                            This is caused by warming up effects of JVM and OJB.
+                        </li>
+                        <li>
+                            ODMG is much slower than PB or JDBC. This is due to the complex object level
+                            transaction management it is doing and the fact that ODMG doesn't have a specific
+                            method to lookup objects by it's identity. The second reason is responsible for
+                            slow <em>querying</em> results, because in test always a complex query is done for
+                            each object. It is possible to use the PB-api within ODMG, then the query by identity
+                            will be as fast as in PB-api - see
+                            <a href="#multithreaded-performance">results for multi-threaded test</a>.
+                        </li>
+                        <li>
+                            You can see that for HSQLDB operations like insert and update are faster with
+                            JDBC than with PB. This performance difference strongly depends on the used
+                            <a href="site:object-cache">cache implementation</a> and can rise up
+                            to 50% when the cache operate on object copies.
+                            This ratio is so high, because HSQLDB was running with <em>in memory mode</em> which
+                            is much faster than ordinary database servers and caching the persistent objects
+                            when using a in-memory database is pure overhead.
+                            <br/>
+                            If you work against Oracle or DB2 the percentual OJB overhead is going down a
+                            lot (to 10 - 15 %), as the database latency is much longer than the OJB overhead.
+                        </li>
+                    </ul>
+                <p>
+                    It's easy to change target database. Please
+                    refer to this
+                    <a href="site:platform/select-profile">document for details</a>.
+                    <br/>
+                    Also it's possible to change the number of test objects by
+                    editing the ant-target in build.xml.
+                </p>
+                <p>
+                    Another test compares PB-api,ODMG-api and native JDBC in multi-threaded environment,
+                    you can find <a href="#multithreaded-performance">this section here</a>.
+                </p>
+            </section>
+
+
         <anchor id="maximal-performance"/>
         <section>
             <title>What are the best settings for maximal performance?</title>
@@ -496,29 +592,38 @@
                 <ul>
                     <li>
                         <p>
-                            The API you use, e.g. PB-api is much faster then the ODMG-api. See
+                            The API you use, e.g. PB-api is in many cases faster then the ODMG-api. See
                             <a href="site:faq/api-differences">which API</a> for more information.
                         </p>
                     </li>
-                    <li><p>The used <a href="site:object-cache">cache implementation</a>.</p></li>
-                    <li><p>ConnectionFactory implementation / Connection pooling. See
-                        <a href="site:faq">connection pooling</a>
-                        for more information.</p></li>
                     <li><p>The <em>autocommit</em> setting of used connections. For best performance
-                        it's recommended to use <em>autocommit</em> 'false' setting in the <em>jdbc-driver</em>
-                        to avoid <code>Connection.setAutoCommit(...)</code> calls by OJB.</p></li>
+                        it's recommended to set <em>autocommit</em> 'false' in the <em>jdbc-driver</em>
+                        or to use 'useAutoCommit="2"' setting in
+                        <a href="site:repository/jdbc-connection-descriptor">repository file database setting</a>
+                        to avoid <code>Connection.setAutoCommit(...)</code> calls by OJB.</p>
+                    </li>
+                    <li><p>Use of batch statements by enable <em>batch mode</em> (when supported by the DB) when
+                        insert/update/delete many objects of the same type (e.g. insert ProductGroup with 20 Article objects).
+                        See <a href="site:repository/jdbc-connection-descriptor"><em>jdbc-connection-descriptor</em></a>
+                        <em>batch-mode</em> attribute for more information.</p>
+                    </li>
                     <li><p><a href="site:advanced-technique/persistent-field"><code>PersistentField</code> class
-                        implementation</a>.See <a href="ext:ojb.properties">OJB.properties section
-                        'PersistentFieldClass'</a> to change the implementation.</p></li>
+                        implementation</a>. See <a href="ext:ojb.properties">OJB.properties section
+                        'PersistentFieldClass'</a> to change the implementation.</p>
+                    </li>
+                    <li><p>The used <a href="site:object-cache">cache implementation</a>.</p></li>
+                    <li><p>The <em>JDBC driver</em> settings (e.g. statement caching on/off).</p></li>
+                    <li><p>ConnectionFactory implementation / Connection pooling settings (e.g. prepared
+                        statement caching if the jdbc-driver doesn't support this feature).
+                        See <a href="site:faq">connection pooling</a> for more information.</p>
+                    </li>
                     <li><p>Used sequence manager implementation. See
                         <a href="site:sequence-manager">sequence manager</a> for
-                        more information.</p></li>
-                    <li><p>Use of <em>batch mode</em> (when supported by the DB). See
-                        <a href="site:repository/jdbc-connection-descriptor"><em>jdbc-connection-descriptor</em></a>
-                        <em>batch-mode</em> attribute for more information.</p></li>
+                        more information.</p>
+                    </li>
                     <li><p>PersistenceBroker pool size. See
-                        <a href="ext:ojb.properties">OJB.properties</a> for more information.</p></li>
-                    <li><p>The <em>JDBC driver</em> settings (e.g. statement caching on/off).</p></li>
+                        <a href="ext:ojb.properties">OJB.properties</a> for more information.</p>
+                    </li>
                 </ul>
             <p>
                 To test the different settings use the tests of the

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/platforms.xml
URL: http://svn.apache.org/viewcvs/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/platforms.xml?rev=386233&r1=386232&r2=386233&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/platforms.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/platforms.xml Wed Mar 15 17:20:09 2006
@@ -324,7 +324,7 @@
                     OJB ships with support for several popular database platforms.
                     The target platform is selected by the switch
                     <code>profile</code>
-                    in the file build.properties.
+                    in the file <em>build.properties</em> (shipped with OJB full source).
                     You can choose one out of the predefined profiles:
                 </p>
                 <source><![CDATA[
@@ -356,16 +356,16 @@
                     select a profile file from the
                     <code>profile</code> directory.
                     <br/>
-                    If you set
-                    <code>profile=db2</code>, then the file
-                    <code>profile/db2.profile</code>
-                    is selected.
+                    If you set <code>profile=db2</code>, then the file <code>profile/db2.profile</code>
+                    is selected. You have to <a href="#edit-profile">adapt the database properties in
+                    the profile file</a> before run.
                     <br/>
                     This file is used by the Torque scripts to set platform specific
                     properties and to perform platform specific SQL operations.
                 </p>
             </section>
 
+            <anchor id="edit-profile"/>
             <section>
                 <title>editing the profile to point to your target db</title>
                 <p>

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml
URL: http://svn.apache.org/viewcvs/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/repository.xml?rev=386233&r1=386232&r2=386233&view=diff
==============================================================================
--- 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 Wed Mar 15 17:20:09 2006
@@ -293,16 +293,6 @@
                         operations of same object type.
                     </p>
                     <note>
-                        OJB 1.0.5 and later:
-                        <br/>
-                        The issue caused by <a href="site:sequence-manager/identity-columns">database identity columns</a>
-                        on insert is fixed.
-                        <br/>
-                        The issue caused by classes using optimistic locking is fixed by temporarily diable
-                        batch-mode for all objects with optimistic locking. A more sophisticated solution will
-                        be provided in next major release.
-                        <br/>
-                        <br/>
                         OJB 1.0.4 and earlier:
                         <br/>
                         When using <a href="site:sequence-manager/identity-columns">database identity columns</a>
@@ -312,6 +302,15 @@
                         version check will always succeed for update operations when <em>batch-mode</em>
                         is enabled - take care!!.
                         <br/>
+                        <br/>
+                        OJB 1.0.5 and later:
+                        <br/>
+                        The issue caused by <a href="site:sequence-manager/identity-columns">database identity columns</a>
+                        on insert is fixed.
+                        <br/>
+                        The issue caused by classes using optimistic locking is fixed by temporarily disable
+                        batch-mode for all objects with optimistic locking. A more sophisticated solution will
+                        be provided in next major release.
                     </note>
                     <p>
                         The

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml
URL: http://svn.apache.org/viewcvs/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml?rev=386233&r1=386232&r2=386233&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/guides/sequencemanager.xml Wed Mar 15 17:20:09 2006
@@ -83,9 +83,50 @@
             </section>
 
 
+            <anchor id="force-id"/>
             <section>
                 <title>Force computation of unique values</title>
                 <p>
+                    To harmonize the behavior of OJB when using different <code>SequenceManager</code>
+                    implementations and to solve a problem with
+                    <a href="site:advanced-technique/table-per-subclass">"table per subclass"-inheritance</a>
+                    we restrict the early id association in newer versions of OJB.
+                </p>
+
+                <anchor id="since-1.0.4"/>
+                <section>
+                    <title>since OJB 1.0.4</title>
+                    <p>
+                        OJB no longer assign the PK values of transient objects on creation of
+                        the <a href="ext:identity"><code>Identity</code></a> objects (using
+                        <a href="ext:identity-factory"><code>IdentityFactory</code></a>).
+                        The <code>Identity</code> object of a transient persistence capable object
+                        is completely independent of the "real" primary key assigned on insert
+                        of the object - when calling
+                    </p>
+                    <source><![CDATA[
+Identity oid = broker.serviceIdentity().buildIdentity(object);]]></source>
+                    <p>
+                        the specified persistence capable object will not be modified and the
+                        returned <code>Identity</code> object use transient primary key placeholder.
+                    </p>
+                    <p>
+                        The reason for doing this was to "harmonize" the behavior of OJB when
+                        using different sequence generation strategies.
+                        <br/>
+                        E.g. when using database based identity columns (supported by MySQL, MsSQL, HSQL, ...)
+                        it's not possible to lookup the generated PK value before
+                        the object is written to database.
+                    </p>
+                    <p>
+                        
+                    </p>
+                </section>
+
+                <anchor id="before-1.0.4"/>
+                <section>
+                    <title>OJB 1.0.3 and earlier</title>
+                    <p>
                     By default OJB triggers the computation
                     of unique ids during calls to PersistenceBroker.store(...).
                     Sometimes it will be necessary to have the ids computed in advance,
@@ -94,9 +135,9 @@
                     follows:
                 </p>
                 <source><![CDATA[
-Identity oid = broker.serviceIdentity().buildIdentity(Object newPersistentObject);]]></source>
+Identity oid = broker.serviceIdentity().buildIdentity(object);]]></source>
                 <p>
-                    This creates an <a href="ext:api/identity">Identity</a> object for the
+                    This creates an <a href="ext:api/identity"><code>Identity</code></a> object for the
                     new persistent object and set all primary key values of the new persistent object
                     - But it only works if <a href="#autoincrement"><code>autoincrement</code></a>
                     is enabled for the primary key fields.
@@ -113,6 +154,7 @@
                     Info about lookup persistent objects by primary key fields
                     <a href="site:pb-tutorial/find-by-pk">see here</a>.
                 </p>
+                </section>
             </section>
 
 

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/jdo-tutorial.xml
URL: http://svn.apache.org/viewcvs/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/jdo-tutorial.xml?rev=386233&r1=386232&r2=386233&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/jdo-tutorial.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/jdo-tutorial.xml Wed Mar 15 17:20:09 2006
@@ -50,7 +50,7 @@
                 </p>
                 <note>
                     OJB does not provide it's own JDO implementation yet.
-                    A full JDO implementation is in the scope of the 2.0 release.
+                    A full JDO 2.0 implementation is in the scope of the OJB 2.x release.
                     <br/>
                     For the time being we provide a plugin to the JDO reference implementation
                     called <code>OjbStore</code>. The <code>OjbStore</code> plugin resides in

Modified: db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.xml
URL: http://svn.apache.org/viewcvs/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.xml?rev=386233&r1=386232&r2=386233&view=diff
==============================================================================
--- db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.xml (original)
+++ db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/odmg-tutorial.xml Wed Mar 15 17:20:09 2006
@@ -257,5 +257,18 @@
             </p>
         </section>
 
+        <anchor id="find-by-pk"/>
+            <section>
+                <title>Find object by primary key</title>
+                <p>
+                    The ODMG-api doesn't provide specific methods to lookup objects by
+                    primary key. In this case it's recommended to use an
+                    <a href="site:query/odmg-oql">oql-query</a> or for much better performance
+                    the PB-api within the odmg-transaction. To access the PB-api within ODMG use
+                    OJB's <a href="site:odmg-guide/pb-access">odmg-extensions</a>. How to
+                    lookup objects by identity <a href="site:pb-tutorial/find-by-pk">see here</a>.
+                </p>
+            </section>
+
     </body>
 </document>

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/viewcvs/db/ojb/branches/OJB_1_0_RELEASE/src/doc/forrest/src/documentation/content/xdocs/docu/tutorials/pb-tutorial.xml?rev=386233&r1=386232&r2=386233&view=diff
==============================================================================
--- 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 Wed Mar 15 17:20:09 2006
@@ -438,12 +438,15 @@
                     In some cases only the primary key values (single field or n-fields for composed primary
                     keys) of an object are known. In OJB you have several ways to request the whole object.
                     It is possible to build a query as
-                    <a href="#query-objects">shown above</a>, but the smarter
+                    <a href="#query-objects">shown above</a>, but the smarter (and faster)
                     solution is to use <code>PersistenceBroker#getObjectByIdentity(Identity oid)</code>. An
                     <a href="ext:identity">Identity</a> object is a unique representation of a persistence
                     capable object based on the object primary key values and the <em>top-level class</em> (abstract class,
                     interface or the class itself, depending on the
                     <a href="site:advanced-technique/extents">extent metadata mapping</a>).
+                    <br/>
+                    To build <a href="ext:identity">Identity</a> objects OJB provide a service class called
+                    <a href="ext:identity-factory"><code>IdentityFactory</code></a>.
                 </p>
                 <p>
                     For example, to find an <em>Product</em> with an single primary key of <em>'23'</em>
@@ -452,6 +455,10 @@
                 <source><![CDATA[
 Identity oid = broker.serviceIdentity().buildIdentity(Product.class, new Integer(23));
 Product product = (Product) broker.getObjectByIdentity(oid);]]></source>
+                <note>
+                    If the persistent object use compound primary keys you have to specifiy
+                    all keys to get a distinct result.
+                </note>
             </section>
 
         </section>



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