expand javadocs for core interfaces

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

18 files changed, 111 insertions, 48 deletions

diff --git a/src/java/com/healthmarketscience/jackcess/Column.java b/src/java/com/healthmarketscience/jackcess/Column.java
index 82268e5..86e8ab0 100644
--- a/src/java/com/healthmarketscience/jackcess/Column.java
+++ b/src/java/com/healthmarketscience/jackcess/Column.java
@@ -27,7 +27,11 @@ import com.healthmarketscience.jackcess.complex.ComplexColumnInfo;
 import com.healthmarketscience.jackcess.complex.ComplexValue;
 
 /**
- * Access database column definition
+ * Access database column definition.  A {@link Table} has a list of Column
+ * instances describing the table schema.
+ * <p>
+ * A Column instance is not thread-safe (see {@link Database} for more
+ * thread-safety details).
  *
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/ColumnBuilder.java b/src/java/com/healthmarketscience/jackcess/ColumnBuilder.java
index 90ddc34..0154ce1 100644
--- a/src/java/com/healthmarketscience/jackcess/ColumnBuilder.java
+++ b/src/java/com/healthmarketscience/jackcess/ColumnBuilder.java
@@ -36,7 +36,8 @@ import com.healthmarketscience.jackcess.impl.JetFormat;
 import com.healthmarketscience.jackcess.impl.DatabaseImpl;
 
 /**
- * Builder style class for constructing a Column.
+ * Builder style class for constructing a {@link Column}.  See {@link
+ * TableBuilder} for example usage.
  *
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/Cursor.java b/src/java/com/healthmarketscience/jackcess/Cursor.java
index 5c6d12f..f84f8dd 100644
--- a/src/java/com/healthmarketscience/jackcess/Cursor.java
+++ b/src/java/com/healthmarketscience/jackcess/Cursor.java
@@ -29,17 +29,23 @@ import com.healthmarketscience.jackcess.util.ErrorHandler;
 import com.healthmarketscience.jackcess.util.IterableBuilder;
 
 /**
- * Manages iteration for a Table.  Different cursors provide different methods
- * of traversing a table.  Cursors should be fairly robust in the face of
- * table modification during traversal (although depending on how the table is
- * traversed, row updates may or may not be seen).  Multiple cursors may
+ * Manages iteration for a {@link Table}.  Different cursors provide different
+ * methods of traversing a table.  Cursors should be fairly robust in the face
+ * of table modification during traversal (although depending on how the table
+ * is traversed, row updates may or may not be seen).  Multiple cursors may
  * traverse the same table simultaneously.
+ * <p/>
+ * Basic cursors will generally iterate table data in the order it appears in
+ * the database and searches will require scanning the entire table.
+ * Additional features are available when utilizing an {@link Index} backed
+ * {@link IndexCursor}.
  * <p>
  * The {@link CursorBuilder} provides a variety of static utility methods to
  * construct cursors with given characteristics or easily search for specific
  * values as well as friendly and flexible construction options.
  * <p>
- * Is not thread-safe.
+ * A Cursor instance is not thread-safe (see {@link Database} for more
+ * thread-safety details).
  *
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/CursorBuilder.java b/src/java/com/healthmarketscience/jackcess/CursorBuilder.java
index 9485090..26f3f92 100644
--- a/src/java/com/healthmarketscience/jackcess/CursorBuilder.java
+++ b/src/java/com/healthmarketscience/jackcess/CursorBuilder.java
@@ -43,9 +43,21 @@ import com.healthmarketscience.jackcess.util.ColumnMatcher;
 
 
 /**
- * Builder style class for constructing a Cursor.  By default, a cursor is
- * created at the beginning of the table, and any start/end rows are
+ * Builder style class for constructing a {@link Cursor}.  By default, a
+ * cursor is created at the beginning of the table, and any start/end rows are
  * inclusive.
+ * <p/>
+ * Simple example traversal:
+ * <pre>
+ *   for(Row row : table.newCursor().toCursor()) {
+ *     // ... process each row ...
+ *   }
+ * </pre>
+ * <p/>
+ * Simple example search:
+ * <pre>
+ *   Row row = CursorBuilder.findRow(table, Collections.singletonMap(col, "foo"));
+ * </pre>
  *
  * @author James Ahlborn
  */
@@ -325,14 +337,13 @@ public class CursorBuilder {
    * types of indexes do not include all entries (namely, some indexes ignore
    * null entries, see {@link Index#shouldIgnoreNulls}).
    * 
-   * @param table the table over which this cursor will traverse
    * @param index index for the table which will define traversal order as
    *              well as enhance certain lookups
    */
-  public static IndexCursor createCursor(Table table, Index index)
+  public static IndexCursor createCursor(Index index)
     throws IOException
   {
-    return table.newCursor().setIndex(index).toIndexCursor();
+    return index.getTable().newCursor().setIndex(index).toIndexCursor();
   }
   
   /**
@@ -343,7 +354,6 @@ public class CursorBuilder {
    * types of indexes do not include all entries (namely, some indexes ignore
    * null entries, see {@link Index#shouldIgnoreNulls}).
    * 
-   * @param table the table over which this cursor will traverse
    * @param index index for the table which will define traversal order as
    *              well as enhance certain lookups
    * @param startRow the first row of data for the cursor (inclusive), or
@@ -351,11 +361,11 @@ public class CursorBuilder {
    * @param endRow the last row of data for the cursor (inclusive), or
    *               {@code null} for the last entry
    */
-  public static IndexCursor createCursor(Table table, Index index,
+  public static IndexCursor createCursor(Index index,
                                          Object[] startRow, Object[] endRow)
     throws IOException
   {
-    return table.newCursor().setIndex(index)
+    return index.getTable().newCursor().setIndex(index)
       .setStartRow(startRow)
       .setEndRow(endRow)
       .toIndexCursor();
@@ -369,7 +379,6 @@ public class CursorBuilder {
    * types of indexes do not include all entries (namely, some indexes ignore
    * null entries, see {@link Index#shouldIgnoreNulls}).
    * 
-   * @param table the table over which this cursor will traverse
    * @param index index for the table which will define traversal order as
    *              well as enhance certain lookups
    * @param startRow the first row of data for the cursor, or {@code null} for
@@ -379,14 +388,14 @@ public class CursorBuilder {
    *               the last entry
    * @param endInclusive whether or not endRow is inclusive or exclusive
    */
-  public static IndexCursor createCursor(Table table, Index index,
+  public static IndexCursor createCursor(Index index,
                                          Object[] startRow,
                                          boolean startInclusive,
                                          Object[] endRow,
                                          boolean endInclusive)
     throws IOException
   {
-    return table.newCursor().setIndex(index)
+    return index.getTable().newCursor().setIndex(index)
       .setStartRow(startRow)
       .setStartRowInclusive(startInclusive)
       .setEndRow(endRow)
@@ -452,15 +461,14 @@ public class CursorBuilder {
    * Warning, this method <i>always</i> starts searching from the beginning of
    * the Table (you cannot use it to find successive matches).
    * 
-   * @param table the table to search
    * @param index index to assist the search
    * @param rowPattern pattern to be used to find the row
    * @return the matching row or {@code null} if a match could not be found.
    */
-  public static Row findRow(Table table, Index index, Map<String,?> rowPattern)
+  public static Row findRow(Index index, Map<String,?> rowPattern)
     throws IOException
   {
-    Cursor cursor = createCursor(table, index);
+    Cursor cursor = createCursor(index);
     if(cursor.findFirstRow(rowPattern)) {
       return cursor.getCurrentRow();
     }
@@ -477,7 +485,6 @@ public class CursorBuilder {
    * distinguishing this situation is important, you will need to use a Cursor
    * directly instead of this convenience method.
    * 
-   * @param table the table to search
    * @param index index to assist the search
    * @param column column whose value should be returned
    * @param columnPattern column being matched by the valuePattern
@@ -485,11 +492,11 @@ public class CursorBuilder {
    *                     desired row
    * @return the matching row or {@code null} if a match could not be found.
    */
-  public static Object findValue(Table table, Index index, Column column,
+  public static Object findValue(Index index, Column column,
                                  Column columnPattern, Object valuePattern)
     throws IOException
   {
-    Cursor cursor = createCursor(table, index);
+    Cursor cursor = createCursor(index);
     if(cursor.findFirstRow(columnPattern, valuePattern)) {
       return cursor.getCurrentRowValue(column);
     }
diff --git a/src/java/com/healthmarketscience/jackcess/DataType.java b/src/java/com/healthmarketscience/jackcess/DataType.java
index 586d16e..75a5a4e 100644
--- a/src/java/com/healthmarketscience/jackcess/DataType.java
+++ b/src/java/com/healthmarketscience/jackcess/DataType.java
@@ -39,7 +39,8 @@ import java.math.BigInteger;
 import com.healthmarketscience.jackcess.impl.JetFormat;
 
 /**
- * Access data type
+ * Supported access data types.
+ * 
  * @author Tim McCune
  */
 public enum DataType {
diff --git a/src/java/com/healthmarketscience/jackcess/Database.java b/src/java/com/healthmarketscience/jackcess/Database.java
index 71a6d59..ab4b7ca 100644
--- a/src/java/com/healthmarketscience/jackcess/Database.java
+++ b/src/java/com/healthmarketscience/jackcess/Database.java
@@ -44,10 +44,15 @@ import com.healthmarketscience.jackcess.util.LinkResolver;
  * Database has been opened, you can interact with the data via the relevant
  * {@link Table}.  When a Database instance is no longer useful, it should
  * <b>always</b> be closed ({@link #close}) to avoid corruption.
- * <p>
- * Note, Database instances (and all the related objects) are <i>not</i>
+ * <p/>
+ * Database instances (and all the related objects) are <i>not</i>
  * thread-safe.  However, separate Database instances (and their respective
  * objects) can be used by separate threads without a problem.
+ * <p/>
+ * Database instances do not implement any "transactional" support, and
+ * therefore concurrent editing of the same database file by multiple Database
+ * instances (or with outside programs such as MS Access) <i>will generally
+ * result in database file corruption</i>.
  *
  * @author James Ahlborn
  * @usage _general_class_
diff --git a/src/java/com/healthmarketscience/jackcess/DatabaseBuilder.java b/src/java/com/healthmarketscience/jackcess/DatabaseBuilder.java
index e9ea26e..f046205 100644
--- a/src/java/com/healthmarketscience/jackcess/DatabaseBuilder.java
+++ b/src/java/com/healthmarketscience/jackcess/DatabaseBuilder.java
@@ -30,7 +30,19 @@ import com.healthmarketscience.jackcess.impl.CodecProvider;
 import com.healthmarketscience.jackcess.util.MemFileChannel;
 
 /**
- * Builder style class for opening/creating a Database.
+ * Builder style class for opening/creating a {@link Database}.
+ * <p/>
+ * Simple example usage:
+ * <pre>
+ *   Database db = DatabaseBuilder.open(new File("test.mdb"));
+ * </pre>
+ * <p/>
+ * Advanced example usage:
+ * <pre>
+ *   Database db = new DatabaseBuilder(new File("test.mdb"))
+ *     .setReadOnly(true)
+ *     .open();
+ * </pre>
  *
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/Index.java b/src/java/com/healthmarketscience/jackcess/Index.java
index 4054c66..9afc6eb 100644
--- a/src/java/com/healthmarketscience/jackcess/Index.java
+++ b/src/java/com/healthmarketscience/jackcess/Index.java
@@ -68,6 +68,11 @@ public interface Index
   public boolean isUnique();
 
   /**
+   * Convenience method for constructing a new CursorBuilder for this Index.
+   */
+  public CursorBuilder newCursor();
+
+  /**
    * Information about a Column in an Index
    */
   public interface Column {
diff --git a/src/java/com/healthmarketscience/jackcess/IndexBuilder.java b/src/java/com/healthmarketscience/jackcess/IndexBuilder.java
index 5e05e5a..3ea8443 100644
--- a/src/java/com/healthmarketscience/jackcess/IndexBuilder.java
+++ b/src/java/com/healthmarketscience/jackcess/IndexBuilder.java
@@ -28,7 +28,8 @@ import com.healthmarketscience.jackcess.impl.IndexData;
 import com.healthmarketscience.jackcess.impl.IndexImpl;
 
 /**
- * Builder style class for constructing an Index.
+ * Builder style class for constructing an {@link Index}.  See {@link
+ * TableBuilder} for example usage.
  *
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/IndexCursor.java b/src/java/com/healthmarketscience/jackcess/IndexCursor.java
index 7871b65..8adff02 100644
--- a/src/java/com/healthmarketscience/jackcess/IndexCursor.java
+++ b/src/java/com/healthmarketscience/jackcess/IndexCursor.java
@@ -24,7 +24,9 @@ import java.io.IOException;
 import com.healthmarketscience.jackcess.util.EntryIterableBuilder;
 
 /**
- * Cursor backed by an index with extended traversal options.
+ * Cursor backed by an {@link Index} with extended traversal options.  Table
+ * traversal will be in the order defined by the backing index.  Lookups which
+ * utilize the columns of the index will be fast.
  *
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/Relationship.java b/src/java/com/healthmarketscience/jackcess/Relationship.java
index 2adb7cb..d8d82af 100644
--- a/src/java/com/healthmarketscience/jackcess/Relationship.java
+++ b/src/java/com/healthmarketscience/jackcess/Relationship.java
@@ -22,7 +22,8 @@ package com.healthmarketscience.jackcess;
 import java.util.List;
 
 /**
- * Information about a relationship between two tables in the database.
+ * Information about a relationship between two tables in the {@link
+ * Database}.
  *
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/Row.java b/src/java/com/healthmarketscience/jackcess/Row.java
index 00fa09f..ede63e2 100644
--- a/src/java/com/healthmarketscience/jackcess/Row.java
+++ b/src/java/com/healthmarketscience/jackcess/Row.java
@@ -22,7 +22,8 @@ package com.healthmarketscience.jackcess;
 import java.util.Map;
 
 /**
- * A row of data as column->value pairs.
+ * A row of data as column name->value pairs.  Values are strongly typed, and
+ * column names are case sensitive.
  *
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/Table.java b/src/java/com/healthmarketscience/jackcess/Table.java
index a9fb4e7..516be6a 100644
--- a/src/java/com/healthmarketscience/jackcess/Table.java
+++ b/src/java/com/healthmarketscience/jackcess/Table.java
@@ -27,13 +27,16 @@ import java.util.Map;
 import com.healthmarketscience.jackcess.util.ErrorHandler;
 
 /**
- * A single database table.  A Table instance is retrieved from a Database
- * instance.  The Table instance provides access to the table metadata as well
- * as the table data.  There are basic data operations on the Table interface,
- * but for advanced search and data manipulation a {@link Cursor} instance
- * should be used.
- * <p>
- * Is not thread-safe.
+ * A single database table.  A Table instance is retrieved from a {@link
+ * Database} instance.  The Table instance provides access to the table
+ * metadata as well as the table data.  There are basic data operations on the
+ * Table interface (i.e. {@link #iterator} {@link #addRow}, {@link #updateRow}
+ * and {@link #deleteRow}), but for advanced search and data manipulation a
+ * {@link Cursor} instance should be used.  New Tables can be created using a
+ * {@link TableBuilder}.
+ * <p/>
+ * A Table instance is not thread-safe (see {@link Database} for more
+ * thread-safety details).
  *
  * @author James Ahlborn
  * @usage _general_class_
diff --git a/src/java/com/healthmarketscience/jackcess/TableBuilder.java b/src/java/com/healthmarketscience/jackcess/TableBuilder.java
index 9530f51..98c256f 100644
--- a/src/java/com/healthmarketscience/jackcess/TableBuilder.java
+++ b/src/java/com/healthmarketscience/jackcess/TableBuilder.java
@@ -38,7 +38,18 @@ import java.util.Set;
 import com.healthmarketscience.jackcess.impl.DatabaseImpl;
 
 /**
- * Builder style class for constructing a Column.
+ * Builder style class for constructing a {@link Table}.
+ * <p/>
+ * Example:
+ * <pre>
+ *   Table table = new TableBuilder("Test")
+ *     .addColumn(new ColumnBuilder("ID", DataType.LONG)
+ *                .setAutoNumber(true))
+ *     .addColumn(new ColumnBuilder("Name", DataType.TEXT))
+ *     .addIndex(new IndexBuilder(IndexBuilder.PRIMARY_KEY_NAME)
+ *               .addColumns("ID").setPrimaryKey())
+ *     .toTable(db);
+ * </pre>
  *
  * @author James Ahlborn
  */
diff --git a/src/java/com/healthmarketscience/jackcess/impl/ComplexColumnSupport.java b/src/java/com/healthmarketscience/jackcess/impl/ComplexColumnSupport.java
index 9cf9b68..6a98ef0 100644
--- a/src/java/com/healthmarketscience/jackcess/impl/ComplexColumnSupport.java
+++ b/src/java/com/healthmarketscience/jackcess/impl/ComplexColumnSupport.java
@@ -77,7 +77,7 @@ public class ComplexColumnSupport
     DatabaseImpl db = column.getDatabase();
     TableImpl complexColumns = db.getSystemComplexColumns();
     IndexCursor cursor = CursorBuilder.createCursor(
-        complexColumns, complexColumns.getPrimaryKeyIndex());
+        complexColumns.getPrimaryKeyIndex());
     if(!cursor.findFirstRowByEntry(complexTypeId)) {
       throw new IOException(
           "Could not find complex column info for complex column with id " +
diff --git a/src/java/com/healthmarketscience/jackcess/impl/DatabaseImpl.java b/src/java/com/healthmarketscience/jackcess/impl/DatabaseImpl.java
index da70cbd..5c28d36 100644
--- a/src/java/com/healthmarketscience/jackcess/impl/DatabaseImpl.java
+++ b/src/java/com/healthmarketscience/jackcess/impl/DatabaseImpl.java
@@ -1929,8 +1929,7 @@ public class DatabaseImpl implements Database
     
     @Override
     protected Cursor getTableNamesCursor() throws IOException {
-      return _systemCatalog.newCursor()
-        .setIndex(_systemCatalogCursor.getIndex())
+      return _systemCatalogCursor.getIndex().newCursor()
         .setStartEntry(_tableParentId, IndexData.MIN_VALUE)
         .setEndEntry(_tableParentId, IndexData.MAX_VALUE)
         .toIndexCursor();
diff --git a/src/java/com/healthmarketscience/jackcess/impl/IndexImpl.java b/src/java/com/healthmarketscience/jackcess/impl/IndexImpl.java
index 1fd560b..db76294 100644
--- a/src/java/com/healthmarketscience/jackcess/impl/IndexImpl.java
+++ b/src/java/com/healthmarketscience/jackcess/impl/IndexImpl.java
@@ -33,11 +33,12 @@ import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
+import com.healthmarketscience.jackcess.CursorBuilder;
 import com.healthmarketscience.jackcess.Index;
-import com.healthmarketscience.jackcess.RowId;
 import com.healthmarketscience.jackcess.IndexBuilder;
+import com.healthmarketscience.jackcess.RowId;
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
 
 /**
  * Access table (logical) index.  Logical indexes are backed for IndexData,
@@ -220,6 +221,10 @@ public class IndexImpl implements Index, Comparable<IndexImpl>
     return getIndexData().getColumns();
   }
 
+  public CursorBuilder newCursor() {
+    return getTable().newCursor().setIndex(this);
+  }
+  
   /**
    * Whether or not the complete index state has been read.
    */
diff --git a/src/java/com/healthmarketscience/jackcess/util/Joiner.java b/src/java/com/healthmarketscience/jackcess/util/Joiner.java
index 02aa051..8a4b854 100644
--- a/src/java/com/healthmarketscience/jackcess/util/Joiner.java
+++ b/src/java/com/healthmarketscience/jackcess/util/Joiner.java
@@ -81,8 +81,7 @@ public class Joiner
     throws IOException
   {
     Index toIndex = fromIndex.getReferencedIndex();
-    IndexCursor toCursor = CursorBuilder.createCursor(
-        toIndex.getTable(), toIndex);
+    IndexCursor toCursor = CursorBuilder.createCursor(toIndex);
     // text lookups are always case-insensitive
     toCursor.setColumnMatcher(CaseInsensitiveColumnMatcher.INSTANCE);
     return new Joiner(fromIndex, toCursor);