Jangaroo at FlashCodersNY

Tyler Larson of FlashCodesNY asked us whether we'd be interested to present and discuss Jangaroo on one of their weekly meetings in Manhatten. The event took place on Wednesday 17th of November in Manhattan, while Andreas and I were connected via live streaming from Hamburg. Well, our time zone offset is not really ideal for meetings in the late afternoon in New York, but with lots of coffee and adrenaline, we hopefully managed to give an exciting presentation of what Flash coders can do with Jangaroo.

After showing some general slides about Jangaroo, we went right into coding with the brand new Jangaroo version 0.7.12. Using IntelliJ IDEA 9 as the cockpit for development, we showed how to import and build a Jangaroo Maven project. Examples of Jangaroo-Flash projects were the well-known Box2DFlashAS3 Jangaroo port and a Jangaroo version of AS3 Lemmings.
Most attendees liked the idea of being able to deploy Flash applications to the browser without a FlashPlayer plugin. However, they were also concerned about performance especially on mobile devices (iOS JavaScript and canvas performance currently only suffices for quite simple applications) and API completeness, correctness and compatibility. One feedback concerning missing AS3 features in Jangaroo was that against our previous assumption, some developers like and use E4X quite a lot. Also better support for annotations is important for using certain Flash/Flex libraries, e.g. FlexUnit 4.

To run Flash code directly in the browser, Jangaroo not only has to compile ActionScript 3 to JavaScript, but also all Flash APIs have to be re-implemented. While the documentation is under a Creative Commons license and can be reused, the implementation is not open. One central feature of Flash are the graphics, which can be emulated in the browser by using HTML5's canvas. Our library "jooflash" does exactly that. This is a big effort.We challanged all FlashCodersNY and of course any other Flash coder enthusiastic about Open Source to contribute to the jooflash library. jooflash is available on github, so please go ahead, fork, code, and do a pull request!
In the session, there were many in-depth questions about how to debug Jangaroo code, how to use other IDEs, and many more, which indicated great interest in the technology.
For example, one very interesting new topic was whether multiple embedded Jangaroo "Flash objects" on the same page are possible and how they behave. The answer is yes, you can run many Jangaroo applications on the same page. Usually, all code is loaded directly into the page, leading to shared classes, but also to shared static variables. If this is not what you want, simply load each application in an iframe. A more elegant solution that shares code, but not state, would require changes in the Jangaroo Runtime.

Although only virtually present, we felt really welcome and were quite amused when we were asked the final question: "When was the last time you stayed up until 3 o'clock in the morning?"
Thanks FlashCodersNY, it was worth it!

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.6.0 released: No More Guessing

This brand new Jangaroo version comes with several improvements which further enhance our ActionScript 3 compatibility.

Up until now, the Jangaroo compiler jooc processed one source file at a time, without taking a look at declarations residing in other source files. However, in certain situations, jooc needs to decide whether a given symbol denotes a class, a package-global function, and whether it is static or a non-static member. This information is important because jooc has to generate different JavaScript code in each case.

jooc based some of these decisions upon heuristics and generated a warning if he wasn't sure (e.g. the warning "undeclared identifier foo, assuming it is an inherited member"), just to tell you about it, giving a chance to review the decision. However, this typically generated a lot of warnings, and nobody actually cared about them any more (broken window effect).

We now took off the blinders and enabled jooc to look into sources other than the single one at hand. This allows the compiler to do his job based on facts, not on assumptions.

On the other hand, now jooc needs to find the definitions of all external symbols which are used within a given source file. We added two new compiler switches which tell jooc where to look for these:

• -sourcepath: a list of source root directories in the same module (e.g. "src/main/joo;target/main/generated-sources/joo;src/test/joo"), and
• -classpath: a list of directories or Jangaroo module jars where to find symbols in module dependencies.

Furthermore, we added another compiler switch -api which tells jooc to generate so called API stubs for your ActionScript sources. These stubs contain just the API part of your code. That is, any private members are left out, and all methods are declared native, leaving out the method body. Any API documentation comments before the remaining declarations are retained. These API stubs are looking quite similar to the ActionScript files we are using as the API declaration for native JavaScript libraries (e.g. Ext JS).

If you are using Maven to build your Jangaroo application (as we do), you are lucky: the new version of the Jangaroo Maven Plugin configures all these new compiler switches with reasonable defaults. Your Jangaroo project should build right out of the box with the new Jangaroo version. The new Jangaroo Maven plugin automatically generates and packages API stubs for every Jangaroo module into the META-INF/joo-api directory within the module jar file.

We also updated the Jangaroo IDEA plugin to take advantage of the new compiler switches. The Plugin is now compatible with IDEA 9.0.2. By the way, a neat side effect of the new API stub packaging is that you may now both get a 'green square' for sources within the IDEA editor and access the API documentation with Quick Documentation Lookup (CTRL-Q) without having to download the source artifacts of dependencies.

Last but not least, here are some additional enhancements which come with the new Jangaroo version:

• Static superclass members are now in scope which means that you do not need to qualify the member with the superclass identifier any more.
• Private members of the same class are now also accessible for parameters and variables. Previously, private members where only accessible if (implicitly or explicitly) qualified by this.
• Old-style type casts are now recognized correctly and commented out in the generated JavaScript code, just like the new-style type casts using the as keyword. Note that we still do not generate any runtime code for both kinds of type cast.
• The restrictions of dynamic class loading are removed, you may now use *-imports and put classes under other source root directories, given you configured the -sourcepath option accordingly.
  

Not to mention many internal compiler re-factorings which simplified the code base, much better test coverage and lots of bug fixes.

As always, we’d be glad about feedback and hope you have fun developing with Jangaroo!

Jangaroo on The Flex Show

Edit: On 08/13/2010, I corrected some outdated information using strike-through and italics.
A couple of days ago, Jeffry Houser and John Wilker of The Flex Show gave me the chance to talk about Jangaroo. Thank you again! Today, the episode has been published, so I'll repeat some of the things mentioned in the interview here and provide some updated information you may need to get started with Jangaroo.
John and Jeffry asked for the differences between AS3 and Jangaroo, which are documented here.
You can find the Flash / Jangaroo demo mentioned in the interview here. It is an example of how to use Jangaroo to run a Flash demo without a Flash plugin. The AS3 source code, borrowed from Andre Michelle, is compiled to JavaScript with the Jangaroo compiler, using the Jangaroo Flash Library (which is still quite incomplete, but suffices for this demo). With only a few lines of JavaScript, that code is loaded and run in any browser supporting the HTML5 canvas element (i.e. not IE). If you are connected to the Internet and your browser has a Flash plugin, you can also see the original demo running in a Flash player at the right side. Don't they look like twins?

My personal project, the game "Jangaron", completely developed using Jangaroo, is located at http://www.jangaron.net.

In the interview, I mention the Maven build process. Since the information on our Web page is not really up-to-date (shame on me), I'll step you through getting started with the demo / example I mentioned.

1. Download and install Maven 2.2.1.
2. Download and unpack the demo source code.
3. Point a command line to the directory where you unpacked the demo source code and run
   mvn package
   If this is your first Maven build, you have to be online and it may take a while.
4. When the build process has finished successfully, a full Web application has been created under target/flash-lines-0.1.1-SNAPSHOT. Simply open the following file in any browser but IE (alas: no canvas!):
   target/flash-lines-0.1.1-SNAPSHOT/index.html

If you want to play around with the demo, I recommend using IntelliJ IDEA 8.1.4 9.0.x Ultimate (where x > 1 for the Jangaroo plugin to work!). They offer a 30 day trial, and if you want to use IDEA to contribute to the Jangaroo project, there also is a free Open Source license which can be obtained by applying via mail.
Note that the Jangaroo plugin is currently not compatible with IDEA 9 -- the update is in progress, stay tuned!
If you'd rather use a free, Open Source IDE, since there is no free AS3 support for Eclipse yet, I recommend Flash Develop. I'm not an expert for FD, but I managed to edit Jangaroo source code with FD, and it felt quite nice. I'm sure the FD guys will help you getting started!

Getting started with IDEA 8 9 and Jangaroo is really simple and consists of the following steps:

1. Install the Jangaroo Language Plugin (see below).
   
2. Import the demo Maven project (see below). Only do this after installing the plugin, as it also plugs into IDEA's Maven import process!

In detail, installing the Jangaroo Language Plugin:

1. Open "Settings", "Plugins".
2. Select the "Available" tab.
3. Find the "Jangaroo Language" plugin. As of today, latest version is 0.3.22 9.0.7.0.0.
4. Right-click, "Download and Install".
5. IDEA asks you to let it restart. Do so.

Importing the demo Maven project:

1. Create a new project (from the start screen or "File", "New Project").
2. Select "Import from external model", "Next".
3. Select "Maven", "Next".
4. Select the root directory of the downloaded demo sources (the one that contains the pom.xml), "Next".
5. The only Maven project found is preselected. "Next".
6. Confirm name and project with "Finish".
7. After the import is finished, in the "Maven Projects" window, click "Download artifacts" (the third button in "Maven Project" window's top toolbar). After that, the AS3 code should be "green" (or "yellow", but not "red").

You have to build the Web application once using Maven as described above or from inside IDEA as follows. In the "Maven Projects" window, you open the root node of the tree, then "Lifecycle". Find "package" and start (click green arrow, you can also double-click "package" right away).
After that, you can use IDEA's make process to a) get a quicker turn-around and b) jump to error locations directly with a double-click. Use "Make Project" (Ctrl-F9) to build incrementally, which is way faster than a Maven build and provides better compiler error messages. After building, simply reload the page in your browser. You may need to reload without cache (Ctrl-R) or even clear the browser cache for changes to take effect. For Firefox, there is a nice plugin for that called "Clear Cache Button".

Now, you can develop a JavaScript based Web application with a level of convenience never achieved before. The key to that is that ActionScript, as a typed language, gives the IDE far more options to offer correct completions and refactorings than JavaScript. Go ahead a try IDEA's completion (Ctrl-space), quick documentation lookup (Ctrl-Q), parameter info (Ctrl-P), or goto declaration (Ctrl-B). Try rename refactoring or "introduce variable". Granted, not all refactorings known from Java are yet available, but Jetbrains are continuously improving AS3 support. Enjoy!

If you have any problems or questions, feel free to comment here, post in the Jangaroo developer group, or contact us directly.