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.8+).</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>Expression evaluation is now optionally available as of 2.2.0
                (currently beta).  Input masks are not handled.</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 3.0+ requires JDK 1.8 or higher.  2.x versions require JDK
          1.5 or higher.
        </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.
        </p>
      </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="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>