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

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. 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 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.
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.

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!

Jangaroo Discussion Groups Started

Latest news: We have started two discussion groups for Jangaroo, one for developers and one for "users", i.e. appliers of Jangaroo language and tools:
http://groups.google.com/group/jangaroo-dev
http://groups.google.com/group/jangaroo-users
We felt that commenting in this blog and e-mailing does not really compensate for real discussion groups. The idea of two groups was that tool developer discussions could be quite boring for people who just want to use the tools and see new features. Discussions about new features should be started in the users group, and if the feature is supported by the user community, developers could take over and discuss how to implement the feature.
To get started, I reposted some e-mail discussions in the users group. Please go ahead and read what's there, and feel free to post your comments and opinion!

IDEA 8 Supports ActionScript 3 and JetBrains Supports Jangaroo

One main point about Jangaroo is that it is based on a language being standardized, not inventing a new one. The main advantage is that all kinds of resources available for that language can be reused: documentation, know how, best practices, and last but not least tools.
As a Java developer, I've been using Jetbrains' IntelliJ IDEA since version 5, and I really like it. As far as I can tell, it offers the best code inspections and refactorings in the Java world.
As a Jangaroo developer, I switched to IDEA 8 when the first milestone was available, because to support Flex, IDEA's JavaScript and ActionScript 3 capabilities were boosted. This makes IDEA 8 the best Jangaroo development environment (and thus the best JavaScript IDE) available!
When version 8 became final, I started using an evaluation license, but became a bit nervous how I would continue after 30 days. So I applied for an Open Source license for IDEA, and voilà, after just three days, I received a free unlimited users license for Jangaroo development!
Thank you, Jetbrains, the Jangaroo team really appreciates your support of Open Source software! I can't wait to do a screencast on how to develop, build & debug (!) a Jangaroo application using IDEA 8!
To not seem too biased ;-), in the following, I'd like to give you pointers to other IDEs that can be used for Jangaroo development.
Of course, there is the Flex Builder by Adobe. It may be the best tool to develop Flex applications, but I have to admit I never tried it for Jangaroo. As far as I know, even as an Open Source developer, after the usual trial period, you have to buy a license.
Like Flex Builder, FDT 3 is Eclipse-based and has sophisticated ActionScript 3 support, but targets at Flash (not Flex) development . I tried it with a demo license, and it works really well with Jangaroo code. Although commercial, too, you can apply for an Open Source license as well, and I think I'll do that next.
The last candidate I had a look at is the only free Open Source ActionScript 3 IDE I could find. FlashDevelop 3 (FD) is based on .net and seems to be a quite fully-featured IDE for AS2, AS3 / MXML, and HTML. Being an Open Source project, it might be the right place to add a special Jangaroo mode, although .net is not really our favorite environment (we are a Java shop...).
What all these tools have in common is that they support ActionScript 3, not JavaScript 2 or even ECMAScript 4, and expect ActionScript 3 class files to have the .as extension, not .js2. (IDEA seems to be the only tool that cares about JS2/ES4.) This evidence and the impression that the ECMAScript specification committee seems to deal rather with their team harmony than with solving real-world JavaScript development problems made us move Jangaroo from JS2/ES4 towards ActionScript 3 -- stay tuned for a major update!

Sneak preview of the Jangaroo Maven plugin

Good news for Maven2 users: with the introduction of the jangaroo-maven-plugin, it will soon be easier than ever to compile Jangaroo sources as part of your build process.

The plugin is an alternative to the provided Ant task and will be part of the next Jangaroo tools release. In the meantime you can already try the 0.1.2-SNAPSHOT version from the Jangaroo snapshot repository. The following pom.xml demonstrates how to use the plugin to build the helloWorld example, which is included with the Jangaroo distribution. Simply create a file called pom.xml in the root directory of the example (the one containing the build.xml file) and paste the following to it:

<project xmlns="http://maven.apache.org/POM/4.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                            http://maven.apache.org/maven-v4_0_0.xsd">
 <modelversion>4.0.0</modelversion>
 <groupid>net.jangaroo.examples</groupid>
 <artifactid>hello-world</artifactid>
 <packaging>war</packaging>
 <version>1.0-SNAPSHOT</version>
 <name>hello-world-example</name>

 <pluginrepositories>
   <pluginrepository>
     <id>jangaroo</id>
     <name>Jangaroo repository</name>
     <url>http://repo.jangaroo.net/maven2</url>
   </pluginrepository>
   <pluginrepository>
     <id>jangaroo-snapshots</id>
     <name>Jangaroo repository</name>
     <url>http://repo.jangaroo.net/maven2-snapshots</url>
     <snapshots>
       <enabled>true</enabled>
     </snapshots>
   </pluginrepository>
 </pluginrepositories>

 <build>

   <plugins>
     <plugin>
       <groupid>net.jangaroo</groupid>
       <artifactid>jangaroo-maven-plugin</artifactid>
       <version>0.1.2-SNAPSHOT</version>
       <executions>
         <execution>
           <id>compile-jangaroo-sources</id>
           <goals>
             <goal>compile</goal>
             <goal>copy-runtime</goal>
           </goals>
           <configuration>
         
             <!-- Default output directory is
                  {project.build.directory}/${project.build.finalName}/js
              -->              
             <outputdirectory>
               ${project.build.directory}/${project.build.finalName}
             </outputdirectory>            

             <!-- All of the following configuration parameters are optional,
                  the values shown are the defaults.
               -->              
             <sourcedirectory>
               ${basedir}/src/main/js2
             </sourcedirectory>            

             <verbose>false</verbose>
             <debug>true</debug>
             <debuglevel>source</debuglevel>
           
           </configuration>
         </execution>
       </executions>
     </plugin>

     <plugin>
       <artifactid>maven-war-plugin</artifactid>
       <version>2.1-alpha-2</version>
       <configuration>
         <failonmissingwebxml>false</failonmissingwebxml>
       </configuration>
     </plugin>

   </plugins>

 </build>
</project>

Two mojos are available and will usually be run together: compile and copy-runtime. The latter one extracts the Jangaroo runtime joo/Class.js to the output directory.

To build the project, run mvn package in the directory containing pom.xml. Obviously, a working Maven2 installation is required to do so.

We still have some important homework to do before the plugin will be released, such as serious documentation or an option to concatenate all compiled output files into one compact JavaScript file. However, feedback to the plugin at this early stage is higly welcome. Just drop a comment below.