You are viewing a plain text version of this content. The canonical link for it is here.
Posted to ojb-dev@db.apache.org by ar...@apache.org on 2004/04/25 03:31:33 UTC
cvs commit: db-ojb/forrest/src/documentation/content/xdocs site.xml status.xml features.xml
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 "Named Roots Map". 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>"
<strong>There is no such thing as a free lunch."</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