jackcess/src/site/fml/faq.fml

<?xml version="1.0"?>

<faqs title="Frequently Asked Questions">

  <part id="general">
    <title>General</title>

    <faq id="linux">
      <question>Does this work on Linux/Unix?</question>
      <answer>
        <p>Yep, Jackcess is pure Java.  It will work on any Java Virtual
        Machine (1.5+).</p>
      </answer>
    </faq>

    <faq id="formats">
      <question>What Access formats does it support?</question>
      <answer>
        <p>Jackcess supports Access database versions 2000-2016 read/write and
           Access 97 read-only.</p>
      </answer>
    </faq>

    <faq id="passwords">
      <question>Are password protected databases supported?</question>
      <answer>
        <p>Basic password protection (Access 2003 or earlier) is merely
           software enforced, and Jackcess does not do any password checking
           at this point.  So, a password protected database can be used the
           same as any other.</p>
        <p>If a database is actually encrypted, then you will need need an
           <a href="#encoding">encoder</a>.</p>
      </answer>
    </faq>

    <faq id="input">
      <question>What sorts of input/data validation does Jackcess support?</question>
      <answer>
        <p>Data validation in Access is controlled via a variety of
           mechanisms, not all of which are supported by Jackces.  See the
           table below for details:</p>
        <div class="indented">
        <table border="1">
          <tr>
            <th>Data Validation Type</th>
            <th>Support</th>
          </tr>
          <tr>
            <td>Data types (Text, Number, etc.)</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Field sizes (min/max length, precision, etc.)</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Unique constraints (indexes)</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>"Enforce Referential Integrity" (aka foreign key
                constraints)</td>
            <td>On by default, can be selectively disabled.</td>
          </tr>
          <tr>
            <td>Field/Table Properties (Validation rules, Input masks, etc)</td>
            <td>No (but Jackcess does provide access to the Properties)</td>
          </tr>
        </table>
        </div>
      </answer>
    </faq>

    <faq id="mdbtools">
      <question>
        How is this different from
        <a href="http://mdbtools.sf.net">mdbtools</a>?
      </question>
      <answer>
        <p>
          We want to give a lot of credit to mdbtools.  They have
          been around much longer than Jackcess, and, along with
          <a href="http://poi.apache.org/">POI</a>,
          inspired us that a project like this could be done.
          mdbtools is written in C.  There is a Java port of it,
          but if you've ever read or used a Java port of a C
          library, you can appreciate the difference between such
          a library and one written from scratch in Java.
        </p>
        <p>
          At the time of this writing, mdbtools could only read
          Access databases.  Jackcess can also write to them.
          According to their web site, "Write support is currently being
          worked on and the first cut is expected to be included in the
          0.6 release."  This status hasn't changed since we first
          started work on Jackcess.
        </p>
        <p>
          The Java port of mdbtools includes an implementation of a small
          subset of the JDBC APIs.  Jackcess does not currently, but a pure
          Java JDBC driver for Access could certainly be written on top of
          Jackcess.
        </p>
      </answer>
    </faq>

    <faq id="odbc">
      <question>
        I'm using the JDBC/ODBC bridge.  Why should I try Jackcess?
      </question>
      <answer>
        <p>
          <ul>
            <li>
              Portability - With Jackcess, your app has one less dependency on Windows.
            </li>
            <li>
              Speed - We had an app that used the ODBC bridge to write data to an
              Access database.  When we switched it over to use Jackcess, it was 5 times faster.
            </li>
            <li>
              Stability - With large amounts of data, we found the ODBC brige to be
              pretty unreliable.
            </li>
            <li>
              Simplicity - With Jackcess, there is no ODBC configuration to set up.
            </li>
            <li>
              Longevity - The JDBC/ODBC bridge has been removed in Java 8.
            </li>
          </ul>
        </p>
      </answer>
    </faq>

    <faq id="jdk">
      <question>What version of the JDK does this require?</question>
      <answer>
        <p>
          Version 1.0 requires JDK 1.4 or higher.  The version in SVN trunk
          and all future releases will require JDK 1.5 or higher.
        </p>
        <p>
          However, some users have contributed patches to make later versions
          compatible with JDK 1.4.  Please check the contributions/ directory
          in the source repository for any such patches.  Note that any code
          in this directory is untested and unsupported, so please use at your
          own risk and do not file bugs based on that code.
        </p>
      </answer>
    </faq>

    <faq id="dependencies">
      <question>Why do I get a NoClassDefFoundError?</question>
      <answer>
        <p>
          Probably because you're missing a jar that Jackcess depends on from
          your classpath.  Take a look at the <a href="dependencies.html">dependencies list</a>.  The "compile" and
          "runtime" dependencies (which are not marked as "optional") are
          necessary for using Jackcess in your application.  One great place
          to track down these dependencies is in the <a href="http://repo1.maven.org/maven2/">Ibiblio Maven Repository</a>.
        </p>
      </answer>
    </faq>

    <faq id="speed">
      <question>Why is jackcess so slow for large updates?</question>
      <answer>
        <p>
          In general, the focus of Jackcess is functionality, not speed.
          However, one major speed factor is whether or not all writes are
          automatically forced to disk.  By default, "autoSync" is enabled,
          which keeps the database file in a more consistent state, but can be
          very slow for large updates.  Disabling "autoSync" can dramatically
          increase update speed, but exceptions during update can leave the
          file in an unusable state (when disabled, you can call <a href="apidocs/com/healthmarketscience/jackcess/Database.html#flush()">Database.flush()</a> manually to force updates to disk).  Modifying this option essentially
          trades off speed for recoverability.
        </p>
        <p>
          Additionally, <a href ="apidocs/com/healthmarketscience/jackcess/Table.html#addRows(java.util.List)">adding rows in batches</a> instead of one at a time can
          increase insert speed.
        </p>
        <p>
          Finally, always make sure you are using the <a href="https://sourceforge.net/projects/jackcess/files/latest/download">latest release</a>, as speed
          improvements are happening periodically.
        </p>
      </answer>
    </faq>
    
    <faq id="international">
      <question>Why am I getting an IOException with the message "unmapped
                string index value"?</question>
      <answer>
        <p>
          Update: As of the 1.1.21 release, the <u>text index handling
          supports the entire Basic Multilingual Plane 0</u> (i.e. any unicode
          character 0x0000-0xFFFF).  Consequently table names can (as of this
          release) contain any character in this character set.  Therefore,
          the rest of this answer should no longer be an issue, but keeping it
          here for reference.
        </p>
        <p>
          Legacy: As of the 1.1.13 release, the text index handling supports
          the entire ISO-8859-1 character set.  Consequently table names can
          (as of this release) contain any character in this character set.
        </p>
        <p>
          Legacy: Jackcess cannot currently update a text column index with
          values which contain non-ascii characters.  This situation often
          arises when tables are created with names which contain
          international characters.  Access stores the table names in another
          table which has an index on the table name column.  The index
          encoding is not simple to reverse engineer, so it is not likely that
          Jackcess will support this anytime soon.
        </p>
        <p>
          Some suggestions (for older releases):
        </p>
        <ul>
          <li>Use only ascii (or ISO-8859-1 as of 1.1.13) characters in table
              names if at all possible</li>
          <li>If tables with international characters are required, create the
              tables using Access, then update the tables using jackcess.</li>
          <li>For indexes on user created tables, populate the table without
              indexes in jackcess, then add the index using Access.</li>
        </ul>
      </answer>
    </faq>

    <faq id="jdbc">
      <question>Does Jackcess provide a JDBC driver for Microsoft Access databases?</question>
      <answer>
        Unfortunately, no.  The Jackcess API is a direct implementation of the
        features available for interacting with an Access database.  There is
        currently no implementation of the JDBC API included with the Jackcess
        library.  While this library would be a great foundation for a JDBC
        driver, implementing the JDBC API is currently outside the scope of
        this project.  There have been a few attempts to use Jackcess to build
        JDBC drivers for Access databases, but most of the projects have not
        progressed very far before becoming inactive.  The <a href="http://ucanaccess.sourceforge.net/site.html">UCanAccess project</a>,
        however, is a currently active open source project which provides a
        JDBC driver built on top of Jackcess.
      </answer>
    </faq>

    <faq id="query">
      <question>Can Jackcess execute SQL queries?</question>
      <answer>
        As of the 1.1.19 release, Jackcess has the ability to <i>read</i> the
        Queries saved in an Access database (i.e. interpret the data stored in
        the system Queries table).  However, Jackcess does not have the
        ability to <i>execute</i> these Queries.  See <a href="#jdbc">this question</a>
        for more details regarding JDBC and Jackcess.
      </answer>
    </faq>
    
    <faq id="android">
      <question>Why do I get an OutOfMemoryError or NullPointerException when
                creating a new database on the Android platform?</question>
      <answer>
        <p>
          There are 2 issues which need to be dealt with when using Jackcess
          on the Android platform.  The first is that non-class resources need
          to be in a special location.  The second is that the nio
          implementation has some "weaknesses".
        </p>
        <p>
          The following steps will make Jackcess compatible with the Android
          platform.
          <ul>
            <li>Set the system property "com.healthmarketscience.jackcess.brokenNio=true"</li>
            <li>Set the system property "com.healthmarketscience.jackcess.resourcePath=/res/raw/"</li>
            <li>Copy the *.txt, *.mdb, and *.accdb files from the
                "com/healthmarketscience/jackcess/" directory in the Jackcess
                jar to the "/res/raw" Android application directory.</li>
            <li>Before executing any Jackcess code, set the current Thread's
                context classloader,
                e.g. "Thread.currentThread().setContextClassLoader(Database.class.getClassLoader())".</li>
          </ul>
        </p>
      </answer>
    </faq>
    
    <faq id="encoding">
      <question>Why do I get an UnsupportedCodecException with the message
                "Decoding not supported"?</question>
      <answer>
        This exception indicates that the Access database you are attempting
        to open is "encrypted" using one of the various forms of encryption
        utilized by Microsoft.  Due to various constraints, the Jackcess
        project does not directly support decrypting Access databases, but
        does, however, support plugging in encryption support using a custom
        <a href="apidocs/com/healthmarketscience/jackcess/CodecProvider.html">CodecProvider</a>.
        The separate <a href="https://jackcessencrypt.sourceforge.io/">Jackcess Encrypt
        project</a> contains the <a href="https://jackcessencrypt.sourceforge.io/apidocs/com/healthmarketscience/jackcess/CryptCodecProvider.html">CryptCodecProvider</a>,
        which implements the Jackess CodecProvider interface and supports
        some forms of Access database encryption.
      </answer>
    </faq>

    <faq id="hms">
      <question>Who is Health Market Science?</question>
      <answer>
        <p>
          HMS is a small company located in suburban Philadelphia.
          Using proprietary matching and consolidation software,
          HMS scientifically manufactures the most comprehensive
          and accurate healthcare data sets in the market today.
        </p>
      </answer>
    </faq>

    <faq id="bugs">
      <question>It doesn't work!</question>
      <answer>
        <p>
          Ok, that wasn't a question, but we'll try to respond anyway. :) As
          you might imagine, it's kind of hard to test, simply by its nature.
          There are bugs that we are aware of, and certainly many more that we
          are not.  If you find what looks like a bug, please <a
          href="https://sourceforge.net/p/jackcess/bugs/">report
          it.</a> Even better, fix it, and <a
          href="https://sourceforge.net/p/jackcess/patches/">submit
          a patch.</a>
        </p>
      </answer>
    </faq>

  </part>

</faqs>