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.

Servlet Mime Mappings and Windows

 

The following issue was encountered in Tomcat 6, Servlet API 2.5.  Your experiences in other app servers/versions may vary.

In Tomcat, you can set Mime Mappings in your web.xml like so:

	
	<mime-mapping>
		<extension>gif</extension>
		<mime-type>image/gif</mime-type>
	</mime-mapping>

The servlet container will then automatically detect a mime type for uploaded files using some built-in entries, as well as the ones you define in web.xml.

Oh That’s Good…

Unfortunately, this extension mapping is case sensitive.  So suddenly your digital camera, which saves files with upper case extensions (I’m looking at you Nikon), such as DCN005.JPG will foil your app server.

Oh That’s Bad….

So to at least partially handle this, you should enter upper case extensions as a separate mapping.

In Tomcat, you can set Mime Mappings in your web.xml like so:

	
	<mime-mapping>
		<extension>gif</extension>
		<mime-type>image/gif</mime-type>
	</mime-mapping>
	<mime-mapping>
		<extension>GIF</extension>
		<mime-type>image/gif</mime-type>
	</mime-mapping>

Now your app will handle upper case extensions (like JPG), but it will still be foiled if the file extension is mixed case like: ex2399.JpG.

I would definitely like mime mappings to be case insensitive! Does anybody know how to do this? I used javax.activation in the past for Mimetype detection and while it was definitely harder to use than the through the servlet api, but I haven't had a chance to see if it is case-sensitive.

AntiCSRF Protection Measures In Chariot Command

 

About CSRF

CSRF stands for Cross Site Request Forgery,   With it, the attacker tricks an unsuspecting user with a malicious web page.  The malicious page then steals the credentials of the user, and then uses those credentials to perform bad things against your website.

There is a ton of information on the Internet about CSRF.  Here are a few to help you learn about it:

• https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)
• http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attacks.html
• http://en.wikipedia.org/wiki/Cross-site_request_forgery

 

Chariot Command CSRF Protection Mechanisms

Chariot Command provides a “reverse-proxy” that modifies html code on the fly to insert CSRF protection mechanisms.  We use the “double-submit-cookie” protection mechanism as described on Coding Horror. 

CSRF protection takes place in two steps:

1. Modify the pages calling the protected commands to insert a token to check against the cookie.
2. On submission of the form (or click of a protected link), check that both the cookie and the token on the form match up.

Our reverse proxy modifies the generated html code with the following rules:

1. If the user loading the page is not logged in, then nothing is done.  (CSRF relies on credential stealing, of nothing is there to steal, modification of forms is pointless)
2. If the user loading the page is logged in then the defaults are:
   1. Modify forms to add a hidden value that must match the hidden cookie.
   2. Leave Links alone.

Token Generation

Changing The Default Logged Token Generation In Behavior

1. Anchors (“a”) tags, will have a security token generated in the link if you add “nocsrf” to its ‘class’ attribute.
2. Forms can be forced to not have the security token generated by adding “allowcsrf” to its ‘class’ attirbute.

Forcing Creation of Security Token

Under normal conditions, whenever a user logs in, a CSRF token is created. However, if no session is created and you need a CSRFToken, how do we know when to create one? Tag either a command object or method with this annotation, and it'll ensure that a Session is being created along with the appropriate CSRFToken.

Example 1:

The following class will have Security tokens generated no matter what method is invoked:

	import org.chfw.command.annotations.WebCommand;
	import org.chfw.command.annotations.SecurityTokenProvider;

	@SecurityTokenProvider
	@WebCommand
	public class Example1 {
		public methodOne() {

		}
	
		public methodTwo() {

		}	
	}

Example 2

The following class will generate a security token when methodOne is invoked, but not methodTwo

	import org.chfw.command.annotations.WebCommand;
	import org.chfw.command.annotations.SecurityTokenProvider;

	@WebCommand
	public class Example1 {
		@SecurityTokenProvider
		public methodOne() {

		}
	
		public methodTwo() {

		}	
	}

 

When to use CSRF protection mechanisms

Not everything has to be protected from CSRF vulnerabilities.  For example, a list of public documents doesn’t necessarily have to be protected.  Updating or deleting a publically available document should be protected. 

The basic rule of thumb would be:  GET methods are typically not protected, POST, PUT, or DELETE operations should be guarded against.

But as you should well know if you’ve done much software development, rules of thumb don’t always hold.  For example, a GET operation that exposes your address book should be protected against CSRF since the information being divulged is sensitive.  (That’s why we have to allow for Anchor tags to have nocsrf in their ‘class’ attribute)

Enable CSRF Token Checking on Various Command Methods

Use the “SecurityTokenRequired” annotation to tag methods to be protected against CSRF.

Example:

The following example protects methodTwo() against CSRF protection. Like the previous set of examples, you may also tag the entire command class with SecurityTokenRequired to protect access to all methods.

	
	import org.chfw.command.annotations.WebCommand;
	import org.chfw.command.annotations.SecurityTokenRequired;

	@WebCommand
	public class Example1 {
		
		public methodOne() {

		}
	
		@SecurityTokenRequired
		public methodTwo() {

		}	
	}

The CSRF protection mechanisms in Chariot Command are not difficult to use, and since  CSRF-based hacks are making the headlines nearly every day, we cannot stress the need for you to employ these methods (or at least roll your own anti-CSRF protection measures.)

Clean Up Existing Checked Exceptions

 

Once in a while you’re having to work with an API that requires Checked Exceptions.  If you have a chance to work with the API, do you have to stick with them forever?  No! 

Do you have to remove them?  No!

Simply change the exception to derive from RuntimeException instead of Exception.

Example:

From:

	public class DbException extends Exception {
		/* ... */
	}
	

 

To:

	public class DbException extends RuntimeException {
		/* ... */
	}

 

Done!

1. Now all new code doesn’t have to write do-nothing catch blocks which unfortunately is all too common in business code.
   
2. It doesn’t break a bit of old code that was running.

 

Simple, effective, and doesn’t require a complete rewrite of existing code base just to save yourself new code pain.

P.S.  This is also an effective way to set up a release where an exception is deprecated as well.

HtmlSieve Five Minute Introduction

Editor Note: HtmlSieve will be released shortly on GitHub with a mirror of the documentation created here.

What is it good for?

HtmlSieve is a Lexer (not a full fledged stateful parser!), that allows for streaming processing of Html/Xml content. The Lexer recognizes the difference between:

• Text (including CDATA sections)
• Tags (open or close)  and it parses the attributes of the tags
• Comments

 

Overly Simple Example: Counting Tags

A Tag Listener

The tag listener will receive events as tags are encountered by the Sieve while processing code

	package htmlparser.example;
	
	import org.htmlparser_fork.Tag;
	import com.centercomp.htmlsieve;
	
	public class TagCountingListener implements TagListener {
		public int endTags = 0;

		public int startTags = 0;

		/**
		 * Receives notification whenever an 'end' tag
		 * such as </body> is encountered in the Lexing
		 * stream.
		 */
		public Tag onEndTag(final Tag tag) {
			endTags++;
			return tag;
		}

		/**
		 * Receives notification whenever a 'start' tag
		 * such as <body> is encountered in the Lexing
		 * stream.  Start tags will also include 
                 * empty xhtml tags
		 * or void html tags such as &lt;br&gt; or &lt;br/&gt;
		 */
		public Tag onStartTag(final Tag tag) {
			startTags++;
			return tag;
		}

	};

Processing

	import org.junit.*;
	import static org.junit.Assert.*;
	
	@Test
	public void testTagCounting() throws IOException{
		//This is where we will send output.
		StringWriter stringWriter = new StringWriter();
		
		TagCountingListener tagListener = new TagCountingListener();
		//Construct the sieve 
		HtmlSieve sieve = new HtmlSieve()
		
					//Tell it where to send output after processing
					.setWriter(stringWriter)
					
					//Add the Tag Listener
					.addTagListener(tagListener);
					
					
		//Now send the sieve some data in bits:
		String test1 = "<html><body><p";
		String test2 = ">This is a test</p></body></html>";
		
		//Make sure nothing has been processed yet.
		assertEquals(0, tagListener.startTags);
		assertEquals(0, tagListener.endTags);
		
		//The lexer will handle what it can... in this case, the <p> tag
		//is incomplete, so it won't be processed yet.
		sieve.write(test1);
		
		//Processed up to, but not including the 'p' tag.
		assertEquals(2, tagListener.startTags);
		assertEquals(0, tagListener.endTags);
		
		sieve.write(test2);
		sieve.close();
		
		assertEquals(3, tagListener.startTags);
		assertEquals(3, tagListener.endTags);
		
		//Make sure content hasn't been modified by the processing.
		assertEquals(test1 + test2, stringWriter.toString());
	}

As you can see, the key to working with the sieve is the streaming listeners.

What can listeners do

• Process Comments with com.centercomp.htmlsieve.CommentListener. A useful example of this is com.centercomp.htmlsieve.filters.CommentStripper
  
• Process text inside the html with: com.centercomp.htmlsieve.TextListener A useful example of this would be a Profanity filter for a form post, or even possibly an inline emoticon replacer.
  
• Rewrite html tags with com.centercomp.htmlsieve.TagListener We use this extensively in the Chariot Framework for the AntiCSRF processing in Chariot Command. We also plan to use it in Chariot FuSOR.

Developing PicoContainer 3.0 in Eclipse with the Maven Plugin

 

Problem

When you first import the PicoContainer project into the Eclipse IDE, the base project will compile fine, but any additional project will contain the error:

“The project was not built because its build path is incomplete.  Cannot find the class file for com.googlecode.jtype.Generic.

You might also see a similar message refering to a class in: javax.inject.* or com.thoughtworks.paranamer.*
However, if you drop to the console and try to build it manually, everything works peachy.
What’s going on?

Explanation:

To keep 3rd party dependencies to a minimum, PicoContainer’s core build process uses the maven-shade-plugin to wire in a couple of utility jars in picocontainer.jar.  That’s all fine and dandy, but Eclipse doesn’t understand what’s going on in the build processes and complains.
There are three jars that are getting shaded that Eclipse isn’t finding:

<dependency>
    <groupId>com.thoughtworks.paranamer</groupId>
    <artifactId>paranamer</artifactId>
</dependency>
<dependency>
     <groupId>javax.inject</groupId>
     <artifactId>javax.inject</artifactId>
     <version>1</version>
</dependency>
<dependency>
    <groupId>com.googlecode.jtype</groupId>
    <artifactId>jtype</artifactId>
     <version>0.1.1</version>
</dependency>

 

Solution:

Manually add the jar files to your build path in Eclipse and everything will work fine. 

To do this:

1. Right click on the project, Select Properties
   
2. Click on Java Build Path
   
3. Click on the Libraries tab.
   
4. Click on Add External Jar
   
5. Repeat adding external jar until you’ve added all three jars into your project.

Hint: The jars can be located in ${userhome}/.m2/repository since Maven will have automatically downloaded them for you.

When you use Maven to create final artifacts, Maven will behave appropriately shade in the three jars into picocontainer.jar, and all applications will behave as if those jars are appropriately in the classpath.

PicoContainer Auto-Wiring and type safety.

One of the things that people often criticize (unjustly, I might add) about PicoContainer is that it recommends Auto-wiring wherever possible: When an object is constructed, PicoContainer searches for the best possibility to serve as its dependencies.
Chariot Framework and in particular, the front controller, Chariot Command relies heavily on PicoContainer autowiring, because even though you can use Pico’s ‘parameter’ ability to specify constructors, method argument matching is impossible if it isn’t autowireable. 
(Note, this original post was written before javax.inject annotations became available – however, I still haven’t gotten hugely into the annotation markup.)
But it has had an interesting side effect:
Instead of having all sorts of HashMaps scattered around the code base, I have been creating lots of little maps that derive from AbstractMap. One map for each type of ‘map’. Examples in Genesis Command are:
RequestAttributeMap
SessionMap
ParameterSource
None of these classes have been hard to create – in fact, they’re pretty simplistic. But it allows me to use autowiring to its fullest capability. (And frankly, I HATE having to use the specific parameters – I avoid them if at all possible.)
The thing that has become clear after using this technique since 2003: it is highly beneficial to code maintenance for a couple of reasons:

1 – The intent of the map is evident by its type, not just the variable name.

I can easily find where this type is being used thanks to IDE searching facilities, and the purpose of those functions that use the type is quite evident.

 

2 – I don’t lose any capabilities

If I need a generic algorithm, I can still use them because each of the above maps still implement the Map interface, so I don’t lose any capabilities there.

 

3 – I can better tie in behavior with the objects.

One day I needed to be able to determine if a ‘command parameter’ was present in the parameters my Web command object was receiving. With the design I had chosen to avoid autowiring, the solution was simple – add the query behavior to ParameterSource.
I had a clean, encapsulated implementation whereas the other way around, most would have used functions to examine the map and decide if a command parameter was present.
So hats off to PicoContainer and its auto-wiring capabilities. My program structures are significantly improving because of it!