db-ojb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From arm...@apache.org
Subject cvs commit: db-ojb/forrest/src/documentation/content/xdocs site.xml status.xml features.xml
Date Sun, 25 Apr 2004 01:31:33 GMT
arminw      2004/04/24 18:31:33

  Modified:    forrest/src/documentation/content/xdocs/docu objectcache.xml
                        faq.xml
               forrest/src/documentation/content/xdocs site.xml status.xml
                        features.xml
  Added:       forrest/src/documentation/content/xdocs/docu platforms.xml
                        testwrite.xml performance.xml testsuite.xml
  Log:
  more adapted docs + new
  
  Revision  Changes    Path
  1.2       +2 -2      db-ojb/forrest/src/documentation/content/xdocs/docu/objectcache.xml
  
  Index: objectcache.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/docu/objectcache.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- objectcache.xml	23 Apr 2004 19:17:46 -0000	1.1
  +++ objectcache.xml	25 Apr 2004 01:31:33 -0000	1.2
  @@ -394,7 +394,7 @@
                   <br/>
                   Integration of your implementation in OJB is easy since the object cache is
                   a pluggable component. All you have to do, is to declare it in the
  -                <link href="site:guide/ojb.properties">
  +                <link href="site:guides/ojb-properties">
                       <code>OJB.properties</code>
                   </link> file by setting the
                   <code>ObjectCacheClass</code> property.
  
  
  
  1.2       +2 -2      db-ojb/forrest/src/documentation/content/xdocs/docu/faq.xml
  
  Index: faq.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/docu/faq.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- faq.xml	22 Apr 2004 19:29:50 -0000	1.1
  +++ faq.xml	25 Apr 2004 01:31:33 -0000	1.2
  @@ -14,6 +14,7 @@
     See the License for the specific language governing permissions and
     limitations under the License.
   -->
  +<!-- @version $Id$ -->
   <!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.2//EN" "http://apache.org/forrest/dtd/faq-v12.dtd">
   
   <faqs title="Frequently Asked Questions">
  @@ -363,8 +364,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 the core tables.
  -                    http://jakarta.apache.org/ojb/platforms.html. These core tables are used by
  +                    database. Look on this page for <link href="site:platform">the core tables</link>. 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>
  
  
  
  1.1                  db-ojb/forrest/src/documentation/content/xdocs/docu/platforms.xml
  
  Index: platforms.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!--
    Copyright 2002-2004 The Apache Software Foundation
  
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
  
        http://www.apache.org/licenses/LICENSE-2.0
  
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
  -->
  <!-- @version $Id: platforms.xml,v 1.1 2004/04/25 01:31:33 arminw Exp $ -->
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
  
  <document>
      <header>
          <title>Platforms</title>
          <authors>
              <person name="Thomas Mahler" email="thma@apache.org"/>
          </authors>
      </header>
  
      <body>
          <section>
              <title>how to use OJB with a specific relational database</title>
              <p>
                  OJB has been designed to smoothly integrate with any relational
                  database that provides JDBC support. OJB can be configured to use only JDBC 1.0 API calls
                  to avoid problems with restrictions of several JDBC drivers.
                  <br/>It
                  uses a limited SQL subset to avoid problems with restrictions of
                  certain RDBMS. This design allows to keep the OJB code generic and
                  free from database specifics.
              </p>
              <p>
                  This document explains basic concepts and shows how OJB can be
                  configured to run against a specific RDBMS.
              </p>
          </section>
          <section>
              <title>Basic Concepts</title>
  
              <section>
                  <title>OJB internal tables</title>
                  <p>
                      For certain features OJB relies on several internal tables that must be present in the
                      target rdbms to allow a proper functioning.
                      <br/>
                      If those features are not needed OJB can be safely run without any internal tables.
                  </p>
                  <p>
                      The following table
                      lists all tables and their specific purpose.
                  </p>
  
                  <table>
                      <tr>
                          <th>Tablename</th>
                          <th>Purpose</th>
                      </tr>
                      <tr>
                          <td>
                              <code>OJB_HL_SEQ</code>
                          </td>
                          <td>
                              Table for the high/low sequence manager.
                              <br/>
                              If the built-in OJB sequence manager is not used, this table is not needed.
                          </td>
                      </tr>
                      <tr>
                          <td>
                              <code>OJB_LOCKENTRY</code>
                          </td>
                          <td>
                              <p>This table is used to store Object locks if the LockManager is
                                  run in distributed mode. Not needed in singlevm mode.</p>
                          </td>
                      </tr>
                      <tr>
                          <td>
                              <code>OJB_NRM</code>
                          </td>
                          <td>
                              <p>The &quot;Named Roots Map&quot;. ODMG allows to bind
                                  persistent objects to an user defined name.
                                  <br/>The Named roots
                                  map is used to store these bindings. It has NAME (String of
                                  arbitrary length) as primary key and keeps the serialized OID of
                                  the persistent object in the field OID (String of arbitrary
                                  length).
                                  <br/>
                                  If bind() and lookup() are not used in client apps, this table is not needed
                              </p>
                          </td>
                      </tr>
                      <tr>
                          <td>
                              <code>OJB_DLIST</code>
                          </td>
                          <td>
                              <p>The table used for the ODMG persistent DList collections.
                                  <br/>
                                  If ODMG DLists are not used, this table is not needed.
                              </p>
                          </td>
                      </tr>
                      <tr>
                          <td>
                              <code>OJB_DLIST_ENTRIES</code>
                          </td>
                          <td>
                              <p>stores the entries of DLists (a wrapper to objects stored in
                                  the DList)
                                  <br/>
                                  If ODMG DLists are not used, this table is not needed.
                              </p>
                          </td>
                      </tr>
                      <tr>
                          <td>
                              <code>OJB_DSET</code>
                          </td>
                          <td>
                              <p>The table used to store ODMG persistent DSET collections
                                  <br/>
                                  If ODMG DSets are not used, this table is not needed.
                              </p>
                          </td>
                      </tr>
                      <tr>
                          <td>
                              <code>OJB_DSET_ENTRIES</code>
                          </td>
                          <td>
                              <p>This table stores the entries of DSets.
                                  <br/>
                                  If ODMG DSets are not used, this table is not needed.
                              </p>
                          </td>
                      </tr>
                      <tr>
                          <td>
                              <code>OJB_DMAP</code>
                          </td>
                          <td>
                              <p>The table use to store the ODMG persistent DMap tables
                                  <br/>
                                  If ODMG DMaps are not used, this table is not needed.
                              </p>
                          </td>
                      </tr>
                      <tr>
                          <td>
                              <code>OJB_DMAP_ENTRIES</code>
                          </td>
                          <td>
                              <p>The table containing the DMap entries. The Keys and Values of
                                  the map can be arbitrary persistent objects.
                                  <br/>
                                  If ODMG DMaps are not used, this table is not needed.
                              </p>
                          </td>
                      </tr>
                  </table>
  
                  <p>
                      OJB uses
                      <link href="ext:torque">Torque</link>
                      to create all required tables and data.
                      Thus there is no SQL DDL file, but an XML file describing the
                      tables in format readable by Torque.
  
                      The Torque DDL information for the internal tables resides in the
                      file
                      <code>src/schema/ojbcore-schema.xml</code>.
                  </p>
                  <p>
                      The o/r mappings for these tables are contained in the file
                      <code>repository_internal.xml</code>.
                  </p>
  
              </section>
              <section>
                  <title>Tables for the regression testbed</title>
                  <p>
                      It is recommended to run the OJB JUnit regression tests
                      against your target database.
                      Thus you will have to provide several more tables, filled with the proper
                      testdata.
                  </p>
                  <p>
                      The DDL information for these tables resides in the
                      file
                      <code>src/schema/ojbtest-schema.xml</code>.
                  </p>
                  <p>
                      The testdata is defined in the
                      file
                      <code>src/schema/ojbtest-data.xml</code>.
                  </p>
                  <p>
                      The o/r mappings for these tables are contained in the file
                      <code>repository_junit.xml</code>.
                  </p>
              </section>
  
              <section>
                  <title>Tables for the tutorial applications</title>
                  <p>
                      If you intend to run the OJB tutorial applications
                      against your target database
                      you will have to provide one extra table.
                  </p>
                  <p>
                      The DDL information for this table also resides in the
                      file
                      <code>src/schema/ojbtest-schema.xml</code>.
                  </p>
                  <p>
                      The testdata is also defined in the
                      file
                      <code>src/schema/ojbtest-data.xml</code>.
                  </p>
                  <p>
                      The o/r mappings for this table is contained in the file
                      <code>repository_user.xml</code>.
                  </p>
              </section>
  
          </section>
  
  
          <section>
              <title>The setup process</title>
              <p>
                  OJB provides a setup routine to generate the target database and to fill it
                  with the required testdata.
                  This routine is based on Torque scripts and is driven from the build.xml file.
                  This section describes how to use it.
              </p>
              <section>
                  <title>Selecting a platform profile</title>
                  <p>
                      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.
                      You can choose one out of the predefined profiles:
                  </p>
                  <source><![CDATA[
  # With the 'profile' property you can choose the RDBMS platform OJB is using
  # implemented profiles:
  #
  profile=hsqldb
  # use the mssqldb-JSQLConnect profile for Microsoft SQL Server and
  # you will automatically JSQLConnect driver, from http://www.j-netdirect.com/
  # MBAIRD: This is my driver of preference for MS SQL Server, I find the OEM'd
  # MS driver to have some problems.
  #profile=mssqldb-JSQLConnect
  #profile=mssqldb-Opta2000
  #profile=mssqldb-ms
  #profile=mysql
  #profile=db2
  #profile=oracle
  #profile=oracle9i
  #profile=oracle9i-Seropto
  #profile=msaccess
  #profile=postgresql
  #profile=informix
  #profile=sybase
  #profile=sapdb
  #profile=maxdb]]></source>
                  <p>
                      The profile switch activated in
                      <code>build.properties</code> is used to
                      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.
                      <br/>
                      This file is used by the Torque scripts to set platform specific
                      properties and to perform platform specific SQL operations.
                  </p>
              </section>
  
              <section>
                  <title>editing the profile to point to your target db</title>
                  <p>
                      The platform specific file
                      <code>profile/xxx.profile</code>
                      contains lots of information used by Torque.
                      You can ignore most of it.
                      The only important part in this file is the section where
                      the url to the target db is assembled, here is an snip of the
                      DB2 profile:
                  </p>
                  <source><![CDATA[
  # ----------------------------------------------------------------
  #
  #  D A T A B A S E  S E T T I N G S
  #
  # ----------------------------------------------------------------
  # JDBC connection settings. This is used by the JDBCToXML task
  # that will create an XML database schema from JDBC metadata.
  # These settings are also used by the SQL Ant task to initialize
  # your Turbine system with the generated SQL.
  # ----------------------------------------------------------------
  
  dbmsName = Db2
  jdbcLevel = 1.0
  urlProtocol = jdbc
  urlSubprotocol = db2
  urlDbalias = OJB
  
  createDatabaseUrl = ${urlProtocol}:${urlSubprotocol}:${urlDbalias}
  buildDatabaseUrl = ${urlProtocol}:${urlSubprotocol}:${urlDbalias}
  databaseUrl = ${urlProtocol}:${urlSubprotocol}:${urlDbalias}
  databaseDriver = COM.ibm.db2.jdbc.app.DB2Driver
  databaseUser = admin
  databasePassword = db2
  databaseHost = 127.0.0.1  ]]></source>
                  <p>
                      These settings result in a database URL
                      <code>jdbc:db2:OJB</code>.
                      If your production database is registered with the name
                      <code>MY_PRODUCTION_DB</code> you have to edit the entry
                      <code>urlDBalias</code> to:
                      <br/>
                      <code>urlDbalias = MY_PRODUCTION_DB</code>.
                  </p>
                  <p>
                      In this section you can also set application user name and password.
                      You can also enter a different jdbc driver class, to activate a different
                      driver.
                  </p>
                  <p>
                      Before progressing, please check that the jdbc driver class, named
                      in the
                      <code>databaseDriver</code> entry is located on the classpath!
                      You can either edit the global environment variable
                      <code>CLASSPATH</code>
                      or place the jdbc driver jar file into the
                      <code>jakarta-ojb-xxx/lib</code>
                      directory.
                  </p>
              </section>
  
  
              <section>
                  <title>Executing the build script</title>
                  <p>
                      Now everything should be prepared to launch the setup routine.
                      This routine can be invoked by calling
                      <strong>
                          <code>ant prepare-testdb</code>
                      </strong>.
                  </p>
                  <p>
                      If you are prompted with a
                      <code>BUILD SUCCESSFUL</code> message after
                      some time, everything is OK.
                  </p>
                  <p>
                      If you are prompted with a
                      <code>BUILD FAILED</code> message after
                      some time, something went wrong.
                      This may have several reasons:
                      </p>
                      <ul>
                          <li>
                              You entered some incorrect settings. Please check the
                              log messages to see what went wrong.
                          </li>
                          <li>
                              Torque does not work properly against your target database.
                              Torque is very flexible and should be able to work against
                              a wide range of databases. But the code templates for each
                              database may not be accurate.
                              Please check the ojb-user mailinglist archive if there are
                              any failure reports for your specific database.
                              Please also check if some contributed a fix already.
                              If you don't find anything please post your problem to the ojb user-list.
                          </li>
                      </ul>
                  <p>
                      As a last resort you can try the following:
                      Switch back to the default hsqldb profile and execute
                      <code>ant prepare-testdb</code>
                      This will setup the default hsqldb database.
                      And it will also generate SQL scripts that you may use to generate your
                      database manually.
                  </p>
                  <p>
                      The SQL scripts are generated to
                      <code>jakarta-ojb-xxx/target/src/sql</code>.
                      You can touch these scripts to match your database specifics and
                      execute them manually against your platform.
                  </p>
              </section>
  
  
              <section>
                  <title>Verifying the installation</title>
                  <p>
                      Now everything is setup to run the junit regression tests against
                      your target database.
                  </p>
                  <p>
                      Execute
                      </p>
                     <source><![CDATA[
  ant junit]]></source>
                      <p>
                          to see if everything works as expected.
                          more information about the <link href="site:test-suite">OJB Test Suite here</link>.
                      If you did not manage to set up the target database with the
                      <code>ant prepare-testdb</code> you can use
                      <br/>
                      <strong>
                          <code>ant junit-no-compile-no-prepare</code>
                      </strong> to run the testsuite without generation of the test database.
                  </p>
                  </section>
          </section>
      </body>
  </document>
  
  
  
  
  
  
  
  
  
  
  1.1                  db-ojb/forrest/src/documentation/content/xdocs/docu/testwrite.xml
  
  Index: testwrite.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!--
    Copyright 2002-2004 The Apache Software Foundation
  
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
  
        http://www.apache.org/licenses/LICENSE-2.0
  
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
  -->
  <!-- @version $Id: testwrite.xml,v 1.1 2004/04/25 01:31:33 arminw Exp $ -->
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
  
  <document>
      <header>
          <title>Write Tests</title>
          <authors>
              <person name="Armin Waibel" email="arminw@apache.org"/>
          </authors>
      </header>
  
      <body>
          <section>
              <title>Introduction</title>
              <fixme author="arminw">
              Write this document!
              </fixme>
              <p>
  
              </p>
          </section>
          <section>
              <title>Donate new Tests</title>
              <p>
  
              </p>
          </section>
      </body>
  </document>
  
  
  1.1                  db-ojb/forrest/src/documentation/content/xdocs/docu/performance.xml
  
  Index: performance.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!--
    Copyright 2002-2004 The Apache Software Foundation
  
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
  
        http://www.apache.org/licenses/LICENSE-2.0
  
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
  -->
  <!-- @version $Id: performance.xml,v 1.1 2004/04/25 01:31:33 arminw Exp $ -->
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
  
  <document>
      <header>
          <title>OJB Performance</title>
          <authors>
              <person name="Armin Waibel" email="arminw@apache.org"/>
              <person name="Thomas Mahler" email="thma@apache.org"/>
          </authors>
      </header>
  
      <body>
  
          <section>
              <title>Introduction</title>
              <p>
                  <em>&quot;
                      <strong>There is no such thing as a free lunch.&quot;</strong>
                      <br/>
                  </em>
                  <em>(North American proverb)</em>
              </p>
              <p>
                  Object/relational mapping tools hide the details of relational
                  databases from the application developer. The developer can
                  concentrate on implementing business logic and is liberated from
                  caring about RDBMS related coding with JDBC and SQL.
              </p>
  
              <p>
                  O/R mapping tools allow to separate business logic from RDBMS
                  access by forming an additional software layer between business logic
                  and RDBMS. Introducing new software layers always eats up additional
                  computing resources.
                  <br/>In short: the price for using O/R tools is performance.
              </p>
  
              <p>
                  Software architects have to take in account this tradeoff between
                  programming comfort and performance to decide if it is appropiate to
                  use an O/R tool for a specific software system.
              </p>
              <p>
                  This document describes the
                  <em>OJB Performance Test Suite</em>
                  which was created to lighten the decision between native JDBC,
                  OJB (the different OJB API's) and other O/R mapper.
              </p>
          </section>
  
          <section>
              <title>The Performance Test Suite</title>
              <anchor id="performance-test-suite"/>
              <p>
                  The
                  <em>OJB Performance Test Suite</em> allows to compare OJB
                  against
                  <link href="#compares-to-native">native JDBC programming</link>
                  against your RDBMS of choice and run OJB in a
                  <link href="#multithreaded-performance">virtual multithreaded
                      environment</link>. Further on it is possible to
                  <link href="#compares-to-other">compare OJB against any O/R mapping tool</link> using a simple
                  framework.
              </p>
              <p>
                  All tests are integrated in the OJB build script, you only need to
                  perform the according ant target:
              </p>
              <p>
                  <code>ant target</code>
              </p>
              <p>
                  The following 'targets' exist:
                  </p>
                  <ul>
                      <li>
                          <code>perf-test</code> multithreaded performance/stress test of PB/OTM/ODMG api against native JDBC
                      </li>
                      <li>
                          <code>performance</code> older single threaded test,  OJB API implementations (PB, ODMG) against native JDBC
                      </li>
                      <li>[
                          <code>performance3</code> multithreaded test against two different databases - developers test]
                      </li>
                  </ul>
              <p>
                  By changing the JdbcConnectionDescriptor in the configuration files
                  you can point to your specific RDBMS. Please
                  refer to this
                  <link href="site:platform">document for details</link>.
              </p>
          </section>
  
  
          <section>
              <title>Interpreting test results</title>
              <p>
                  Interpreting the result of these benchmarks carefully will help to
                  decide whether using OJB is viable for specific application scenarios
                  or if native JDBC programming should be used for performance reasons.
              </p>
              <p>
                  Take care of compareable configuration properties when run
                  performance tests with different O/R tools.
              </p>
              <p>
                  If the decision made to use an O/R mapping tool the comparison with
                  other tools helps to find the best one for the thought scenario.
                  But performance shouldn't be the only reason to take a specific
                  O/R tool. There are many other points to consider:
              </p>
              <p>
                  - Usability of the supported API's
                  <br/>- Flexibility of the framework
                  <br/>- Scalability of the framework
                  <br/>- Community support
                  <br/>- The different licences of Open Source projects
                  <br/>- etcetera ...
              </p>
  
          </section>
  
  
          <section>
              <title>How OJB compares to native JDBC programming?</title>
              <anchor id="compares-to-native"/>
              <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 shipped with OJB. A typical output looks like
                  follows:
                  </p>
                  <source><![CDATA[
  performance:
        [ojb] .[performance] INFO: Test for PB-api
        [ojb] [performance] INFO:
        [ojb] [performance] INFO: inserting 2500 Objects: 3257 msec
        [ojb] [performance] INFO: updating 2500 Objects: 1396 msec
        [ojb] [performance] INFO: querying 2500 Objects: 1322 msec
        [ojb] [performance] INFO: querying 2500 Objects: 26 msec
        [ojb] [performance] INFO: fetching 2500 Objects: 495 msec
        [ojb] [performance] INFO: deleting 2500 Objects: 592 msec
        [ojb] [performance] INFO:
        [ojb] [performance] INFO: inserting 2500 Objects: 869 msec
        [ojb] [performance] INFO: updating 2500 Objects: 1567 msec
        [ojb] [performance] INFO: querying 2500 Objects: 734 msec
        [ojb] [performance] INFO: querying 2500 Objects: 20 msec
        [ojb] [performance] INFO: fetching 2500 Objects: 288 msec
        [ojb] [performance] INFO: deleting 2500 Objects: 447 msec
        [ojb] [performance] INFO:
        [ojb] [performance] INFO: inserting 2500 Objects: 979 msec
        [ojb] [performance] INFO: updating 2500 Objects: 1240 msec
        [ojb] [performance] INFO: querying 2500 Objects: 741 msec
        [ojb] [performance] INFO: querying 2500 Objects: 18 msec
        [ojb] [performance] INFO: fetching 2500 Objects: 289 msec
        [ojb] [performance] INFO: deleting 2500 Objects: 446 msec
  
        [ojb] Time: 18,964
  
        [ojb] OK (1 test)
  
       [jdbc] .[performance] INFO: Test for native JDBC
       [jdbc] [performance] INFO:
       [jdbc] [performance] INFO: inserting 2500 Objects: 651 msec
       [jdbc] [performance] INFO: updating 2500 Objects: 775 msec
       [jdbc] [performance] INFO: querying 2500 Objects: 616 msec
       [jdbc] [performance] INFO: querying 2500 Objects: 384 msec
       [jdbc] [performance] INFO: fetching 2500 Objects: 49 msec
       [jdbc] [performance] INFO: deleting 2500 Objects: 213 msec
       [jdbc] [performance] INFO:
       [jdbc] [performance] INFO: inserting 2500 Objects: 508 msec
       [jdbc] [performance] INFO: updating 2500 Objects: 686 msec
       [jdbc] [performance] INFO: querying 2500 Objects: 390 msec
       [jdbc] [performance] INFO: querying 2500 Objects: 360 msec
       [jdbc] [performance] INFO: fetching 2500 Objects: 46 msec
       [jdbc] [performance] INFO: deleting 2500 Objects: 204 msec
       [jdbc] [performance] INFO:
       [jdbc] [performance] INFO: inserting 2500 Objects: 538 msec
       [jdbc] [performance] INFO: updating 2500 Objects: 775 msec
       [jdbc] [performance] INFO: querying 2500 Objects: 384 msec
       [jdbc] [performance] INFO: querying 2500 Objects: 360 msec
       [jdbc] [performance] INFO: fetching 2500 Objects: 48 msec
       [jdbc] [performance] INFO: deleting 2500 Objects: 204 msec
  
       [jdbc] Time: 18,363
  
       [jdbc] OK (1 test)
  
       [odmg] .[performance] INFO: Test for ODMG-api
       [odmg] [performance] INFO:
       [odmg] [performance] INFO: inserting 2500 Objects: 12151 msec
       [odmg] [performance] INFO: updating 2500 Objects: 2937 msec
       [odmg] [performance] INFO: querying 2500 Objects: 4691 msec
       [odmg] [performance] INFO: querying 2500 Objects: 2239 msec
       [odmg] [performance] INFO: fetching 2500 Objects: 1633 msec
       [odmg] [performance] INFO: deleting 2500 Objects: 1815 msec
       [odmg] [performance] INFO:
       [odmg] [performance] INFO: inserting 2500 Objects: 2483 msec
       [odmg] [performance] INFO: updating 2500 Objects: 2868 msec
       [odmg] [performance] INFO: querying 2500 Objects: 3272 msec
       [odmg] [performance] INFO: querying 2500 Objects: 2223 msec
       [odmg] [performance] INFO: fetching 2500 Objects: 1038 msec
       [odmg] [performance] INFO: deleting 2500 Objects: 1717 msec
       [odmg] [performance] INFO:
       [odmg] [performance] INFO: inserting 2500 Objects: 2666 msec
       [odmg] [performance] INFO: updating 2500 Objects: 2841 msec
       [odmg] [performance] INFO: querying 2500 Objects: 2092 msec
       [odmg] [performance] INFO: querying 2500 Objects: 2161 msec
       [odmg] [performance] INFO: fetching 2500 Objects: 1036 msec
       [odmg] [performance] INFO: deleting 2500 Objects: 1741 msec
  
       [odmg] Time: 55,186]]></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!
                      </li>
                      <li>
                          ODMG is much slower than PB or JDBC. This is due to the complex object level transaction management it is doing.
                      </li>
                      <li>
                          You can see that for HSQLDB operations like insert and update are much faster with JDBC than with PB (60% and more).
                          This ratio is so high, because HSQLDB is much faster than ordinary database servers (as it's inmemory).
                          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
                  <link href="platforms.html">document for details</link>.
                  <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
                  <link href="#multithreaded-performance">next section</link>.
              </p>
          </section>
  
  
          <section>
              <title>OJB performance in multi-threaded environments</title>
              <anchor id="multithreaded-performance"/>
              <p>
                  This test was created to check the performance and stability of the
                  supported API's (PB-api, ODMG-api, JDO-api) in a multithreaded environment.
                  Also this test compares the api's and native JDBC.
                  <br/>
                  Running this test out of the box (a virgin OJB version against hsql) shouldn't cause any problems.
                  To run the JDO-api test too, see
                  <link href="site:jdo-tutorial">JDO tutorial</link> and comment in
                  the test in target
                  <code>perf-test</code> in
                  <code>build.xml</code>
              </p>
              <fixme author="arminw">
                  A test for JDO API is missed.
              </fixme>
              <p>
                  Per default OJB use hsql as database, by changing the JdbcConnectionDescriptor
                  in the repository.xml file you can point to your specific RDBMS. Please
                  refer to this
                  <link href="site:platform">document for details</link>.
              </p>
  
              <p>
                  To run the multithreaded performance test call
                  </p>
              <source><![CDATA[
  ant perf-test]]></source>
              <p>
                  A typical output of this test looks like (OJB against hsql server, 2-tier, 100 MBit network):
                  </p>
              <source><![CDATA[
  [ojb] ========================================================
  [ojb]         OJB PERFORMANCE TEST SUMMARY
  [ojb] 10 concurrent threads, handle 2000 objects per thread
  [ojb]         - performance mode
  [ojb] ========================================================
  [ojb]      API  Period   Total  Insert   Fetch  Update  Delete
  [ojb]            [sec]   [sec]  [msec]  [msec]  [msec]  [msec]
  [ojb] --------------------------------------------------------
  [ojb]     JDBC  25.934  25.703   10843     342    9861    4656
  [ojb]       PB  26.461   26.21   11298     427    9889    4595
  [ojb]     ODMG  55.146  49.341   25979   11249    5852    6260
  [ojb] ========================================================
  
  [ojb] PerfTest takes 329 [sec]
              ]]></source>
              <p>
                  To change the test properties go to target
                  <code>perf-test</code>
                  in the
                  <code>build.xml</code> file and change the program parameter.
                  <br/>
                  The test needs five parameter:
                  <br/>- A comma separated list of the test implementation classes (no blanks!)
                  <br/>- The number of test loops
                  <br/>- The number of concurrent threads
                  <br/>- The number of managed objects per thread
                  <br/>- The desired test mode.
                  <code>false</code> means run in
                  performance mode,
                  <code>true</code> means run in stress mode
                  (useful for developer to check stability).
              </p>
          </section>
  
  
          <section>
              <title>How OJB compares to other O/R mapping tools?</title>
              <anchor id="compares-to-other"/>
              <p>
                  Many user ask this question and there is more than one answer. But OJB was
                  shipped with a simple performance framework which allows a rudimentarily
                  comparision of OJB with other (java-based) O/R mapping tools.
                  <br/>
                  Call
                  <code>ant perf-test-jar</code>
                  to build the jar file contain all necessary classes to set up a test with an
                  arbitrary O/R mapper. After build the
                  <code>db-ojb-XXX-performance.jar</code> can
                  be found in
                  <code>[db-ojb]/dist</code> directory.
              </p>
              <p>
                  <strong>Steps to set up the test:</strong>
                  </p>
                  <ul>
                      <li>Implement a class derived from
                          <code>org.apache.ojb.performance.PerfTest</code>
                      </li>
                      <li>Implement a class derived from
                          <code>org.apache.ojb.performance.PerfHandle</code>
                      </li>
                      <li>[If persistent objects used within your mapping tool must be derived from a special base
                          class or must be implement a special interface write your own persistent object class
                          by implementing
                          <code>org.apache.ojb.performance.PerfArticle</code> interface and override
                          method
                          <code>newPerfArticle()</code> in your PerfHandle implementation class.
                          <br/>
                          Otherwise the test use a default implementation of this interface.]
                      </li>
                  </ul>
              <p>
                  That's it!
              </p>
  
              <p>
                  You can find a example implementation called
                  <code>org.apache.ojb.broker.OJBPerfTest</code> in the test-sources directory
                  under
                  <code>[db-ojb]/src/test/org/apache/ojb</code> (when using source-distribution).
                  This implementation class is used to compare the PB-API, ODMG-API and native JDBC and
                  to test performance of the API implementations. See more section
                  <link href="#multithreaded-performance">multi-threaded performance</link>.
                  <code>OJBPerfTest</code>
                  is made up of inner classes. At each case two inner classes represent a test for
                  one api (as described above).
              </p>
  
              <p>
                  <strong>Run the test</strong>
                  <br/>
                  You have two possibilities to run the test:
                  <br/>
                  <br/>
                  a) Integration in the OJB build script
                  <br/>
                  Add the full qualified class name of your PerfTest implementation class
                  to the
                  <code>perf-test</code> target of the OJB
                  <code>build.xml</code>
                  file, add all necessary jar files to
                  <code>[db-ojb]/lib</code>. The working
                  directory of the test is
                  <code>[db-ojb]/target/test/ojb</code>.
  
                  <br/>
                  <br/>
                  b) Run PerfMain
                  <br/>
                  It's possible to run the test using
                  <code>org.apache.ojb.performance.PerfMain</code>.
                  </p>
              <source><![CDATA[
  java -classpath CLASSPATH org.apache.ojb.performance.PerfMain
  [comma separated list of PerfTest implementation classes, no blanks!]
  [number of test loops]
  [number of threads]
  [number of insert/fetch/delete loops per thread]
  [boolean - run in stress mode if set true,
  run in performance mode if set false, default false]
  
  For example:
  java -classpath CLASSPATH my.A_PerfTest,my.B_PerfTest 3 10 2000 false
              ]]></source>
              <p>
                  Take care of compareable configuration properties when run
                  performance tests with different O/R tools (caching, locking,
                  sequence key generation, connection pooling, ...).
              </p>
              <note>
                  <strong>Please, don't start flame wars</strong> by posting performance results to
                  mailing lists made with this simple test. This test was created for
                  OJB QA and to give a clue how good or bad OJB performs, NOT to start
                  discussion like
                  <em>XY is 12% faster then XZ</em>!!.
              </note>
          </section>
  
  
          <section>
              <title>What are the best settings for maximal performance?</title>
              <anchor id="maximal-performance"/>
              <p>
                  We don't know, that depends from the environment OJB runs (hardware, database, driver, application server, ...).
                  But there are some settings which affect the performance:
                  </p>
                  <ul>
                      <li>
                          The API you use, e.g. PB-api is much faster then the ODMG-api. See
                          <link href="faq.html#What are the differences between the PersistenceBroker API and the ODMG API? Which one should I use in my applications?">
                              which API</link> for more information.
                      </li>
                      <li>
                          ConnectionFactory implementation / Connection pooling. See
                          <link href="site:documentation/faq">connection pooling</link>
                          for more information.
                      </li>
                      <li>
                          PersistentField class implementation.See
                          <link href="ext:ojb.properties">OJB.properties section
                              'PersistentFieldClass'</link> for more information.
                      </li>
                      <li>
                          Used sequence manager implementation. See
                          <link href="site:sequence-manager">sequence manager</link> for
                          more information.
                      </li>
                      <li>
                          Use of batch mode (when supported by the DB). See
                          <link href="ext:repository.dtd">repository.dtd
                              element 'jdbc-connection-descriptor'</link>
                          for more information.
                      </li>
                      <li>
                          PersistenceBroker pool size. See
                          <link href="ext:ojb.properties">OJB.properties</link> for more information.
                      </li>
                  </ul>
              <p>
                  To test the different settings use the tests of the
                  <link href="#performance-test-suite">performance test suite</link>.
              </p>
          </section>
      </body>
  </document>
  
  
  
  
  
  
  
  1.1                  db-ojb/forrest/src/documentation/content/xdocs/docu/testsuite.xml
  
  Index: testsuite.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!--
    Copyright 2002-2004 The Apache Software Foundation
  
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
  
        http://www.apache.org/licenses/LICENSE-2.0
  
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
  -->
  <!-- @version $Id: testsuite.xml,v 1.1 2004/04/25 01:31:33 arminw Exp $ -->
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
  
  <document>
      <header>
          <title>OJB JUnit Test Suite</title>
          <authors>
              <person name="Armin Waibel" email="arminw@apache.org"/>
              <person name="Thomas Mahler" email="thma@apache.org"/>
          </authors>
      </header>
  
      <body>
          <section>
              <title>Introduction</title>
              <p>
                  Building an Object/Relational mapping tool with support for multiple API's
                  is really error prone. To create a solid and stable software, the most awful thing in
                  programmers life has to be done - Testing.
              </p>
              <p>
                  Quality assurance taken seriously! OJB and provide specific tests for each
                  supported API. Currently more than 600 test cases for regression tests exist.
                  As testing framework
                  <link href="ext:junit">JUnit</link> was used.
              </p>
          </section>
  
          <section>
              <title>How to run the Test Suite</title>
              <p>
                  If the
                  <link href="site:platform">platform depended settings</link> are done, the test suite
                  can be started with the ant target:
              </p>
              <source><![CDATA[
  ant junit]]></source>
              <p>
                  If compiling of the sources should be skipped use
                  </p>
       <source><![CDATA[
  ant junit-no-compile]]></source>
              <p>
                  If you did not manage to set up the target database with the
                  <code>ant prepare-testdb</code> you can use
                  </p>
                  <source><![CDATA[
  ant junit-no-compile-no-prepare]]></source>
              <p>
              to run the testsuite without generation of the test database
                  (and without compiling).
              </p>
              <p>
                  After running the regression tests
                  you should see a console output as follows:
              </p>
              <source><![CDATA[
  junit-no-compile-no-prepare:
  [junit] Running org.apache.ojb.broker.AllTests
  [junit] Tests run: 382, Failures: 0, Errors: 0, Time elapsed: 50,843 sec
  
  [junit] Running org.apache.ojb.odmg.AllTests
  [junit] Tests run: 193, Failures: 0, Errors: 0, Time elapsed: 16,243 sec
  
  [junit] Running org.apache.ojb.soda.AllTests
  [junit] Tests run: 3, Failures: 0, Errors: 0, Time elapsed: 8,392 sec
  
  [junit] Running org.apache.ojb.otm.AllTests
  [junit] Tests run: 79, Failures: 0, Errors: 0, Time elapsed: 21,871 sec
  junit-no-compile:
  junit:
  BUILD SUCCESSFUL
  Total time: 3 minutes 58 seconds]]></source>
              <p>
                  We aim at shipping that releases have no failures and errors in the regression tests!
                  If the Junit tests report errors or failures something does not
                  work properly! There may be several reasons:
              </p>
              <ul>
                  <li>
                      You made a mistake in configuration (OJB was shipped with settings pass all tests).
                      See <link href="site:platform">platform</link>,
                      <link href="site:ojb-properties">OJB.properties</link>,
                      <link href="site:repository">repository file</link>,
                      <link href="site:jdbc-types"></link>.
                  </li>
                  <li>Your database doesn't support specific features used by the tests</li>
                  <li>Evil hex</li>
                  <li>Bug in OJB</li>
              </ul>
              <p>
                  JUnit writes a <em>log-file</em> for each tested API. You can find the logs
                  under <code>[db-ojb]/target/test</code>. The log files named like <code>tests-XXX.txt</code>.
                  The test logs show in detail what's going wrong.
              </p>
              <p>
                  In such a case please check again if you followed all the above
                  steps. If you still have problems you might post a request to
                  the OJB user mailinglist.
              </p>
          </section>
  
          <section>
              <title>What about known issues?</title>
              <p>
                  All major known issues are listed in the <link href="ext:ojb/release-notes"></link>.
                  The tests for open bugs will be skipped on released versions. It is possible to enable
                  these tests to see failing test cases by set a flag in <code>[db-ojb]/build.properties</code>
                  file:
              </p>
              <source><![CDATA[
  ###
  # If 'true', junit tests marked as known issue in the junit-test
  # source code (see OJBTestCase class for more detailed info) will be
  # skipped. Default value is 'true'. For development 'false' is recommended,
  # because this will show unsolved problems.
  OJB.skip.issues=true]]></source>
          </section>
      </body>
  </document>
  
  
  1.3       +9 -4      db-ojb/forrest/src/documentation/content/xdocs/site.xml
  
  Index: site.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/site.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- site.xml	23 Apr 2004 19:17:46 -0000	1.2
  +++ site.xml	25 Apr 2004 01:31:33 -0000	1.3
  @@ -36,7 +36,7 @@
           <features label="Features" href="features.html" description="OJB features"/>
           <faq label="FAQ's" href="docu/faq.html" description="Frequently Asked Questions"/>
           <status label="Status" href="status.html" description="Project status page"/>
  -        <release-notes label="Release-Notes" href="release-notes.txt" description="Project release-notes"/>
  +        <release-notes label="Release-Notes" href="ext:release-notes" description="Project release-notes"/>
           <wiki label="Wiki" href="http://wiki.apache.org/db-ojb"/>
           <mail-lists label="Mail lists" href="mail-lists.html"/>
           <mail-archives label="Mail Archives" href="mail-archives.html"/>
  @@ -83,7 +83,7 @@
           </tutorials>
   
           <guides label="Reference Guides">
  -            <platform label="Platform settings" href="platform.html" description=""/>
  +            <platform label="Platform settings" href="platforms.html" description=""/>
               <ojb-properties label="OJB.properties File" href="ojb-properties.html" description=""/>
               <jdbc-types label="JDBC Types" href="jdbc-types.html" description="">
                   <jdbc-mapping href="#jdbc-mapping"/>
  @@ -134,7 +134,7 @@
                   <distributed-locking href="#distributed-locking"/>
               </lock-manager>
               <xdoclet label="XDoclet Module" href="xdoclet-module.html" description=""/>
  -            <performance label="OJB Performance" href="performance.html" description=""/>
  +            <performance label="Performance" href="performance.html" description=""/>
           </guides>
   
           <howto label="Howto's">
  @@ -145,6 +145,10 @@
               <clustering label="Work in clustered environment" href="howto-work-with-clustering.html" description=""/>
               <stored-procedures label="Work with Stored Procedures" href="howto-work-with-stored-procedures.html" description=""/>
           </howto>
  +        <testing label="Testing">
  +            <test-suite label="Test Suite" href="testsuite.html"/>
  +            <write-test label="Write Tests" href="testwrite.html"/>
  +        </testing>
       </documentation>
   
       <all label="All the site" tab="home">
  @@ -231,6 +235,7 @@
               </jdo>
           </sun>
           <odmg-group href="http://www.odmg.org/"/>
  +        <junit href="http://www.junit.org"/>
       </external-refs>
   
   </site>
  
  
  
  1.2       +2 -2      db-ojb/forrest/src/documentation/content/xdocs/status.xml
  
  Index: status.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/status.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- status.xml	22 Apr 2004 19:29:51 -0000	1.1
  +++ status.xml	25 Apr 2004 01:31:33 -0000	1.2
  @@ -45,7 +45,7 @@
               <p>
                   The ODMG API implementation is stable, but there some known
                   issues - see
  -                <link href="site:release-notes">release-notes</link>
  +                <link href="ext:release-notes">release-notes</link>
               </p>
               <note>
                   OQL is currently not
  
  
  
  1.2       +6 -5      db-ojb/forrest/src/documentation/content/xdocs/features.xml
  
  Index: features.xml
  ===================================================================
  RCS file: /home/cvs/db-ojb/forrest/src/documentation/content/xdocs/features.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- features.xml	22 Apr 2004 19:29:51 -0000	1.1
  +++ features.xml	25 Apr 2004 01:31:33 -0000	1.2
  @@ -52,6 +52,11 @@
                       ConnectionManager, IndirectionHandler, SQLGenerator, JdbcAccess and so on.
                   </li>
                   <li>
  +                    Quality assurance taken seriously: More than
  +                    <link href="site:test-suite"><em>600 JUnit-TestCases</em></link> for
  +                    regression tests. JUnit tests integrated into the build scripts.
  +                </li>
  +                <li>
                       Mapping support for 1:1, 1:n and m:n
                       <link href="site:basic-technique">associations</link>.
                   </li>
  @@ -167,10 +172,6 @@
                               when using multiple OJB servers.
                           </li>
                       </ul>
  -                </li>
  -                <li>
  -                    Quality assurance taken seriously: More than <em>600 JUnit-TestCases</em> for
  -                    regression tests. JUnit tests integrated into the build scripts.
                   </li>
                   <li>
                       Comes along with fully functional demo applications running against
  
  
  

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