Go here to download ready-to-run and source distributions of Jangaroo. more...

Saturday, August 1, 2009

Jangaroo 0.3.1: Less Imports, More Rhino

We just released version 0.3.1 with some nice updates:

No more same-package imports

With Jangaroo 0.3.1, you no longer need to import classes of the same package to enable automatic class loading. The compiler now scans the directory of the current source file for all *.as files, so that it knows about all declarations in the same package. The limitation that you have to import top-level Jangaroo classes for automatic class loading to work remains---hopefully only until the next release! For more info about Jangaroo and top-level classes, read on below.

Oh, behave, Rhino!

Jangaroo works in many environments: in most browsers, and also in Rhino. For example, to run automated Jangaroo unit tests, the easiest way is to start a cross-platform, stand-alone JavaScript engine like Rhino.
While in principle, the Jangaroo runtime worked inside Rhino, some classes were not loaded and there were strange error messages. After some investigation, we found out that Rhino behaves badly in polluting the global namespace with [JavaPackage] objects for all imported top-level Java package name prefixes. You cannot get rid of some Java packages imported by default, among which are com and net, and even more badly, any property of Rhino's [JavaPackage] objects is claimed to be defined, and they are all again [JavaPackage]. For example, if Rhino knows of a Java class in com.mydomain, the JavaScript expression com.foobar also returns a [Java package] object, even if there is no such package!
This odd behavior made the Jangaroo runtime think that any Jangaroo class in a package starting with com or net is already defined. It seems Rhino cannot be configured to behave less obtrusive, so we had to find a workaround in the Jangaroo runtime. The solution was to treat any JavaScript object whose string representation contains "[JavaPackage" as non-existent and overwrite it with a clean Jangaroo package object. If you still need to access the overwritten Java packages, Rhino also places them under the top-level object Packages, so simply use

Alias for top-level package
The updated Jangaroo runtime defines the alias js for the top-level package. Why?
ActionScript seems to have a problem with top-level classes. Say you have a top-level class Node, and some framework defines a class org.w3c.dom.Node. In your client code, you need to use both classes, so you have to import org.w3c.dom.Node (the top-level class is in scope by default). With asdoc (which is based on the Flex ActionScript compiler), this situation leads to the error that Node is not defined (I also tried importing the top-level Node explicitly). Whether this is a compiler bug or a conceptual problem in ActionScript, I don't really care, since we cannot wait for asdoc to be fixed. My theory is that the import mapping is removed as a result of the name clash, as there is a rule that two imports with the same local name cancel each other out, which means that both classes have to be used with their fully qualified names. But what is the fully qualified name of a top-level class?!
We ran into this situation when trying to provide built-in browser APIs as ActionScript 3 classes and interfaces. Most JavaScript frameworks define wrapper classes for top-level types and put them into their own package (e.g. Ext.Element). So our solution now is to declare the API for a top-level JavaScript type in the package js, which at runtime is the same as the top-level package. Then, to come back to my example, you can use both js.Node and org.w3c.dom.Node in the same class. You can find an alpha of the Jangaroo library defining most built-in browser APIs as ActionScript classes and interfaces under the name "js2native" in the Jangaroo Maven snapshot repository.