path: root/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>As of the 1.2.0 release, Jackcess supports Access database versions
           2000-2007. Access 97 databases are not supported.</p>
      </answer>
    </faq>

    <faq id="passwords">
      <question>Are password protected databases supported?</question>
      <answer>
        <p>Basic password protection 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>
      </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>
          mdbtools supports Access 97 databases, which Jackcess does not.
          The Java port of mdbtools also 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="poi">
      <question>
        This looks like a logical addition to POI.  Why not integrate with
        that project?
      </question>
      <answer>
        <p>
          <a href="http://poi.apache.org/">POI</a> is released under
          <a href="http://www.apache.org/foundation/licence-FAQ.html">The Apache License</a>.
          Jackcess is released under
          <a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt">The GNU Lesser General Public License</a>.
          The Apache license allows closed-source and/or commercial forks.
          The LGPL does not.  If you change or enhance Jackcess, you must contribute
          your changes back to the project.
        </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>
          </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 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>
          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>
          Update: 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>
          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="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.  As of the 1.2.0 release, large index support is
        enabled by default.  This support is enabled/disabled via a few
        different means.  Please see the <a href="apidocs/com/healthmarketscience/jackcess/Database.html">Database
        javadocs</a> for details on enabling/disabling large index support.
      </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.  There have been a few
        attempts to use Jackcess to build JDBC drivers for Access databases,
        but none of the projects seem to have progressed very far before
        becoming inactive.
      </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 UnsupportedOperationException 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="http://jackcessencrypt.sourceforge.net/">Jackcess Encrypt
        project</a> contains the <a href="http://jackcessencrypt.sourceforge.net/apidocs/com/healthmarketscience/jackcess/CryptCodecProvider.html">CryptCodecProvider</a>,
        which implements of 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. :)
          Jackcess is young, and not that robust yet.  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="http://sf.net/tracker/?group_id=134943&amp;atid=731445">report it.</a>
          Even better, fix it, and
          <a href="http://sf.net/tracker/?group_id=134943&amp;atid=731447">submit a patch.</a>
        </p>
      </answer>
    </faq>

  </part>

</faqs>