add some documentation on large index support (#1564870)

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

src/changes/changes.xml

@@ -13,6 +13,11 @@
       <action dev="jahlborn" type="fix" issue="1942330">
         Access seems to limit data pages to a max of 256 rows.
       </action>
+      <action dev="jahlborn" type="fix" issue="1564870">
+        Added experimental support for "large" indexes.  The current support
+        is optional.  It can be enabled via a varity of means, see the
+        Database javadoc for more details.
+      </action>
     </release>
     <release version="1.1.13" date="2008-03-21">
       <action dev="jahlborn" type="fix" issue="1913775">

src/java/com/healthmarketscience/jackcess/Database.java

@@ -61,6 +61,19 @@ import org.apache.commons.logging.LogFactory;
 
 /**
  * An Access database.
+ * <p>
+ * There is now experimental, optional support for large indexes (disabled by
+ * default).  This optional support can be enabled via a few different means:
+ * <ul>
+ * <li>Setting the system property {@value #USE_BIG_INDEX_PROPERTY} to
+ *     {@code "true"} will enable "large" index support accross the jvm</li>
+ * <li>Calling {@link #setUseBigIndex} with {@code true} on a Database
+ *     instance will enable "large" index support for all tables subsequently
+ *     created from that instance</li>
+ * <li>Calling {@link #getTable(String,boolean)} can selectively
+ *     enable/disable "large" index support on a per-table basis (overriding
+ *     any Database or system property setting)</li>
+ * </ul>
  *
  * @author Tim McCune
  */

src/java/com/healthmarketscience/jackcess/Index.java

@@ -320,7 +320,7 @@ public abstract class Index implements Comparable<Index> {
     
     if(_readOnly) {
       throw new UnsupportedOperationException(
-          "FIXME cannot write indexes of this type yet");
+          "FIXME cannot write indexes of this type yet, see Database javadoc for info on enabling large index support");
     }
     updateImpl();
   }
@@ -733,7 +733,7 @@ public abstract class Index implements Comparable<Index> {
     if(dataPage.getCompressedEntrySize() > _maxPageEntrySize) {
       if(this instanceof SimpleIndex) {
         throw new UnsupportedOperationException(
-            "FIXME cannot write large index yet");
+            "FIXME cannot write large index yet, see Database javadoc for info on enabling large index support");
       }
       throw new IllegalStateException("data page is too large");
     }

src/site/fml/faq.fml

@@ -187,6 +187,20 @@
         </ul>
       </answer>
     </faq>
+
+    <faq id="bigindex">
+      <question>Why am I getting an UnsupportedOperationException (or
+                IOException) when updating an indexed table?</question>
+      <answer>
+        Previously index update support only handled tables with small numbers
+        of rows.  When the index size limit was reached an
+        UnsupportedOperationException (or possibly an IOException) was thrown.
+        As of the 1.1.14 release, experimental, optional large index support
+        has been added.  This support is disabled by default but can be
+        enabled via a few different means.  Please see the <a href="apidocs/com/healthmarketscience/jackcess/Database.html">Database javadocs</a>
+        for details on enabling large index support.
+      </answer>
+    </faq>
     
     <faq id="hms">
       <question>Who is Health Market Science?</question>