9/26/2007

Flexjson 1.5 is live!

After a while I've finally released Flexjson 1.5 to the world. I've been running it for quite sometime trying to see how I liked some of the changes. Since I haven't wanted to change any of my decisions I thought that meant it was time to let other people try it out. There were some big additions to the library. The primary was adding wildcard support for including and excluding fields from your objects. This means you can now exclude one or more fields by using the star notation. The biggest example would be to omit the class attribute on JSON objects. For example:

new JSONSerializer().exclude("*.class").serialize( obj );

Pretty simple huh? You can even use wildcards more than once so expressions like:

new JSONSerializer().exclude("foo.*.bar.*").prettyPrint( obj );

Using a plain star ('*') will cause a deep serialization. In previous releases you used the deepSerialize() method to get a deep serialization. You can still use that method. The big thing that changed between releases is the evaluation order of includes and excludes. In prior releases includes were always processed before excludes. So that meant if you did the following:

In previous release "my.hobbies" would always be processed before *.class, but now they are processed in the order in which you register them. So in 1.5 the order would be to evaluate each field against the "*.class" exclude then evaluate it against "my.hobbies". This enables you do things like:

You might notice a new method I'm using...prettyPrint(). Pretty print is fairly straight forward it formats your JSON output in a pretty to read format. Very nice for debugging.

The other big feature is Transformers. Transformers allow you to register classes that participate in serializing fields. It's best understood as described by a use case. Say we have an object that represents an email, and we want to send it to the browser over JSON. But, emails can have illegal characters for HTML like < or > in fields like the to, from, or cc portions. Before we would have to create a separate method that would HTML encode those characters, and exclude the method that returned those values in plain text. Now we can register a transformer for those fields on the fly. Here's how we can solve this problem:

So the transform() method allows us to register a Transformer called HTMLEncoder. The "to", "from", and "cc" are fields within the email object that we want to run this Transformer on. We can register this Transformer with one or more fields to make it easy on us. The transform() method supports dot notation, just like include and exclude, but doesn't support wildcards.

Transformers can do all sorts of things. Say transform Markdown into HTML from your objects, escape HTML tags and script tags to protect your application, or translating dates into non-numeral format (2007-08-12) or (1/1/2008). Flexjson ships with a HTMLEncoder that you can use out of the box. In the future I hope to add more, especially for security concerns.

This release also has several bug fixes, and performance enhancements. There are some very exciting features in this release. Grab it and see how you like it.

We showed (http://jsonmarshaller.sourceforge.net/2007_11_19_15_02/index.html) that the implementation of wildcards in flexjson is about 200 times slower than deep serialization. I wouldn't recommend this feature for production code.

The format of Dates by default is to send as a plain number. There are several reasons for this. First client side formats are specific to the locale settings which flexjson doesn't have by default. Second doing ajax like things (especially with libraries like ext) it's more useful to convert those Dates to Javascript Date objects so you can do client side sorting and comparisons using those numbers. That's not possible with strings.

If you'd like to convert those dates to strings you can install a DateTransformer for either the Date.class or the object path for portions you'd like to convert. Flexjson does ship with a DateTransformer so it's really a single method call to convert them. Although I just checked and the online javadoc looks like it's a little old. The javadoc that ships with 1.6 should be up to date.

Something like:

new JSONSerializer().transform( Date.class, new SimpleDateTransformer( "yyyy/MM/dd").serialize( new Date() );

Yes it's still being worked on, but I've been occupied with some changes in my life that doesn't allow me much time to dedicate to it. I just sketched out a preliminary Deserializer which is something people have been asking for. I'll probably make a quick release to fix the hibernate bug here in a few days. Then hopefully soon release 2.0

I have a problem with the names of the properties. I want to create a POJO that represent this json: {"font-size": 12}. But in java, the "-" character is forbidden in property names. How can I workaround this problem? Thanks.