#1 Implement MimeDir API + misc improvements

[Chris Hubick]

1) Mime-Dir and vCard Java API:

Mainly these modifications make vcard4j implement the
"Mime-Dir and vCard Java API" which I created,
currently found at:
http://adlib.athabascau.ca/~hubick/MimeDir/

This gives Java developers a standard object model for
Mime-Dir and vCard data, as well as the ability to
write code against this interface, without being tied
to a particular implementation.

It is important to note that existing vcard4j code and
users does not need to notice or care about this change
if they don't want to. All existing vcard4j constructs
are in tact, just now implementing some additional
interfaces.

The MimeDir code (LGPL) either needs to be bundled with
vcard4j, or it will add an external jar dependency to
the package which people will need to get (with the
benefit that it can be updated independently for bug
fixes or additional utility functions). I am fine with
bundling it though to minimize impact on users.
Preference?

2) toString() and equals()

Part of what I provide in the MimeDir package is
'toString' and 'equals' functions for Mime-Dir/vCard
interface implementing objects. I have used these to
implement the corresponding methods on the vcard4j Java
Type objects. If you do System.out.println(vcard) you
will now get properly formatted vCard output, without
requiring stylesheet overhead.

Secondly, if you do vcard1.equals(vcard2) it will
conduct a *logical* comparison - meaning it will
compare the two vCard instances and still return true
if they both have all the same types/values but in
different order (including parameter order).

3) StructuredType and ListType set() fixes

I changed DomParser to no longer create empty DOM
tree's for non-existant structure values. The set
function for Structured (and implemented for List now
too) types will now create DOM elements on demand as
needed. In addition, the size() function can now work
correctly on StructuredTypes (needed for the Mime-Dir API).

4) size() performance increases

I needed size() type functions for the Java API, and
optimized these throughout the Types to use a new
XpathUtils function which does an xpath "count()"
rather than creating a whole array of objects just to
do .length on then throw away.

5) abstract getConstructor() functions.

The Type base-class functions used to take a
constructor as an argument, and the type compiler
needed to generate wrappers for these, supplying the
valueTypeConstructor from the sub-class. Abstract
getConstructor() functions have been created, and base
class functions switched to use these rather than
taking arguments, simplifying the method calls greatly.
The type compilers were changed to generate the proper
code. This allows additional base class functions,
without having to add more and more wrapper methods to
the type compiler.

6) Parser convertVersion option.

Up-Conversion from vCard 2.1 to 3.0 was made optional
(default
enabled). I use vcard4j as part of a validator which
needs to 'explode' if the wrong version of vCard data
is supplied in the document.

There is a DomParser.setConvertVersion(boolean) method now.

7) Parser checkMandatoryTypes option.

DomParser.checkVcard30() was renamed to
checkMandatoryTypes() and made optional as well
(default enabled). There was a bug where N or FN could
be missing on 2.1 or unknown version vCards - all
versions are now validated (possibly after
up-conversion) unless this option is shut off.

8) Unknown VERSION's allowed

If someone wants to run a backwards compatible vCard
VERSION 4.0 (or whatever) through the parser someday,
and if it still meets 3.0 rules, that should still work
without exception.

[Chris Hubick]

cvs diff -u

[Chris Hubick]

Logged In: YES
user_id=843406

As of this writing this project has not had a release in
over a year, numerous emails to the maintainer (Yann
Duponchel) and posts in the forum have gone unanswered, and
this patch has not been applied (or even commented on) in
over three months. So, for the convenience of my users, so
that they don't have to manually patch and compile vCard4J,
I have created a forked vCard4J distribution containing the
latest CVS code with this patch applied:
http://adlib.athabascau.ca/~hubick/vCard4J/