update javadocs, minor cleanups

git-svn-id: https://svn.code.sf.net/p/jackcess/code/jackcess/branches/mutateops@1030 f203690c-595d-4dc9-a70b-905162fa7fd2

TODO.txt

@@ -2,8 +2,6 @@ Missing pieces:
 
 - fix long text index entries (for new general sort order)
   * ???
-- implement foreign key index creation & relationship creation
-  * MEDIUM
 - implement table creation w/ complex columns
   * MEDIUM
 - implement table, column, index renaming
@@ -19,13 +17,3 @@ Rename:
 - Table - update table def, queries, relationships, complex tables?
 - Column - update table def, queries, relationships, complex tables?
 - Index - update table def
-
-Index add (fk impl)
-- Database.addIndex(IndexBuilder) - use TableCreator internal
-  - add indexes separately from adding fk info, (backing indexes need to be
-    added first)
-    - require baking indexes to be created first (does MSAccess?)
-    - need to populate index after creation! populate first, then add?
-  - add relationships
-- flush all non-system tables from DbImpl._tableCache (references to old table
-  impls)

src/main/java/com/healthmarketscience/jackcess/ColumnBuilder.java

@@ -34,6 +34,7 @@ import com.healthmarketscience.jackcess.impl.TableUpdater;
  * existing Table using the {@link #addToTable(Table)} method.
  *
  * @author James Ahlborn
+ * @see TableBuilder
  * @usage _general_class_
  */
 public class ColumnBuilder {

src/main/java/com/healthmarketscience/jackcess/IndexBuilder.java

@@ -35,6 +35,7 @@ import com.healthmarketscience.jackcess.impl.TableUpdater;
  * existing Table using the {@link #addToTable(Table)} method.
  *
  * @author James Ahlborn
+ * @see TableBuilder
  * @usage _general_class_
  */
 public class IndexBuilder 

src/main/java/com/healthmarketscience/jackcess/RelationshipBuilder.java

@@ -27,9 +27,24 @@ import com.healthmarketscience.jackcess.impl.RelationshipImpl;
 /**
  * Builder style class for constructing a {@link Relationship}, and,
  * optionally, the associated backing foreign key (if referential integrity
- * enforcement is enabled).
+ * enforcement is enabled).  A Relationship can only be constructed for
+ * {@link Table}s which already exist in the {@link Database}.  Additionally,
+ * if integrity enforcement is enabled, there must already be a unique index
+ * on the "from" Table for the relevant columns (same requirement as MS
+ * Access).
+ * <p/>
+ * Example:
+ * <pre>
+ *   Relationship rel = new RelationshipBuilder("FromTable", "ToTable")
+ *     .addColumns("ID", "FK_ID")
+ *     .setReferentialIntegrity()
+ *     .setCascadeDeletes()
+ *     .toRelationship(db);
+ * </pre>
  *
  * @author James Ahlborn
+ * @see TableBuilder
+ * @usage _general_class_
  */
 public class RelationshipBuilder 
 {

src/main/java/com/healthmarketscience/jackcess/TableBuilder.java

@@ -45,6 +45,9 @@ import com.healthmarketscience.jackcess.impl.TableCreator;
  * </pre>
  *
  * @author James Ahlborn
+ * @see ColumnBuilder
+ * @see IndexBuilder
+ * @see RelationshipBuilder
  * @usage _general_class_
  */
 public class TableBuilder {

src/main/java/com/healthmarketscience/jackcess/impl/DatabaseImpl.java

@@ -1021,8 +1021,9 @@ public class DatabaseImpl implements Database
    * Create a new table in this database
    * @param name Name of the table to create
    * @param columns List of Columns in the table
-   * @usage _general_method_
+   * @deprecated use {@link TableBuilder} instead
    */
+  @Deprecated
   public void createTable(String name, List<ColumnBuilder> columns)
     throws IOException
   {
@@ -1034,8 +1035,9 @@ public class DatabaseImpl implements Database
    * @param name Name of the table to create
    * @param columns List of Columns in the table
    * @param indexes List of IndexBuilders describing indexes for the table
-   * @usage _general_method_
+   * @deprecated use {@link TableBuilder} instead
    */
+  @Deprecated
   public void createTable(String name, List<ColumnBuilder> columns,
                           List<IndexBuilder> indexes)
     throws IOException

src/test/java/com/healthmarketscience/jackcess/DatabaseTest.java

@@ -25,7 +25,6 @@ import java.text.SimpleDateFormat;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Calendar;
-import java.util.Collections;
 import java.util.Date;
 import java.util.HashSet;
 import java.util.LinkedHashMap;
@@ -63,7 +62,7 @@ public class DatabaseTest extends TestCase
       Database db = create(fileFormat);
 
       try {
-        ((DatabaseImpl)db).createTable("test", Collections.<ColumnBuilder>emptyList());
+        new TableBuilder("test").toTable(db);
         fail("created table with no columns?");
       } catch(IllegalArgumentException e) {
         // success
@@ -598,9 +597,9 @@ public class DatabaseTest extends TestCase
         columns.add(new ColumnBuilder(colName, DataType.TEXT).toColumn());
       }
 
-      ((DatabaseImpl)db).createTable("test", columns);
-
-      Table t = db.getTable("test");
+      Table t = new TableBuilder("test")
+        .addColumns(columns)
+        .toTable(db);
 
       List<String> row = new ArrayList<String>();
       Map<String,Object> expectedRowData = new LinkedHashMap<String, Object>();