The Json Viewlet

A new viewlet was recently added to the build called JsonViwelet that renders a graph of objects in Javascript Object Notation (Json). It’s packaged in a new module called org.infogrid.jee.viewlet.json to isolate its dependency on “Jackson” – an open source Json parser, from the rest of the ig-ui modules, which is checked in to the ig-vendors package.

This viewlet was provided to help you write an Ajax user interface. Of course, it does not solve the whole problem of creating a modern browser experience which includes visually rendering objects in a browser window, and synchronizing them with the server running Infogrid. However it does kick-start the process and is one less issue to deal with.

There is already support for Json in the tree, from a Viewlet in the ig-ui MeshWorld test apps. called ObjectSetViewlet.jsp. As its name suggests it is a java server page implementation. It’s packaged conventionally in the web tree in v/viewlet/objectset/ObjectSetViewlet/text/json so that it can be dispatched when you provide a mime type of “text/json” in the lid-format parameter of the request URL. As its name suggests it’s dispatched on a collection of objects returned by traversing from the object identified in the request URL – e.g. http://localhost:8084/

This serves as a useful example for how to develop your own Json viewlets, however you could soon end up with several special purpose jsp viewlets that could say render the specific object in the request as Json, render it with and without its meta information and so on … These different rendering requirements are based on how you intend to use the objects into which the Json response gets transformed when it’s evaluated in the browser.

So it seemed like a better idea to provide a universal viewlet that could fulfill all these requirements by being passed URL arguments to control its behavior. It works by performing a transitive closure on the object graph from the object specified in the URL – without looping. Whenever a cycle is detected it writes the object’s “id”  but not its contents, to stub the graph so that the client has a reference it can deal with later.

Unless constrained by the arguments, its default behavior is to dump everything about every object that is encountered in the traversal. So be warned – if you have a very interconnected graph you could end up dumping the whole contests of your meshbase.

The JsonViewlet takes the URL arguments:

  • level=n|0 – 0 means no limit and will follow every relationship
  • dateenc=func|string – determines how Date is rendered, either as a function or String
  • ignoreblessing=entitytype_name_regex – names of blessings to be ignored
  • meta=[no|false]|[true|yes]|only – whether or not to dump meta information
  • trimsa=[yes|true]|[no|false] – trims the subject area name from the property names

Bold = default.

Level, determines the depth of the traversal. Since the object identifiers are returned for the next lower level you could provide code in your javascript client to later make another call to return the next levels in the graph.

Dateenc, controls how IG TimeStamp’s are rendered in json. Json does not provide a way to encode dates, so there is a choice to do this either as a string or as a javascript Date constructor method signature. They both work – you choose.

Ignoreblessing, has the effect of not dumping the values of the specified blessing. This is primarily useful for removing the Probe model properties which bless probed entities. This is control information that is probably not needed by a client – unless you are say writing a probe manager. You can pass it a regular expression or the fully qualified class name, and the argument can be repeated or comma-delimited to specify as many of these as you like.

Meta, gives you the option of either supressing the meta information or only dumping the meta information about an object. Javascript is a typeless language and probably does not care too much about the meta information. However there are some client frameworks that are wrestling with the issue of java-javascript mapping and doing things like simulating fixed class hierarchies – so maybe the meta information might be important.

Finally there is trmsa – which simply trims the subject area name off the front of property type names. These strings can get a bit long and often they are not needed if you’ve specified the property type name uniquely.

There is some error checking of these arguments, and if any error is encountered a Json error is returned as an “id” and “msg.” There should be no other errors returned.

Json returns values as either numbers or strings, therefore blobs are treated as references and returned as URL’s that reference the specific property, and request the PropertyViewlet do the rendering.

In order to use this viewlet you’ll need to make sure it’s added to the application’s viewlet factory, using something like this:

ret.add(JsonViewlet.choice(realToView, ViewletFactoryChoice.BAD_MATCH_QUALITY));

So please give it a try. It would be nice to build out more components needed to build a rich client experience.