More javadoc.

[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..1ea78e255d6e9e6bb1c712431c4dac3085637de0 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
@@ -72,6 +72,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 {@link DatabaseBuilder#DB_CAPABILITIES_PROP}
+ * </p>
+ * 
  * 
  * <a name="db-utils">
  *   <h2>Executing code within a JDBC transaction</h2>
@@ -189,26 +195,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;
-