mirrors
/
jackcess
mirror of https://github.com/jahlborn/jackcess.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221
							<?xml version="1.0"?>

<document>
  <properties>
    <author email="jahlborn@users.sf.net">James Ahlborn</author>
    <title>Jackcess Cookbook</title>
  </properties>
  <body>
    <section name="Introduction">
      <p>
        This cookbook will attempt to familiarize the reader with the various
        nooks and crannies of the Jackcess API.  The API is large due to the
        large feature-set that an Access Database provides, so this cookbook
        will by no means be exhaustive.  However, this will hopefully give the
        reader enough useful building blocks such that the rest of the API can
        be discovered and utilized as necessary.
      </p>
      <p>
        This cookbook is a cross between a tutorial and a reference, so the
        reader should be able to skip to relevant sections without needing to
        read the entire preceding text.
      </p>
      <p>
        While this cookbook strives to present best practices for both the
        Jackcess API and Java programming in general, at times, the code may
        be trimmed for the sake of brevity.  For the same reason, pseudo-code
        may be used in places where the actual code is not relevant to the
        example.
      </p>
<macro name="toc">
  <param name="section" value="2"/>
  <param name="fromDepth" value="0"/>
  <param name="toDepth" value="4"/>
</macro>
    </section>

    <section name="The Basics">
      <subsection name="Opening an existing Database">
        <p>
          So you have an Access Database and you want to do something with it.
          You want to use Java, and you may not even be running on Windows (or
          you tried the JDBC/ODBC bridge and it failed miserably).  Through
          some Google-fu, you landed here at the Jackcess project.  Now what?
        </p>
        <p>
          Well, the first thing you need to do is open the database.  The
          entry point class in the Jackcess API is, suprisingly enough, the
          <a href="apidocs/com/healthmarketscience/jackcess/Database.html">Database</a> class.
        </p>
        <source>
  Database db = Database.open(new File("mydb.mdb"));
</source>
        <p>
          That's it, now you have a Database instance (maybe this isn't that
          difficult after all).
        </p>
        <p>
          Important note, <i>always</i> make sure you close a Database
          instance when you are finished with it (preferably in a finally
          block like any other important resource).  Failure to close the
          Database instance could result in data loss or database corruption.
        </p>
      </subsection>
      <subsection name="Reading a Table">
        <p>
          Okay, so you have a Database instance, now what?  Since pretty much
          everything in an Access database lives in a table, grabbing a <a href="apidocs/com/healthmarketscience/jackcess/Table.html">Table</a>
          would be the logical next step.
        </p>
        <source>
  Table table = db.getTable("Test");
</source>
        <p>
          Where's the data?  While a <a
          href="apidocs/com/healthmarketscience/jackcess/Cursor.html">Cursor</a>
          is the best way to interact with the data in a Table, for the sake
          of simplicity when just getting started, we will use the simplified
          iteration provided by the Table class itself.  When reading row
          data, it is generally provided as a <code>Map&lt;String,Object&gt;</code> where the keys are the column
          names and the values are the strongly typed column values.
        </p>
        <source>
  for(Map&lt;String,Object&gt; row : table) {
    System.out.prinln("Look ma, a row: " + row);
  }
</source>
        <p>
          So, what's in a row?  Well, let's assume your "Test" table is
          defined in the following way in Access:
        </p>
        <blockquote>
          <table>
            <tr>
              <th>Field Name</th><th>Data Type</th>
            </tr>
            <tr>
              <td>ID</td><td>AutoNumber (Long Integer)</td>
            </tr>
            <tr>
              <td>Name</td><td>Text</td>
            </tr>
            <tr>
              <td>Salary</td><td>Currency</td>
            </tr>
            <tr>
              <td>StartDate</td><td>Date/Time</td>
            </tr>
          </table>
        </blockquote>
        <p>
          Then, given a row of data, we could inspect the various <a href="apidocs/com/healthmarketscience/jackcess/Column.html">Columns</a> and
          their values like so:
        </p>
<source>
  Map&lt;String,Object&gt; row = ...;
  for(Column column : table.getColumns()) {
    String columnName = column.getName();
    Object value = row.get(columnName);
    System.out.println("Column " + columnName + "(" + column.getType() + "): "
                       + value + " (" + value.getClass() + ")");
  }

  // Example Output:
  //
  // Column ID(LONG): 27 (java.lang.Integer)
  // Column Name(TEXT): Bob Smith (java.lang.String)
  // Column Salary(MONEY): 50000.00 (java.math.BigDecimal)
  // Column StartDate(SHORT_DATE_TIME): Mon Jan 05 09:00:00 EDT 2010 (java.util.Date)
</source>
        <p>
          As you can see in this example (and as previously mentioned), the
          row values are <i>strongly typed</i> Java objects.  In Jackcess, the
          column types are represented by a Java enum named <a href="apidocs/com/healthmarketscience/jackcess/DataType.html">DataType</a>.
          The DataType javadoc details the Java types used to return row
          values as well as the value types which are acceptable inputs for
          new rows (more on this later).  One other thing to note in this
          example is that the column names in the row Map are <i>case
          sensitive</i> strings (although other parts of the API strive to
          mimic Access's love of case-insensitivity).
        </p>
      </subsection>
      <subsection name="Adding a Row">
        <p>
          Awesome, so now we can read what's already there.  Of course, lots
          of tools can do that.  Now we want to write some data.
        </p>
        <p>
          The main hurdle to writing data is figuring out how to get the data
          in the right columns.  The primary method for adding a row to a
          Table is the <a href="apidocs/com/healthmarketscience/jackcess/Table.html#addRow(java.lang.Object...)">addRow(Object...)</a>
          method.  This method should be called with the appropriate, strongly
          typed Java object values <i>in the order of the Columns of the
          Table</i>.  The order of the Columns on the Table instance <i>may
          not be the same as the display order of the columns in Access</i>.
          (Re-read those last two sentences again, as it will save you a lot of
          grief moving forward).
        </p>
        <p>
          Additionally, when adding rows, we never provide a value for any
          "auto" columns.  You can provide a value (any value in fact), but it
          will be ignored (in the example below, we use a useful constant which
          makes the intent clear to any future developer).
        </p>
        <p>
          So, assuming that the order of the Columns on the Table instance is
          "ID", "Name", "Salary", and "StartDate", this is how we would add a
          row to the "Test" table:
        </p>
<source>
  String name = "bob";
  BigDecimal salary = new BigDecimal("1000.00");
  Date startDate = new Date();

  table.addRow(Column.AUTO_NUMBER, name, salary, startDate);
</source>
        <p>
          There you have it, a new row in your Access database.
        </p>
      </subsection>
    </section>
    <section name="Starting from Scratch">
      <subsection name="Creating a new Database">
        <p>
          While updating existing content is nice, and necessary, many times
          we want to create an entire new Database.  While Jackcess doesn't
          support everything you may need when creating a new database, it
          does support a wide range of functionality, and adds more all the
          time.  (If you started using Jackcess a while ago, you should
          definitely keep tabs on the release notes, as your knowledge of what
          is possible may be out of date).
        </p>
        <p>
          As of version 1.2.10, Jackcess supports:
        </p>
        <ul>
          <li>Creating databases for Access all versions 2000-2010</li>
          <li>Creating columns for all simple data types</li>
          <li>Creating tables with single-table Indexes</li>
        </ul>
        <p>
          Some notable gaps:
        </p>
        <ul>
          <li>Cannot currently create (index backed) foreign-key
              constraints</li>
          <li>Cannot currently create "complex" columns (attachment,
              multi-value, versioned memo)</li>
        </ul>
        <p>
          As long as your needs fall into the 
        </p>
      </subsection>
      <subsection name="Creating a Table">
        <p>
          
        </p>
      </subsection>
    </section>

  </body>
</document>