1) Usage 
It is assumed a user operates on Cayenne checked out from CVS
- Build Cayenne distribution.
- Build Regression like "ant -file build-regression.xml"
- Make sure an Oracle driver is in the classpath (check for ojdbc14.jar, nls_charset12.jar or likes).
  If it is not, an ConfigException will be thrown.
- Create or adjust existing cayenne.xml project, 'datanode'.xml (see src/regression/samples)
  The database schema must exist and, preferably, be empty.
- Create or modify existing config file
  (see src/regression/samples/schema-test.config, schema-test1.config)
- Put the config file into the working directory (".") or pass its path to the executable.
- Start regression.bat from the command line (to see useful output).
  regression.bat is located in the bin directory of the Cayenne distribution.

Note: Regression always tries to clean the schema up after itself. But if it is aborted from the outside,
chances are some tables and sequences will be left in the schema. In such a case one can use the recorded
drop_schema.sql to delete them correctly before the next launch.

2) Supported Test Features
- Random schema generation: complex referential integrity constaints, NOT NULL,
  auto pk generation (sequences), dependent pks
- Generation of DataMaps, new DataObject types
- Random insertions of data objects connected via relationships (reflexive too)
- Random deletions and related updates of referential constraints
- Memory and time metering
- Basic logging facilities: create_schema.sql, drop_schema.sql, DataMap.xml
- Automatic schema clean-up
- Various parameters to configure the above mentioned features


3) Principles of Work

Created the functional Oracle-oriented prototype of the Cayenne testing app
dwelling in the package org.objectstyle.cayenne.test. Its purpose is to 
automatically generate a set of random database schemas and quality of the 
Cayenne's commit against them. A short description of the steps follows:

  1. A random Oracle schema is generated. Table count, max. count of foreign
  keys a table can have, max count of the tables referencing a table, seed of
  the randomizer, Oracle database connection, and name of the schema are configured
  
  2. A data map is created for the schema generated and attached to the data node
  representing the database connection.

  3. The data domain having been configured by steps 1. 2., a robot randomly
  creates and registers data objects for the data map in the data context.
  It also establishes relationships among them accordingly to the meta data
  in the data map.
  (Note: deletion functionality has recently been added)
  
  4. The modified context is committed to the database.
  
Principles a schema is built on:
  1. Schema's name must be the name of the default connected user's schema.
  2. Preferably it should be empty in order for newly generated tables and
  sequences not to interfere with the existing ones.
  3. All the tables created have primary keys either autogenerated (for
  such tables sequences are created) or dependent. Most of the tables
  have enabled 'NOT NULL' foreign keys. Thus columns of the tables can be
  primary keys, foreign keys, or both in the case of dependent tables
  (like many-to-many tables-relations, and such) of the type INTEGER.
  All of them are 'NOT NULL' and do not have default values.
  4. The graph of the referential relations is always acyclic.
  5. The produced schema is usually quite complex in the sense of referential
  integrity and complies with the principles of the theory of relational
  databases.
  
To start the app one must execute a command line like:
java org.objectstyle.cayenne.test.Main path_to_config_file
The config file contains parameters to tune the app. For the details
see doc/test/schema-test.config. If the command line argument is
omitted the app tries to find "./schema-test.config".
Several schemas can be created and several commits can be performed
per schema during one run of the app. Quite descriptive information along
with the create and drop scripts and the data map are stored as files.
The important info is outputted to the console as well so regularly it is 
advised to run java instead of javaw. Also, it is advised to
tune the memory heap of the JVM like java -Xms150m -Xmx150m in case one would
like to run intensive tests with lots of tables and data objects.

Several hundreds of random schemas of 10, 25, 30, 50, and 100 tables were tested
by the app on Oracle 9.2. All the tests succeeded working with the new commit.
The old commit failed on the same tests. At the same time Cayenne turned out
very stable and easily runtime reconfigurable and did not show any notable
memory or database resource (like open cursors) leakages even when it was 
created 100 schemas, 50 tables per schema, 30 data objects per table, 20 commits
per schema. Moreover the garbage collector could very effectively clean the 
memory from the stale data, which was monitored very attentively.

Another note - the robot might evolve into a fully functional automatic testing 
tool for existing schemas to measure and qualify how well a given schema and 
data map work on various sorts of data manipulation in the extensively loaded 
environments. Such a tool would be precious in the cases when multi-user web or
intranet application performance must be tested as it is known too many
serious and hardly identified bottle-necks occur in the communication of
an app and database server.