Jangaroo 0.7.12: More AS3 Features, even for IE9

What's new in Jangaroo 0.7.12?

We are proud to present our latest Jangaroo release with many improvements and new features in several different areas.
Our last blog post is a while ago, but in the meantime, we delivered several intermediate releases and used light-weight Twitter announces (just follow @Jangaroo).

General

• github
  Jangaroo is on github now!
  Check out Jangaroo Tools (compiler, Maven plugins, IDEA plugin) from https://github.com/CoreMedia/jangaroo-tools.
  Find Jangaroo JavaScript wrapper APIs (browser API, Ext JS, CKEditor, soundmanager 2) and libraries (URI utils, JooUnit, JooFlash) at https://github.com/CoreMedia/jangaroo-libs.
  
• Maven Central
  Since version 0.7.9 you can use Jangaroo from Maven without specifying any <repository> or <pluginRepository> now, so the POMs get even simpler. This is possible because all new Jangaroo Maven artifacts are deployed to Maven Central. Sonatype kindly offers this service to all Open Source projects. The old Jangaroo Maven repository still exists to host the old versions.
  
• Compiler and Runtime Version in Generated Code
  The compiler now adds version information, so that the Jangaroo Runtime can check compatibility of generated JavaScript code. A class runtimeApiVersion/compilerVersion is compatible with the current Runtime if
  
  
  • the runtimeApiVersion matches the Runtime's runtimeApiVersion exactly and
  • the compilerVersion is lower or the same as the Runtime's compilerVersion.
  The idea is that runtimeApiVersion is only incremented when the contract between compiler and runtime changes. Thus, you may use library code compiled with an older compiler together with a runtime plus your code compiled with a later compiler. This may be important if you want to use a library and a new compiler feature, but the library is not yet available compiled with the latest compiler version. As long as we release all Jangaroo libraries ourselves, this may be academic, but this situation is bound to change sooner or later.
  
• Cyclic Static Dependency Detection
  The Runtime now logs a warning if a cyclic static initializer dependency is detected. This happens if one class triggers initializing another class and the other class directly or indirectly triggers initializing the first class, which is already in progress. This situation does not have to cause problems, but the first class is already used while it is not yet fully initialized, so e.g. members might still be "undefined". Clean code should not contain such initialization cycles.
• IntelliJ IDEA 9 Plugin
  As always, the Jangaroo Language IDEA plugin has been updated to use the latest compiler. In IDEA, simply go to Settings | Plugins | Available, search for Jangaroo Language, and click the "Download & Install" or "Update Plugin" button. After restarting IDEA, you can import Jangaroo Maven projects and enjoy code completion, fast compile-and-deploy turn-around ("Make Project"), and instant static type checking.

Newly Supported AS3 Features

• Full trace() Compatibility and More
  In previous Jangaroo versions, trace() only took a single parameter to print to the JavaScript console. However, in AS3, trace takes arbitrary parameters and joins them to a string (using space as separator). We now implement exactly this method signature and semantics.
  To also take advantage of Firebug's different console log levels, indicated through icons, without changing the method signature, we use the following convention: If you start your trace output with one of [LOG], [INFO], [WARN] or [ERROR], the corresponding Firebug console method (log(), info(), warn() or error()) is invoked with the remainder of the message. For other environments, the string is printed as-is.
  
• Variable Default Values
  Depending on their type, class variables (fields) are initialized to standard values as defined in the AS3 language specification (see bottom of page). Note that this feature is only implemented for class variables, including statics, but not yet for local variables.
  
• Helper Classes
  Out-of-package helper classes, i.e. non-public class definitions contained in the source file of a public class, are now fully supported. Unfortunately, I could not find any official Adobe reference documentation on helper classes, so please refer e.g. to this blog post on helper classes .
  
• Annotations
  Basic support for annotations, i.e. meta data in square brackets added to classes or methods, has been added to the Jangaroo compiler and runtime. Since we do not yet fully implement flash.utils.describeType(), the only way to query meta data at runtime is through a Jangaroo-specific API which is subject to change. If you want to give it a try, find the meta data for a class using the following code:
  

  var metadata:Object =
    joo.SystemClassDeclaration(SomeClass['$class']).metadata;
  

  To retrieve the metadata of a public class member, use the following pattern:
  

  var memberMetadata:Object =
    joo.SystemClassDeclaration(SomeClass['$class'])
    .getMemberDeclaration("public", "someMember").metadata;
  

  In both cases, the according annotation is transformed to an Object straight-forwardly, e.g.
  

  [SWF(width=465, height=465,
       backgroundColor=0, frameRate=15)]
  

  results in the metadata object
  

  {SWF:{width:465, height:465,
        backgroundColor:0, frameRate:15}}
  

• as Operator
  Jangaroo has been supporting as for quite some time, but so far, it was not transformed into any code (only comments in debug mode).
  Now, as is implemented with its original AS3 semantics, i.e. checking the object's type and evaluating to null if there is no match. Be aware that this changes semantics of your code, for example if you used as to cast to a type to call some method, which might have worked at runtime without the object actually being an instance of the type. In such cases, you can fall back to the type cast syntax (Type(expr)), which still generates comments only. Be warned that this code might someday throw a TypeError when using a later Jangaroo release.
  

Browser Compatibility

• trace() in IE
  trace() now also works with Internet Explorer's console. It already worked before with Firefox with Firebug, WebKit, Opera, and any browser using Firebug light.
  
• Property Accessor Functions in IE9
  So far, Jangaroo supported AS3 properties (function get/set) in WebKit, Firefox and Opera, but not in any version of Internet Explorer. IE9 is the first to implement custom properties accessor functions for any JavaScript object. IE8 already introduced the ECMAScript 5 methods to define properties, but they were only implemented for DOM objects. Thus, Jangaroo only supports property accessor functions in IE9.
  To simulate this feature also in older IE versions is a much harder task, but still we might tackle it later (see discussion on Jangaroo User Group).
  
• Workaround for IE9 Crash
  Jangaroo stores class meta data under the expando property $class of the class's constructor function. Even for built-in classes, when used from Jangaroo code, the Runtime attaches this property. So far, this approach worked well with IE, but IE9 beta crashed (!) when trying to run our Box2D demo.
  After intensive debugging, I figured out that IE9 does not like the $class property of built-in class TypeError being accessed. With some more digging into, the real source revealed itself: If in IE9 document mode, you set any expando property on the built-in Error class and query it through a subclass (like TypeError), IE9 beta crashes. Comprising only 21 characters, this might actually be the shortest JavaScript "code of death" for IE9:
  

  Error.x=1;TypeError.x
  

  The workaround for Jangaroo is not to set $class on the Error class, but Microsoft will have to fix this bug anyway, or there will be lots of Websites with links that say: "To crash IE9, please click here."
  
• @-Properties in IE
  Respect that IE does not like properties starting with @, and quote them.
  

Bug Fixes, Improvements and API Changes

• fixed a minor bug in regular expressions syntax and improved parser error messages
• improved class initialization, which was sometimes triggered eagerly when not necessary
• cleaned up Runtime logging in debug mode: log class initialization instead of class loading
• Introduced joo.boundMethod() in favor of Function.prototype.bind(). See its ASDoc for details.
• overhauled joo.ResourceBundleAwareClassLoader API. See its ASDoc for details.

Jangaroo Libraries

Together with a new release of the Jangaroo tools, we always release all Jangaroo libraries, too. Besides being recompiled with the latest compiler version, there are also many updates and new features.

• Flash Compatibility jooflash
  This library re-implements the Flash APIs in the browser, using HTML5 features like canvas. It is still rather incomplete, but nevertheless suffices for demos like flash-lines as well as quite complex applications like Box2DFlashAS3.
  
• Network Utilities jangaroo-net
  This new module contains utilities for URI parsing, formatting, relativizing and resolving functionality according to RFC 3986.
  
• Ext JS ActionScript API ext-as
  The library Ext AS is an ActionScript 3 wrapper for Ext JS 3.2.2, so you can do Ext coding with code completion and type checks while keeping a fast turn-around.
• Many more libraries, which we will cover in a future blog post.

As always, comments, questions, corrections, praise etc. are highly welcome! Why not contribute by issuing pull requests on github to include your bug fixes?

Andreas and Frank

Jangaroo 0.7.0 Released

In the latest release, Jangaroo features Runtime optimizations, localization, and semicolon insertion.

Jangaroo Runtime without with

After concentrating on compiler and build process in release 0.6, the new release 0.7 cleans up the Jangaroo Runtime accordingly.
Many features that used to be implemented in the Runtime became obsolete, because the compiler now takes care of them:

• The mapping of private member names now consists of a set of local variable assignments, generated by the compiler. The runtime merely still contributes the class inheritance level, which can only be computed at runtime if we want to keep "binary" update compatibility with libraries. This removed the last with-statement from the generated code! Since with is considered harmful, we are proud to now avoid it completely. This results in less ambigous code ("where the heck does that $foobar variable come from?") and most likely in better performance, since modern JavaScript engines with their just-in-time compilers have better chances to perform optimizations without with.
• Resolving unqualified identifiers (usually class names without package) is no longer done at runtime, but completely at compile time. Even implicit imports, i.e. usages of classes of the same package or the top level package, are detected and made explicit by the compiler. Thus, the runtime no longer has to deal with imports. It still needs to know which other classes to load (i.e. its dependencies). We may re-introduce more concise code for imported classes later.

New Feature: Localization Support

Localization means to provide your software with different texts and configuration, depending on the user's locale settings. For Jangaroo, this means that there should be some standard way to access the current user's locale and that the runtime should be able to load differnet resources depending on that user locale. Since the Runtime can already load classes automatically, representing resource bundles as classes suggests itself. To help you creating such classes, there is a new tool, the Properties Compiler. Actually, it has been included with the Jangaroo tools for quite some time as a hidden feature. But after we have revamped it with the 0.7 release, we're glad no-one (but ourselves) has used it yet ;-). The properties compiler takes a set of properties files for different locales, in Java often called a resource bundle, and generates an ActionScript class for each locale, and one for the defaults. We will add an example to the Jangaroo website soon, also explaining how to let a user choose her locale.

Automatic Semicolon Insertion

The Jangaroo compiler jooc is now capable of inserting semicolons according to the ECMA-262 specification (of which ActionScript 3 is an implementation). For compiler writers: this is done by exploting the error recovery mechanism of the CUP LALR(1) parser generator.
We implemented this feature not beause we like it so much, but to increase our ActionScript 3 compatibility, esp. for the purpose of porting 'legacy' code. For example, we needed to patch the FlexUnit library at many places just because some semicolon was missing. These patches are now no longer necessary.
When writing new code, you should not use the optional-semicolon feature of ActionScript 3, as recommended by Adobe in the Flex SDK coding conventions and best practices.
Semicolon Insertion is considered one of the bad parts of JavaScript, and ActionScript 3 inherited them: a line terminator might trigger semicolon insertion which might change the meaning of the program in unexpected ways. Because of these bad vibes, we added a compiler switch which configures the behaviour of jooc with regard to semicolon insertion. The syntax is -autosemicolon mode, and possible modes are:

• warn (which is the default) will issue a compiler warning if a line terminator is the cause for semicolon insertion
• error will treat this as an error (some kind of strict mode, recommended setting). 
• quirks silently inserts all these semicolons as JavaScript interpreters and Flex compc do (good luck with this setting!)

Note that the ECMA-262 rule which inserts a missing semicolon right before a closing brace ('}') is unaffected by this switch. This rule basically states that a semicolon is optional at the end of a block, which we consider a favourable thing.
One last tip: IntelliJ IDEA offers a code style setting for ActionScript to highlight unterminated statements. Just open Settings - Project Settings - Code Style - JavasScript/ECMAScript/ActionScript and place a checkmark at Use semicolons to terminate statements.

Frank and Andreas

P.S.: As always, we updated the Jangaroo IDEA plugins Jangaroo Language and Jangaroo EXML (containing the properties compiler) to the new version.

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 Packages.com.mydomain.

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.

Jangaroo 0.3: Amplified ActionScript 3 Compatibility

It's been quite a while, but eventually, I am proud to announce Jangaroo 0.3, featuring highly improved ActionScript 3 compatibility and better build and deployment support:

• interfaces, is
• type casts (as and support for the legacy syntax)
  
• bound methods (get this right!)
• no more need to always use this.x instead of x
• *-imports
• fully AS3 compatible Array class
• include directive
  
• annotations (syntax only)
  
• getter and setter methods (unfortunately not in IE)
  
• automatic loading of dependent classes
  
• Maven plugin provides Jangaroo with a flexible and powerful build system
  

Actually, many of these features were already introduced with the 0.2.x versions, but these were only released in the Jangaroo Maven repository. Now, the main effort was to round things off and update all documentation, so please go ahead and re-visit the Jangaroo Web site to find an updated story ("JavaScript 2 is dead, long live ActionScript 3!") and many new technical details.
Jangaroo Tool Support
Jangaroo has always used a subset of AS3, so that all AS3 tools like asdoc and IDEs can be used with Jangaroo code. As mentioned before, IntelliJ IDEA 8 supports ActionScript 3 and thus Jangaroo very well. To top that, we have implemented a Jangaroo IDEA plugin that will be released in the near future.
Porting AS3 Libraries to Jangaroo
Now that we have added all these nice AS3 language features, it is possible to translate most existing AS3 code with the Jangaroo compiler and run it in the browser (without any Flash plug-in!).
For example, we work on a port of FlexUnit and, with very few code changes, can already run its self-test-suite successfully in the browser. Our FlexUnit variant (of course called JooUnit!) will be released shortly, and some of the changes (missing semicolons, mixed DOS/UNIX line end encodings, asdoc glitches) will be submitted back to FlexUnit's main branch.
Of course, making the browser understand AS3 natively is only half the truth: Most AS3 code relies on standard libraries, namely Adobe's Flash API. Thus, another running project is to re-implement the Adobe Flash 9 API in Jangaroo as an adapter to native browser APIs (including canvas for drawing), so that most Flash code and even programs that draw and animate can be run, and as always when using Jangaroo: without a Flash plugin, thus seamlessly embedded into any HTML page!
Based on the Flash API, we recently also managed to compile the whole open source Flex 3.3 framework after some Jangaroo-friendly changes, but it is still quite some way to go until it would actually work, so we hope to get you ActionScript whiz people to contribute soon...
Have fun with a new way of experiencing JavaScript and ActionScript 3! We can't wait for your feedback!

Former Life and Birth of Jangaroo

Today, CoreMedia released a first version of the Jangaroo language and tools as Open Source. This was a wonderful moment for me, because this little project has a long history and played an important underpart in my professional life at CoreMedia over the last years. Please read about it, download, apply, spread the word! Be prepared to develop JavaScript like you never did before! The new Web site should offer you everything for a quick start. If not, feel free to ask! In this first blog post, however, you are going to hear Jangaroo's story, which covers its birth, coming of age, and reincarnation, if you want.

Trying Not to Be Eclectic

When in 2003, I had my first deeper dive into JavaScript, I never had thought it would become a passion. As most Java developers, I despised the style of eclectic programming that was then common among JavaScript hackers: To implement some requirement, they didn't use frameworks or libraries, but grabbed code snippets from other Web pages or forums and somehow assembled them to make them work on their Web pages. My impression was that it is hardly possible to implement serious business in such a patchwork language. But I had to, since a new Web application for CMS content entry waited to be designed and implemented.

Patching a Patchwork Language

My colleague Andreas Gawecki surely agreed on that and decided that, before even starting to dirty our hands on pure JavaScript, we needed a tool to transfer at least some of the amenities of Java to the JavaScript world. But because that was in the days before the Web 2.0 hype and the JavaScript Renaissance, there was no such tool. If you know Andreas, you may be able to imagine what happened: Within a week or so, he had gone through the JavaScript 2 / ECMAScript 4 standard proposals and came up with a compiler that could translate a subset of JavaScript 2 language features to JavaScript 1.x! Of course, Andreas had done research on how classes are usually simulated in JavaScript, and of course he had implemented those JS2-features a Java developer would need most desperately when having to program in JavaScript. I was one of his first Guinea Pigs, and also his primary sparring partner for the language. We started developing tons of JavaScript 2 code, because there were not even JavaScript 1 frameworks available, and we had to do all the cross-browser compatibility code ourselves. Andreas even implemented a Rich Text Editor that had features like table editing that were rare in 2003 - and all that using the JavaScript 2 subset and his compiler.

One Thing Leads to Another

This first shot of the compiler was simply named jscc (JavaScript Class Compiler), and the source file extension was .jsc, so the language was also called JSC. Soon, more tools and libraries followed: Holger Tewis implemented a javadoc-counterpart, naturally called jscdoc, that tricked Java doclets into generating HTML API documentation for JSC programs. I did a port of JsUnit to JSC, needless to say called JscUnit, in about two days (and of course its self-tests were green then). We experimented with writing IDE plug-ins for the unfinished language. Having learned from the WebEditor, we implemented another UI framework, which we so far only used for popping up a context menu on preview Web pages to let the user invoke content-related actions (sounds a bit like breaking a fly on the wheel, doesn't it?).
I loved working with JSC, but to be honest it had some serious drawbacks:

• There was no real IDE support.
• No type checker, types are just remarks used for API documentation.
• Bugs and request were not fairly tracked and never really tackled.
• No class dependencies or automatic class loading: each class file had to be listed, and even in the right sequence before all its depending classes.

Worst, there was almost no documentation and the build process was tied to our primary product. JSC was suffering the typical fate of an internal development tool that had no (paying) customer, although a lot of value or at least potential. At that time, our company grew, and even other projects in the very same company did not use JSC for their JavaScript development. I felt there was something going wrong.

Time for a Change

CoreMedia went through some changes, which opened up new possiblities. We evolved to a learning company, where all members are given time for "peer group" work, i.e. work in small groups of people who pursue a common goal and handle a topic of individual choice. Luckily, I found fellows who were, like me, interested in reanimating JSC. The new spirit and transparency of our company was the perfect breeding ground for the idea to release JSC to the public, as Open Source. It was the perfect candidate:

• En vogue topic.
• Focussed, general purpose tool.
• Not too big to handle.
• Nothing anyone would want to sell: development tools are hard to sell, anyway, and these are not our company's focus.
• We had to document and clean up, anyway, so hardly any additional cost.

The main goal of the peer group, consisting of Andreas Gawecki, Olaf Kummer, Matthias Buse, Mark Michaelis, and myself, was to prepare a decision memo convincing CoreMedia to spend resources on our first real Open Source project.
At that time, JavaScript really enjoyed a renaissance and AJAX was a hype. Interesting new articles about JavaScript mushroomed and inspired me to create a new JSC runtime supporting features like private and protected members, lazy class initializing, and even better readable compiled code. After several iterations, we decided to skip "really private" and protected members for performance reasons, but nevertheless found a solution that does the job to avoid unexpected name clashes. We also updated the language syntax to the latest standard proposals. Suddenly, IDEs started to support ActionScript 3, which is also an ECMAScript 4 language, so we could benefit from that, too.
We were overcoming most disadvantages of JSC. In other words, we had even more to offer than what we had used successfully as an internal tool for years.
The peer-group found that JSC needed a proper name: it should be Web-2.0-ish, cool, foolish, looney (add your favorite adjectives containing oo-s), and artificial, so that we could still grab the domain, the blogger subdomain (sic!), the user ID for community xyz, and so on. All our peer groups have rather silly animal names, and we were True Kangaroo. Replacing the first letter by a JavaScript J and keeping the popular oo-s finally led to Jangaroo. I guess the cool name must have been the critical factor when CoreMedia decided to give us a go.

Walking the Talk

In the execution phase, Masiar Bostanipoor (Web site) and Dennis Homann (build infrastructure, tutorial) joined the team. Andreas and Olaf rounded off compiler (now coherently called jooc) and runtime (where I helped a bit). Olaf wrote most of the language and compiler documentation. Kudos to numerous CoreMedians who helped us with the project, in no particular order and surely not complete: Thomas Stegmann, Gunnar Klauberg, Uli Henningsen, Tobias Baier, Jan Brauer, Carsten Böttcher, Stefanie Wegener, and Christian Pesch.
We used the project time CoreMedia granted us mainly to come up with a stable infrastructure and an appealing presentation (at least we hope so), not to create more tools. We got the domain jangaroo.net, created a Web home for Jangaroo, started this blog, wrote documentation, set up a proper build process involving a Maven repository, cared about license issues (German license jurisdiction is a nightmare!), and so on. Of course, some infrastructure is still missing, most importantly a forum and a bug tracker -- we are working on that, please bear with us! Until then, please comment in this blog for public discussions, and e-mail for direct communication. We also have a twitter user Jangaroo, feel free to follow if you like! Many of the tools and libraries mentioned here may follow jooc, so stay tuned!
I hope you have enjoyed hearing about Jangaroo's first life as JSC and its rebirth as an Open Source project. What I described is just the way I personally remember and feel about things. In the future, be prepared to find a bit more technological facts in my postings...