code style improvements.

[utils] / test / enterprise / src / main / java / org / wamblee / support / persistence / package-info.java

diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/package-info.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/package-info.java
index d38be5796fed215c5341d165ce549af23a5d4bbd..979dde6f7c0189c5d4a53f709d610403218de996 100644 (file)
--- a/test/enterprise/src/main/java/org/wamblee/support/persistence/package-info.java
+++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/package-info.java
@@ -42,7 +42,7 @@
  * </ul>
  * 
  * <p>
- *   See the <a href="#design-overview">design overview</a> for a an overview of the design.  
+ *   See also the <a href="#design-overview">design overview</a>.  
  * </p>
  * 
  * <a name="db-basic">
@@ -53,9 +53,13 @@
  *      Database db = DatabaseBuilder.getDatabase();
  *      DataSource dataSource = db.start();
  * </pre>
+ * <p>
  * If nothing is specified in the user's environment, an inmemory database is started (derby).
- * Using the datasource is just standard JDBC now. 
- * Stopping the database
+ * Using the datasource is just standard JDBC now.
+ * </p>
+ * <p>
+ * After a test it is good practice to stop the database:
+ * </p>
  * <pre>
  *      db.stop();
  * </pre>
@@ -72,6 +76,12 @@
  * This also requires a number of environment variables or system properties to be set, 
  * see {@link ExternalDatabase}. 
  * 
+ * <p>
+ * However, the most convenient way to set the capabilities is usually to set a system property or environment 
+ * variable see the javadocs of {@link DatabaseBuilder}. and 
+ * specifically <code>DatabaseBuilder.DB_CAPABILITIES_PROP</code>
+ * </p>
+ * 
  * 
  * <a name="db-utils">
  *   <h2>Executing code within a JDBC transaction</h2>
@@ -99,7 +109,8 @@
  *   <h2>Using DB Unit in your tests</h2>
  * </a>
  * 
- * <p>To work with <a href="http://dbunit.org">DBUnit</a>, {@link DatabaseUtils#createDbTester(org.dbunit.dataset.filter.ITableFilterSimple)}
+ * <p>To work with <a href="http://dbunit.org">DBUnit</a>, 
+ * <code>DatabaseUtils#createDbTester(org.dbunit.dataset.filter.ITableFilterSimple)</code>
  * must be used passing it in the tables to use in the form of a {@link org.dbunit.dataset.filter.ITableFilterSimple}
  * object. </p>
  * 
@@ -123,7 +134,7 @@
  *    want to test. 
  * </p>
  * <p>Second step is to make sure that all entities are listed explicitly in your
- *    <pre>persistence.xml</pre>. Currently, class path scanning appears to fail when
+ *    <code>persistence.xml</code>. Currently, class path scanning appears to fail when
  *    run from junit. 
  *    Specifying all entities explicitly is not necessarily a bad thing as it is also more efficient. 
  * </p>
@@ -162,8 +173,8 @@
  * get them directly from the <code>JPATester</code> after initializing it: 
  * <pre>
  *      builder = jpaTester.getJpaBuilder();
- *      dbtester = jpaTester.getDbUtils().createDbTester(new MyTables());
  *      dbutils = jpaTester.getDbUtils();
+ *      dbtester = dbutils.createDbTester(new MyTables());
  * </pre>
  * 
  * <a name="db-jpa-services">
@@ -189,26 +200,50 @@
  * </p> 
  * 
  * <a name="design-overview">
- *   <h2>design overview</h2>
+ *   <h2>Design overview</h2>
  * </a>
  * 
- * <h3>Database transaparency</h3>
- * 
- * <h3>Testing using JDBC and DBUnit</h3> 
+ * <h3>Database transparency</h3>
  * 
+ * <br/>
+ * <img src="doc-files/Class_Diagram__org.wamblee.support.persistence__database.jpg"
+ *   alt="database"/>
+ * </br/>
+ * <p>
+ *   {@link DatabaseProvider} uses <code>java.util.ServiceLoader</code> to find all implementations
+ *   of {@link DatabaseProvider} on the classpath. It then asks the database providers whether
+ *   they support the required capabilities (by default inmemory), and the first provider that 
+ *   supports the capabilities is used to create the database. 
+ * </p>
+ * <p>
+ *   Note that the <code>Database</code> interface is not intended to always create a database. 
+ *   It will do so for {@link DerbyDatabase} (inmemory), but with {@link ExternalDatabase}
+ *   it simply connects to an external database based on system properties or environment 
+ *   variables. 
+ * </p>
+ *  
  * <h3>JPA tester overview</h3>
  * 
+ * <br/>
+ * <img src="doc-files/Class_Diagram__org.wamblee.support.persistence__jpatester.jpg"
+ *   alt="database"/>
+ * </br/>
+ * 
+ * <p><code>JPATester</code> is responsible for:</p>
+ * <ul>
+ *   <li> Starting or connecting to a database, using {@link DatabaseBuilder}. 
+ *   </li>
+ *   <li>  Registering the acquired datasource in JNDI by first stubbing JNDI
+ *       using {@link org.wamblee.support.jndi.StubInitialContextFactory}. 
+ *   </li>
+ *   <li>  Creating the {@link JPABuilder} that will do the JPA heavy lifting. 
+ *   </li>
+ *   <li> Creating the {@link DatabaseUtils} for JDBC and DBUnit testing. 
+ *   </li>
+ * </ul> 
  * 
  * 
  */
 package org.wamblee.support.persistence;
 
-import static org.mockito.Mockito.*;
-
-import javax.persistence.EntityManager;
-
-import org.junit.Before;
-import org.wamblee.support.persistence.JpaBuilder.JpaUnitOfWork;
-import org.wamblee.support.persistence.TransactionProxyFactoryTestBase.Service;
-