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


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176
							<?xml version="1.0"?>

<document>
  <properties>
    <author email="jahlborn@users.sf.net">James Ahlborn</author>
    <title>Upgrading from Jackcess 1.x to 2.x</title>
  </properties>
  <body>
    
    <section name="Jackcess 2.0">
      <subsection name="I'm Scared!">
        <p>
          Step back from the keyboard and take a moment to catch your breath.  I
          know the idea of upgrading to a new major version of a software
          project can be a bit daunting.  A completely re-written library means
          a whole new set of bugs to work through!  Rest assured, however,
          <u>the changes from Jackcess 1.x to 2.x are largely cosmetic!</u> The
          core code is functionally unchanged, just shuffled around and tweaked.
          So, once an existing project has been updated for the new API, things
          should work pretty much the same as they did before (for better or
          worse!).  That begs the question, of course, why mess everything up in
          the first place?
        </p>
      </subsection>

      <subsection name="Why rock the boat?">
        <p>
          The Jackcess project is over 8 years old at this point, and as any
          developer knows, projects tend to accumulate cruft over the years.
          The available functionality has grown dramatically from the initial
          release while still retaining binary compatibility across most
          releases.  This has been quite an effort and, unfortunately, has
          caused the API to become a bit unwieldy.  The 2.x release is an
          attempt to rework the API to make it both more approachable for new
          users as well as more convenient for power users.
        </p>
        <p>
          While an initial compile of existing code against the new 2.x API may
          generate a fair bit of compile warnings, many of the changes are
          fairly superficial (e.g. classes moving to new packages).  All of the
          changes that were made were made in an attempt to make the API more
          useable and to follow API design best practices.  Change for the sake
          of change was avoided (e.g. just "prettying" up existing method
          names).
        </p>
      </subsection>

      <subsection name="So what changed?">
        <p>
          Functionally speaking, Jackcess is largely unchanged.  The core
          codebase is largely the same, just re-arranged.  The only major
          changes regarding functionality are:
        </p>
        <ul>
          <li><b>"Simple" index support has been removed.</b></li>
          <ul>
            <li>In older releases, Jackcess did not fully understand how
            indexes worked.  When that functionality was fully grasped,
            "big" index support was added, but the "simple" support was left
            as the default for backwards compatibility.  In later releases,
            after the "big" index support was stabilized, it became the
            default.  Now, there really isn't any reason to keep the old,
            broken support.</li>
          </ul>
          <li><b>Foreign Key constraints are now enforced by default.</b></li>
          <ul>
            <li>Similarly, foreign key constraints were only recently
            understood by jackess.  For backwards compatibility, enforcement
            was not made the default.  This tends to confuse new users, as the
            general expectation of a database is that it will enforce
            constraints (unless told otherwise).  Unlike "simple" index
            support (which was removed completely), foreign key constraint
            enforcement can still be disabled.</li>
          </ul>
        </ul>
        <p>
          The remaining changes are largely cosmetic or just slightly different
          (hopefully better) ways to do the same things.  Among these changes,
          the major ones are:
        </p>
        <ul>
          <li><b>The public API classes are now primarily interfaces.</b></li>
          <ul>
            <li>Making the primary API classes interfaces allows more
            flexibility in the implementation without affecting the API.  It
            also makes a more clear distinction between methods that are
            intended to be used externally and those that are intended for
            internal use.  This makes the API much more approachable for new
            users.</li>
            <li>Note that there are some "advanced" methods which may be
            useful to the occassional power user which are no longer available
            from the public API.  These methods, however, <i>are still
            available</i> on the implementation classes.</li>
          </ul>
          <li><b>Most instance construction is now handled via builder classes.</b></li>
          <ul>
            <li>Since the public API is now primarily interfaces, some sort of
            factory type class is necessary to construct the relevant
            implementations.  These new factory classes follow the builder
            pattern which is a very convenient programming style which has the
            secondary benefit of removing the need for complex constructors
            with many parameters.</li>
          </ul>
          <li><b>The various (and confusing) methods for constructing Iterables
          have been replaced by an Iterable builder.</b></li>
          <ul>
            <li>There were a variety of methods on the Cursors for
            constructing different Iterable/Iterator instances with different
            options.  These have all been combined into a single Iterable
            builder class which is both easier and more convenient to work
            with.</li>
          </ul>
          <li><b>Many secondary "utility" classes were moved to the "util"
          package.</b></li>
          <ul>
            <li>As part of making the API more approachable to new users, many
            of the secondary classes were moved to the "util" package.  This
            makes the primary API more obvious.</li>
          </ul>
          <li><b>A row is now a Row.</b></li>
          <ul>
            <li>A row of data, previously typed as a
            <code>Map&lt;String,Object&gt;</code>, is now explicitly typed as
            a Row.  This makes code much more readable as well as allows for
            additional functionality beyond the basic Map.  Since the Row
            interface extends <code>Map&lt;String,Object&gt;</code>, old code
            can remain largely untouched.</li>
          </ul>
          <li><b><code>Attachment.getFileData</code> now returns the "real"
              data.</b></li>
          <ul>
            <li>Previously, this method returned the internal representation
            of the attachment data, which included a wrapper and the data in a
            possibly compressed form.  Now that the internal format has been
            deciphered, this method has been changed to return the actual
            attachment content (which is most likely what people would desire
            from that method in the first place).  The internal representation
            can be retrieved from <code>Attachment.getEncodedFileData</code>
            if necessary.</li>
          </ul>
        </ul>

        <h4>Working with Jackcess Encrypt</h4>
        <p>
          If you are using the <a href="https://jackcessencrypt.sourceforge.io/">Jackcess Encrypt</a> project, then you will need to
          use a version compatible with the relevant Jackess API.
          Fortunately, the major versions match, so it's pretty simple:
        </p>
        <ul>
          <li>Jackcess 2.x -&gt; Jackcess Encrypt 2.y</li>
          <li>Jackcess 1.x -&gt; Jackcess Encrypt 1.y</li>
        </ul>
      </subsection>

      <subsection name="What does this mean for 1.x?">
        <p>
          Moving forward, all new feature development will be in Jackcess 2.x.
          The Jackcess 1.x code has been branched at version 1.2.14 and some
          bugfixes may be backported to that branch on a case by case basis.
          However, no new feature development will be done on the 1.x branch.
        </p>
      </subsection>

      <subsection name="What did we miss?">
        <p>
          This upgrade guide attempts to hit all the high-points for upgrading
          from Jackcess 1.x to 2.x.  If you feel that it is incorrect or missing
          a key bit of information, please, <a href="https://sourceforge.net/p/jackcess/discussion/456474/">drop us a line</a>!
        </p>
        <p>
          Some <a href="https://sourceforge.net/p/jackcess/discussion/456474/thread/8b76f73b/">additional notes</a> from a migration effort.
        </p>
      </subsection>
    </section>
  </body>
</document>