How to run entity-persistence tests
-----------------------------------
The entity-persistence tests are currently configured to build with maven, and to run with ant.

1. Ensure the entity-persistence module has successfully built

2. To clean the view run "maven clean"

3. Edit the build.properties file.  Change the following entries:

jdbc.driver.jar - point this to your jdbc driver
db.driver - the name of the driver class
db.url - the url to your database
db.user - your database username
db.pwd - your database password

Adding these same settings to a build.properties in your user's home directory will also work.

4. To build the testing run "maven build". Note: The maven "build" target depends on the changes to the build.properties files to populate the persistence.xml files used for the testing persistence units.

5. Prepare to run ant by configuring your classpath to include a junit jar file.  An appropriate junit.jar can be found in ../appserv-tests/lib. The ant tests make use of a junit task and ant requires that junit be on the classpath for this task to run.

6. Run "ant test"

Note: As of February 21, 2006, the persistence.xml files stored in the config directories are no longer changed by the build script.  Instead, changes occur in a temporary directory prior the building the testing jar files.  As a result, users that check out the config directories after Februrary 21, 2006, should not have to worry about accidentally changing the persistence.xml files used in testing.


Drop all tables of database
----------------------------
If you want to drop *all* tables of your database to run test on a clean database, do like below. 

$ ant clean-db

This will be required in some cases if existing tables or foreign key contraints cause test failures.


-------------------------------
BEGIN: TEST PACKAGING STRUCTURE 
-------------------------------
Starting from 7 Oct 2006, the packaging of tests have change so that we can
avoid bugs like GF #1074, 1131 etc. The documentation below describes the new
structure. Please update it when yo make any change. Read the build.xml
for more information.

1. What are the jar files produced?
-----------------------------------
build produces *6* jar files, viz:
toplink-essentials-tests.jar,
toplink-essentials-annotation-model-tests.jar,
toplink-essentials-xml-only-model-tests.jar,
toplink-essentials-xml-merge-model-tests.jar,
toplink-essentials-ddl-generation-tests.jar and
toplink-essentials-validation-tests.jar.

2. Where are the JUnit classes packaged?
----------------------------------------
*toplink-essentials-tests.jar* contains *only* JUnit test and framework 
classes. i.e. t contains:
oracle/toplink/essentials/testing/tests and 
oracle/toplink/essentials/testing/framework 
packages. It does not contain any model classes or XML files. This is not 
a persistence archive.

3. Where are the model classes packaged?
----------------------------------------
Model classes are packaged in five different files:
a) *toplink-essentials-annotation-model-tests.jar* includes 
oracle/toplink/essentials/testing/models/ classes,
but excludes 
oracle/toplink/essentials/testing/models/cmp3/xml/** and 
oracle/toplink/essentials/testing/models/cmp3/validationfailed/**.

b) *toplink-essentials-xml-only-model-tests.jar* includes 
oracle/toplink/essentials/testing/models/cmp3/xml/, 
but excludes 
oracle/toplink/essentials/testing/models/cmp3/xml/merge/**.

c) *toplink-essentials-xml-merge-model-tests.jar* includes 
oracle/toplink/essentials/testing/models/cmp3/xml/merge/, 
but excludes 
oracle/toplink/essentials/testing/models/cmp3/xml/merge/inherited/**.

d) *toplink-essentials-ddl-generation-tests.jar* includes 
oracle/toplink/essentials/testing/models/cmp3/xml/merge/inherited/**.

e) *toplink-essentials-validation-tests.jar* includes
oracle/toplink/essentials/testing/models/cmp3/validationfailed/.

4. Where are the persistence.xml files packaged?
------------------------------------------------
There are three persistence.xml files. 
a) config/META-INF/persistence.xml is packaged in toplink-essentials-annotation-model-tests.jar. So, this jar is a PU Root. This persistence.xml uses <jar-file>
 element in persistence.xml as shown below to reference model classes from other
 two jars:
       <jar-file>toplink-essentials-xml-only-model-tests.jar</jar-file>
       <jar-file>toplink-essentials-xml-merge-model-tests.jar</jar-file>

b) config/ddl-generation-testmodel/META-INF/persistence.xml is packaged in
toplink-essentials-ddl-generation-tests.jar.

c) config/validation-failed-testmodel/META-INF/persistence.xml is packaged in
toplink-essentials-validation-tests.jar. 

5. How are the mapping XML documents packaged?
----------------------------------------------
Mapping files are distributed among all the jar files as shown below:
toplink-essentials-annotation-model-tests.jar:
META-INF/orm.xml

toplink-essentials-ddl-generation-tests.jar:
META-INF/merge-inherited-beers.xml
META-INF/merge-inherited-certification.xml
META-INF/merge-inherited-consumer.xml
META-INF/merge-inherited-superclasses.xml

toplink-essentials-tests.jar:
none
toplink-essentials-validation-tests.jar:
none
toplink-essentials-xml-merge-model-tests.jar:
META-INF/incomplete-nonowning-entity-mappings.xml
META-INF/incomplete-owning-entity-mappings.xml
META-INF/orm-annotation-merge-advanced-entity-mappings.xml
META-INF/orm-annotation-merge-relationships-entity-mappings.xml

toplink-essentials-xml-only-model-tests.jar:
META-INF/orm.xml (inheritance-entity-mappings.xml is renamed as orm.xml)
META-INF/advanced-entity-mappings.xml
META-INF/inherited-entity-mappings.xml
META-INF/relationships-entity-mappings.xml
META-INF/unidirectional-relationships-entity-mappings.xml

6. Special Notes:
------------------
To test issue #1131 and #589, we rename inheritance-entity-mappings.xml and
package it as orm.xml in toplink-essentials-xml-only-model-tests.jar.

-------------------------------
END: TEST PACKAGING STRUCTURE 
-------------------------------
