1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
<?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<String,Object></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<String,Object></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="http://jackcessencrypt.sourceforge.net/">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 -> Jackcess Encrypt 2.y</li>
<li>Jackcess 1.x -> 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>
|
