Cardme Java Library Review

Once in a while you come across a little library that holds great promise, who’s creator has obviously put his heart into it and is willing to work with whomever comes along, just for the love of the library.

The BSD licensed Cardme is one such library.

This tale began when I was looking for a library to help generate VCards.  Even though the basic VCARD format itself is rather simple (Just open one up in a text editor and you’ll see what I mean), there’s always gotchas inside any format (such as string encoding), that I thought I’d rather leave up to the experts.

However, the Vcard library landscape seems to be littered with rotting corpses:  libraries that have received zero care for several years (typically greater than 5 years with zero activity), who’s owners obviously could care less about them. (Forum posts typically were ignored).  Then I came across Cardme.

The Downside

First let me talk about the issues in the library that stood out to me:

1. One committer. (Can be good, usually bad)
2. Class files are checked into the SVN tree.
3. Eclipse settings files checked into the codebase.
4. No automated tests
5. Limited Docs

Normally these would be enough red flags to run me off.  But since I was desperate to find an active project, I decided to give it a test drive for a day.

I started by creating a maven pom and unit tests…. and then I noticed that while normally little-used features like I was testing would EASILY show errors, I couldn’t find big issues with the library.

The only issue I ever came across was Outlook 2010 not being able to read the embedded photos generated by the library.  So I took a deep breath, and posted to the forum…. and about 8 hrs later… *gasp* I got a reply from an interested developer!

While this issue hasn’t been fixed at the time of this writing, I’m confident that this bug will eventually fall since it’s obvious there are people interested in getting it resolved.

The Upside

So lets talk about why I liked this library so much I’m posting a review of it here.

• No static factories.  HOORAY!
• Few Coding Mistakes: I ran the project through PMD just to see if I could find errors that way….  the only errors flagged were the Base64 public domain library being used.  The developer worked to keep a clean style with few shortcuts that kept his code free of such errors. 
• The API is very consistent: Again, a pleasant surprise for a little Sourceforge library with only one committer.  There are interfaces if you want to use them, but the typical bean implementations are more than sufficient.  This made the library surprisingly easy to learn, even though the VCard format is fairly flexible.
• Correct Encoding: If I threw bizarre characters at the library in my test, it properly escaped the strings (more than can be said for some other vcard libraries)
• Did I mention no static factories?
• Developer willing to work with bizarre programs: By having compatibility switches available, the developer is more than willing to work with bizarre program support (such as Outlook, Gmail, and Mac Contacts).  He doesn’t just sit on his heels, say, “Well, that’s not to the spec” and walk way.
• It did its job It doesn’t try to do everything in the world, but it helped me generate vcards cleanly and efficiently.

So in the end, I get to generate VCards knowing that I’ve got a developer who’s heart is in the library at my side.  What’s not to like?

Check out this guy’s project at http://sourceforge.net/projects/cardme

Update: 9/8/2011

As I expected, the Cardme library author has come through with flying colors… I can embed images inside my vcf files that Outlook 2010 can read, I can set item URL’s so Outlook can read it and best of all, he has revised the license to the shortened BSD license so it’s now compatible with GPL.  It would be a game changer if the opensource community had a few more of these guys around.