From: Erik Brakkee <erik@brakkee.org>
Date: Mon, 5 Jul 2010 20:38:58 +0000 (+0000)
Subject: More javadoc.
X-Git-Tag: wamblee-utils-0.7~355
X-Git-Url: http://wamblee.org/gitweb/?a=commitdiff_plain;h=bd197313c85d3ee6336e7e7cbf7ff706247df9b4;p=utils

More javadoc.
---

diff --git a/test/enterprise/src/main/java/org/wamblee/support/jndi/StubInitialContextFactory.java b/test/enterprise/src/main/java/org/wamblee/support/jndi/StubInitialContextFactory.java
index d65968a2..158bd6d8 100644
--- a/test/enterprise/src/main/java/org/wamblee/support/jndi/StubInitialContextFactory.java
+++ b/test/enterprise/src/main/java/org/wamblee/support/jndi/StubInitialContextFactory.java
@@ -27,11 +27,17 @@ import javax.naming.spi.InitialContextFactory;
  * 
  * See {@link #bind(String, Object)} to resp. register the initial context.
  * 
- * To bind objects in the JNDI tree simply use the standard JNDI api: <code>
+ * To start mocking the JNDI tree, call {@link #register()}. 
+ * 
+ * To bind objects in the JNDI tree simply use the standard JNDI api: 
+ * <pre>
  *   InitialContext context = new InitialContext();
  *   MyClass myObj = ...; 
  *   context.bind("a/b", myObj); 
- * </code>
+ * </pre>
+ * 
+ * When finished with a test case, call {@link #unregister()} to unregister the 
+ * JNDI tree again. 
  */
 public class StubInitialContextFactory implements InitialContextFactory {
 
diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseBuilder.java b/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseBuilder.java
index 6f495698..ae7cd28a 100644
--- a/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseBuilder.java
+++ b/test/enterprise/src/main/java/org/wamblee/support/persistence/DatabaseBuilder.java
@@ -60,7 +60,7 @@ public class DatabaseBuilder {
      * Environmment variable by which capabilities of the requested database can
      * be defined
      */
-    private static final String DB_CAPABILITIES_PROP = "TEST_DB_CAPABILITIES";
+    public static final String DB_CAPABILITIES_PROP = "TEST_DB_CAPABILITIES";
 
     private static ServiceLoader<DatabaseProvider> LOADER = 
         ServiceLoader.load(DatabaseProvider.class);
diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/doc-files/Class_Diagram__org.wamblee.support.persistence__database.jpg b/test/enterprise/src/main/java/org/wamblee/support/persistence/doc-files/Class_Diagram__org.wamblee.support.persistence__database.jpg
new file mode 100644
index 00000000..f8e6cede
Binary files /dev/null and b/test/enterprise/src/main/java/org/wamblee/support/persistence/doc-files/Class_Diagram__org.wamblee.support.persistence__database.jpg differ
diff --git a/test/enterprise/src/main/java/org/wamblee/support/persistence/doc-files/Class_Diagram__org.wamblee.support.persistence__jpatester.jpg b/test/enterprise/src/main/java/org/wamblee/support/persistence/doc-files/Class_Diagram__org.wamblee.support.persistence__jpatester.jpg
new file mode 100644
index 00000000..965e92b4
Binary files /dev/null and b/test/enterprise/src/main/java/org/wamblee/support/persistence/doc-files/Class_Diagram__org.wamblee.support.persistence__jpatester.jpg differ
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 d38be579..1ea78e25 100644
--- 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;
-