What is Java2Script?

TODO: unify and simplfy all content of this section

Java2Script is an Eclipse plugin that helps you write your web applications in Java. This means that your Java codes will be automatically translated into JavaScript which can be executed in a web page. With Java2Script you can transform your java application in a pure javascript application, reusing your java codes in your Rich Internet Applications (RIA), and most of all being able of developing your RIA 100% in java code just like if you were developing another java project.

As you would know, in a common java application this is what happen: First the .java files need to be compiled by the java compiler into .class files. Only then you can execute your program: calling the "java" command the java virtual machine will load and execute the .class files.

As we will see, in a Java2Script application something similar happens. First we need the java2script translator to translate out .java files to .js files and only then we are ready to load and execute the program from javascript in a browser.

A general diagram showing the roles of the Java2Script framework compared with the Java development kit is shown in the followign figure:

For all of this, Java2Script provides with the following components:

• A java to javascript code translator (compiler). that translates each .java in a java source folder to a .js file, just like the java compiler javac translate .java files into .class files.

• Java language and java runtime emulation. Javascript support for loading and executing generated JavaScript in the browser, including java language emulation utilities such as ClassLoader that will lazily load JavaScript code as required, Object Oriented Programming emulation, etc

• Java core utilities. An implementation of Java SE SDK library is translated, by the Java2Script compiler, to JavaScript. It is available to the Java programmer in HTML document. Currently Apache Harmony Java SE SDK implementation is used.

The following shows a more general architectonic idea involving all the components in developing Java2Script applications.

For "running" our java programs in a browser, Java2Script also supports a java language emuilation library, letting as easyly configure, load and execute our java translated code inside an html document from javascript.

Also, Java2Script comes with known java libraries like (TODO links) SWT, JUnit and other Java tools translated to JavaScript by Java2Script compiler. All this translated-tools are inside the j2slib folder and are lazily loaded by the J2S class loader when needed by J2S applications. These componenets are:

1. SWT. SWT version 3 support is available! You can develop your rich internet application without having to learn another GUI toolkit API. More, you can develop applications which can be distributed for both desktop (Java+SWT) and internet!

2. ajax - simple RPC support. Aiming to help Java developers balancing and debugging *local* and *remote* procedure calls for AJAX RIAs without knowledge of serialization and deserialization. TODO: http://blog.java2script.org/2006/10/12/java2script-introduces-simple-rpc/

3. JUnit. So you do not need to learn or develop another testing framework.

4. YUI and others. The fact is Java2Script make it easy to port existing Java frameworks to JavaScript and vice versa. With a little more imagination, you can port existing JavaScript frameworks, like YUI, to Java. That is just the mission of the project yui4java that among other things contain tools that easily let the Java programmer to access JavaScript language constructions and Java API for YUI version 2 and 3 and other known JavaScript toolkits.

Demonstrations

Enough talking, here are some interesting web applications made 100% in Java using Java2Script:

1. Google Talk Client in Java2Script. Google Talk Client in Java2Script is a pure JavaScript copy of Google Talk Client from non-Google communities. It is first implemented in Java language using Eclipse SWT and Smack (A library for Jabber's XMPP). Then the client is converted to JavaScript with servlet supports. And then it's deployed on a Tomcat server. As Java being platform-independent, and JavaScript is browser-independent, this Google Talk client runs in any modern browsers, such as Firefox, Opera, and Internet Explorer (IE), on Windows, Linux, Mac and others OS platforms. For more details or architectural information, please visit blog "Inside Java2Script".

2. WeMail Web Mail Client. WeMail Web Mail Client is a free web mail client for Google Mail, Hotmail/Live Mail, Yahoo! Mail, AOL/AIM Mail and other mail providers that support POP/IMAP & SMTP. In case these mail services are blocked by your network firewall in office, you still can access to your mails by using WeMail. WeMail is designed to be used anywhere, Windows/Linux PC, Mac, home or office behind firewall. WeMail uses similar Gmail UI, so those Gmail users should feel much comfortable. WeBuzz.IM team is dedicating to build web mail client services with better security, accessibility and user experience.

3. SWT Control Examples. SWT Control Examples contain tests for common SWT widgets. You can download the swt-control-examples-1.0.0.zip, unzip it and view the example locally.

4. Java2Script demo web applications. Java2Script demo web applications contains some of SWT based mentioned demo applications and more, like MSN, Facebook, ICQ, AOL, Yahoo, Jabber, tetris game and other demo applications made with java2script. It shows how several SWT based applications can be presented in one web page.

5. Advanced Image Viewer. Advanced Image Viewer let you load, view and manipulate your images online. Several image operations are supported, like rotation, zoom, alpha, import/export and advance image filters like blur, emboss, high/low pass filters, edge detection filters and general image convolution based filters are available. This project is a work in progress. For those users who need advanced manipulation technics and filters for online image viewing. 100% client side. Unlike the other java2script projects, it uses YUI instead of SWT for the GUI. And it also uses raphaeljs frameworks, which is ported to Java thanks to yui4java project.

Comparing Java2Script to other similar technologies

TODO: do not know if this section goes here... TODO write this better.

If you are already familiar with other framework that let you write web pages in java, like GWT [1] , you may wonder what are the main differences and similarities of those with Java2Script

When Java2Script is compared to other technologiess like GWT, RAP and other more server side oriented technologies.

* it can't be run outside Eclipse, 

* it makes a direct compilation from .java to .js file. Concepts like compilation unit, class, classloader are
available

* it has a lazy Java class loader 
   
* it let you write your native
javascript code easily section: the run as dialog: todo. show picture
TODO: explain the porpuse of each item 

* use unchecked "Use global j2slib"
only for development. If you want to put your j2slib application in a web
server, you must indicate questions: ¿is there an official j2slib
published version on some url, so user can use in his/her web
applications without having to have/upload their own j2slib
folder?



other comments about j2s vs gwt of mine (not sure of its accuracy):


about gwt vs java2script, I think they are similar tools. IMHO de big desition in this kind of projects is ¿how much I have to restrict the java programmer so the resulting javascript code size is acceptable? What I've seen of gwt is that its resulting javascript code size is lower than in java2script. But this is because:

* the translate .java into a very compressed (and ofuscated) javascript code while java2script do an straight and clear translation of .java to .js

* there are restrictions about java.lang and java.util compared to java2script

* only java 1.4 syntax is supported by gwt while in java2script all java syntax versions are supported. - (not so true now!)

* as a result it is easier of porting existing java code and toolkits to javascript with java2script

* java2script provides with metodologies that easily allow to port existing javascript toolkits to java like yui4java

* it is nicely integrated to eclipse IDE: it is very easy to use if you already know about eclipse java projects.

* finnaly somehting totally subjective: I discovered java2script when I was starting to research and develop a product very very similar to java2script (an eclipse plugin based on jdt for translating java to javascript). I think at the moment, that was my first motivation of joining java2script team.

Also I've seen other projects for allowing to program RIA in java that heavily use server side for GUI computations (like layouts). Among others :

http://www.eclipse.org/rap/
http://www.fybit.com/products/riatrax4js  

This is different to java2script and gwt since the "translation result" is both to javascript+html and serverside.

Also, I've seen other java to javascript compilers that are actually java vm implementations on javascript that "execute" .class files in the browser... a completly different approach to java2script and gwt

    

A simple Java2Script application

As with any Java application, the first thing is to create an Eclipse project. But instead of creating a common Java application project, we will create a Java2script application project. To do so, go to menu File -> New... -> Other... and in the dialog select Java2Script Project:

The following steps for finishing creating the Java2Script project are equal to Java project's. Just enter a valid project name and click next/finnish. Congratulations you have created your first Java2Script project!

Now, we will create a simple Java hello world program and see how easily can be executed in an HTML document. First create a Java package like my.first.project and add a Java class named HelloWorld inside it with the following code:

package my.first.project;

public class HelloWorld {

	public static void main(String[] args) {
		System.out.println("hello world");
	}

}
    

Save the file with CTRL + S. Now we will execute the HelloWorld class as a Java2Script application. An HTML document named my.first.project.HelloWorld.html will be created that launch our little Java application. You can launch your Java2Script application in the same way you launch a normal Java application: right click you Java code -> Run As -> Java2Script Application:

When you run a Java class as a Java2Script Application, the J2S console Eclipse view will be opened and it will show an HTML document which will execute your Java application. This view is a simple browser and in fact you can also open the generated HTML document with your favourite browser:

Congratulations, you have just executed your first Java2Script application! As you can see, java2script simulate the System.out.println method call pending a paragraph with text to the html document. Another thing to notice, is that if you refresh your project, you will see a new html file at the root

Configuring your Java2Script application launcher.

A very important part of Java2Script plugin is the application launcher configuration. By default, Java2Script applications will be launched from local filesystem and will point to the j2slib.js file that is inside your eclipse's plugins/ directory.

When you run your application the first time, a Java2Script application launcher configuration is created. For editing it, you just rught click on you java file -> Run Configgurations... As you may see, there are two new tabs in the application launcher configuration.

The first tab, HTML, is used to introduce html code at the <head> or <body> html elements of the generated html document, like scripts, CSS stylesheets, etc. We will call this tab the "HTML configuration tab":

The Miscellaneous tab is used to specify, among other things, the location of the j2slib.js file, the location of generated .js files (the bin/ folder URL), firefox addon support, etc:

The most important item to configure here is the location of j2slib.js file. By default, Java2Script are launched pointing to plugins/ internal j2slib.js filesystem version, for example :

   <script type="text/javascript" src="../../j2s_3.6_workspace/net.sf.j2s.lib/j2slib/j2slib.z.js">
   

This is aceptable for developing because the Java2Script application will be loaded fast from filesystem. Nevertheless, you should change this if you want to deploy your application to a web server. A common practice is to copy your eclipse classic helios/plugins/net.sf.j2s.lib_2.0.0/j2slib/ folder inside your Java2Script project and configure the application launcher to use a Global .js URL for your j2slib base:

Java2Script project

this section describe project configuration, project properties page, .j2s file, in .j2s file

TODO

J2S Java to JavaScript compiler

The most important component is the java to javascript code translator. This is an eclipse plugin, based on eclipse java develpment tools (JDT / http://www.eclipse.org/jdt/), that will compile your eclipse java project to javascript.

1. Object oriented JavaScript simulator is introduced
2. JavaScript ClassLoader is built inside
3. Eclipse JDT based Java to JavaScript compiler, support Java
1.4 and Java 5 features, including generic, enums, static imports,
enhanced loops
4. Support incremental building for Java projects
5. Support Hotspot JavaScript swapping for debugging
6. Support most classes in java.lang.*, java.utils.* and others
packages
7. Support native JavaScript through @j2s* Javadoc in Java sources and java anotations

      

TODO: do this better. Ideas: * talk about compiler supported java versions, * in section chap-java-to-js-translation will talk about code tranlation *

Application launching

this section describe j2s app launcing in detail

TODO

Debugging

how turn on debuggin?

what happens when debug is on?

package org.sgx.j2s.js;

import org.sgx.j2s.html.HTMLUtils;

public class HotSpotTest1 {
  int counter = 0;  
  
  public static void main(String[] args) {
    new HotSpotTest1().test();
  }
  
  public void test() {
    
    //creates an html button element in document.body, with label "click me" and 
    //with an event handler that will call doCLickAction() instance method
    
    HTMLUtils.createButton(JsUtils.document().body, "click me", new Runnable() {
      public void run() {
        counter++;
        doClickAction();
      }
    });   
  }

  protected void doClickAction() {
    System.out.println(counter+" say hello!");
  }

}

protected void doClickAction() {
  System.out.println(counter+" say hello CRUEL WORLD!");
}

Libraries in Java2Script

In this section we will detail mechanisms provided by Java2Script plugin for using and distributing java software. How java software components can be distributed so other Java2Script users can use them in their J2S porojects.

Suppose you develop a very useful software component in Java2Script and now you want to distribute so other can use it in their own java2script projects. In normal java project we normally put our .class files inside a .jar (Java ARchive) file, and distribute the .jar. That is enought, but not in a java2script project where, besides .class files you must also can distribute generated javascript files.

Of course you can always distribute your library sources, and let the users import the osources into their own projects, perhaps in differents sourcefolders, but that is generally a good idea when you want to encapsulate your library api and implementation.

Fortunately, Java2Script provide with flexible mechanism of library definition. Also as we will see, Java2Script support for defining how the library must loaded

TODO: talk about j2slib and how swt, junit etc are inside. TODO: talk about .j2x files and package.js files that le definehow alibrary must be loaded. Also, try and if works to dev a library, put it in other folder that j2slib, with a pacakge.js and lib.j2z file, and show how oackage.js is evaluated, and how to use it for loading one, concatenating several files, etcx

TODO: p/d: future extension packer can be mention here for intelligent generattion of big .js file .

Command line API

TODO: document here the expiremental support for j2s console api. ?

Using unsupported java classes

Let's see what happen when we try to use unsupported java classes in our Java2Script applications. Let's create java class with the following content:

package foo.bar;

import java.io.File;

public class WontWork {
  public static void main(String[] args) {
    new File("foo.txt");
  }
}

Let's see if Java2Script compiled the class. Save the file, right click and choose "Edit converted *.js" option from the context menu:

Clazz.declarePackage ("foo.bar");
Clazz.load (null, "foo.bar.WontWork", ["java.io.File"], function () {
c$ = Clazz.declareType (foo.bar, "WontWork");
  c$.main = Clazz.defineMethod (c$, "main", function (args) {
    new java.io.File ("foo.txt");
  }, "~A");
});

So, as we can see in line 5 of the generated js file, the java class is translated anyway, no matter if it contains or reference a not supported java class. The compiler won't fail, but if we execute the class as a J2S application, the generated html will contain a message error like the following:

[Java2Script] Error in loading ../path/to/j2slib/java/io/File.js!

More, if we open the html document with firefox, the following javascript error will be thrown in the Firefox error console:

Error: java.io.File is not a constructor
Source File: file:///path/to/project/bin/foo/bar/WontWork.js
Line: 6

Remember we have said that one of the main porpuses of J2S is to let the user to reuse Java codes inside web applications. So, this feature of not failing at compile time but at run time can be usefull when trying to compile an existing Java library or framework to javascript because the Java code will be compiled no matter if it contains not supported java classes. Also, generated javascript will run OK as long as the unsupported classes are not needed. But will fail when trying to load an unsupported class with a message like we have showed.

JRE Emulation Reference

TODO. instead only listing files, argument how well is supported each class with .,..

Java2Script includes a library that emulates a subset of the Java runtime library. The list below shows the set of JRE packages, types and methods that Java2Script can translate automatically. Note that in some cases, only a subset of methods is supported for a given type.

• Package java.lang

• Package java.lang.annotation

• Package java.lang.reflect

• Package java.io

• Package java.util

Package java.lang

Almost all java language classes are supported. The main restriction is with classes related with Threads, like java.lang.Thread,

workspace/net.sf.j2s.java.core/src/java/lang> ls
AbstractMethodError.java             CloneNotSupportedException.java    InstantiationException.java      SecurityException.java
AbstractStringBuilder.java           Comparable.java                    Integer.js                       Short.js
annotation                           Console.js                         InternalError.java               StackOverflowError.java
Appendable.java                      Copy of Boolean.js                 InterruptedException.java        StackTraceElement.java
ArithmeticException.java             Double.js                          Iterable.java                    StrictMath.java
ArrayIndexOutOfBoundsException.java  Encoding.js                        LinkageError.java                StringBuffer.java
ArrayStoreException.java             Enum.java                          Long.js                          StringBuilder.java
AssertionError.java                  Enum.js                            NegativeArraySizeException.java  StringIndexOutOfBoundsException.java
Boolean.js                           Error.java                         NoClassDefFoundError.java        String.js
Byte.js                              ExceptionInInitializerError.java   NoSuchFieldError.java            ThreadDeath.java
Character.java                       Exception.java                     NoSuchFieldException.java        ThreadGroup.java
CharSequence.java                    Float.js                           NoSuchMethodError.java           Thread.java
ClassCastException.java              IllegalAccessError.java            NoSuchMethodException.java       Throwable.java
ClassCircularityError.java           IllegalAccessException.java        NullPointerException.java        TypeNotPresentException.java
ClassExt.js                          IllegalArgumentException.java      NumberFormatException.java       UnknownError.java
ClassFormatError.java                IllegalMonitorStateException.java  Number.js                        UnsatisfiedLinkError.java
Class.js                             IllegalStateException.java         OutOfMemoryError.java            UnsupportedClassVersionError.java
ClassLoader.js                       IllegalThreadStateException.java   Readable.java                    UnsupportedOperationException.java
ClassLoaderProgressMonitor.js        IncompatibleClassChangeError.java  reflect                          VerifyError.java
ClassNotFoundException.java          IndexOutOfBoundsException.java     Runnable.java                    VirtualMachineError.java
Cloneable.java                       InstantiationError.java            RuntimeException.java        

Package java.io

This is the package with more restrictions. Nevertheless, there is support for some kind of Streams that can be emulated in javascript.

/sgurin_workspace/net.sf.j2s.java.core/src/java/io> ls
BufferedInputStream.java    CharConversionException.java  FilterOutputStream.java      NotSerializableException.java  StringBufferInputStream.java
BufferedOutputStream.java   Closeable.java                Flushable.java               ObjectStreamException.java     StringReader.java
BufferedReader.java         DataInput.java                InputStream.java             ObjectStreamField.java         StringWriter.java
BufferedWriter.java         DataOutput.java               InterruptedIOException.java  OptionalDataException.java     SyncFailedException.java
ByteArrayInputStream.java   EOFException.java             InvalidClassException.java   OutputStream.java              UnsupportedEncodingException.java
ByteArrayOutputStream.java  Externalizable.java           InvalidObjectException.java  Reader.java                    UTFDataFormatException.java
CharArrayReader.java        FileNotFoundException.java    IOException.java             Serializable.java              WriteAbortedException.java
CharArrayWriter.java        FilterInputStream.java        NotActiveException.java      StreamCorruptedException.java  Writer.java
    

Package java.util

In general, all kind of collections and utils are supported. Some utilities have limited support, like Date and Regexp. There is no support for DateFormat stuf. Utilities related to unsuported features like filesystem and Threads, like Timer, TimerTask are not supported. TODO: folrmalize this.

/sgurin_workspace/net.sf.j2s.java.core/src/java/util> ls
AbstractCollection.java                      HashSet.java                           MissingResourceException.java
AbstractList.java                            Hashtable.java                         NoSuchElementException.java
AbstractMap.java                             IdentityHashMap.java                   Observable.java
AbstractQueue.java                           IllegalFormatCodePointException.java   Observer.java
AbstractSequentialList.java                  IllegalFormatConversionException.java  Properties.java
AbstractSet.java                             IllegalFormatException.java            Queue.java
ArrayList.java                               IllegalFormatFlagsException.java       RandomAccess.java
Arrays.java                                  IllegalFormatPrecisionException.java   Random.java
Collection.java                              IllegalFormatWidthException.java       regex
Collections.java                             InputMismatchException.java            ResourceBundle.java
Comparator.java                              InvalidPropertiesFormatException.java  Set.java
ConcurrentModificationException.java         Iterator.java                          SortedMap.java
Date.js                                      LinkedHashMap.java                     SortedSet.java
Dictionary.java                              LinkedHashSet.java                     Stack.java
DuplicateFormatFlagsException.java           LinkedList.java                        StringTokenizer.java
EmptyStackException.java                     ListIterator.java                      TooManyListenersException.java
Enumeration.java                             List.java                              TreeMap.java
EventListener.java                           ListResourceBundle.java                TreeSet.java
EventListenerProxy.java                      Locale.java                            UnknownFormatConversionException.java
EventObject.java                             MapEntry.java                          UnknownFormatFlagsException.java
FormatFlagsConversionMismatchException.java  Map.java                               Vector.java
FormatterClosedException.java                MissingFormatArgumentException.java    WeakHashMap.java
HashMap.java                                 MissingFormatWidthException.java
    
    

Package java.util

TODO: how well supported are util.regex ?

/workspace/net.sf.j2s.java.core/src/java/util/regex> ls
Matcher.java  MatchResult.java  Pattern.java  PatternSyntaxException.java

Java2Script SWT

1. Eclipse SWT 3.1 API is ported for JavaScript in modern browsers,
Firefox, Internet Explorer, Opera, Safari
2. Desktop and window manager are built inside
3. Support UI blocking fow SWT's Shell and Dialog
4. Support SWT deffered layout
5. Support detecting font size change in Firefox
      

You may take a look at SWT example for a Java2Script application that intensively uses SWT. In this section however, we will make a SWT based application from scratch for showing how easily it is.

TODO: what is not supported is this version of SWT is the GC, etc.

Java2Script AJAX

TODO: do this section better.

1. HttpRequest/AJAX is introduced for both Java and JavaScript
2. Simple RPC API is introduced to call back Java server, which
supports Cross Site Scripting
3. Simple and Compound Pipe API is introduced to setup Comet 
connection to server.
4. Support dynamic class loading for both Java and JavaScript
5. Support Java reflection (early implementation)
      

Using @j2s tags in JavaDoc

Java2Script compiler supports some "directives" that the user can include in its java code inside javadoc comments, that affects how a java element, like a method, a class or simple code block is translated to javascript. So the javadoc always must go before some java block of code. Also, usually this directives accepts some input that must be after the @j2s directive in the same javadoc. In the following java segment, we use the directive @j2sNative to tell the J2S compiler that a java code block must be replaced by some native javascript code that we give:

System.out.println("Code before");
/**
 * @j2sNative
 *
 * alert("a javascript native statement");
 */
{
    System.out.println("these statements will be replaced");
} 
System.out.println("Code after");

that will be translated to

System.out.println("Code before");
{
alert("a javascript native statement");
}
System.out.println("Code after");

The important thing to notice here is how the java statement inside the block ("these statements will be replaced") is not present in the translated code, and it was replaced by the javascript statement alert("a javascript native statement"); that we wrote inside the javadoc comment, after the @j2sNative directive.

All these @j2s annotations that we will describe later in more detail, are used the same way. First of all, they must be inside a JavaDoc comment. JavaDoc comments are special comments that begin with /** instead of /*. This JavaDoc comment have to go before a java code entity, like a method definition, a class definition or a code block. Second, the javadoc must contain a special J2S annotation like in the previous example, @j2sNative . We call this @j2s annotations J2S compiler directives, since they let us customize in some ways the compiler output code. Also, in most cases, the J2S compiler directive accepts some text input, like in the last example the javascript native code, and act over some java element, like in the last example, the java code block.

Writing native JavaScript code with @j2sNative

the @j2sNative is perhaps the more important @j2s directive of all. It allow the java programmer to replace a java block or method body with native javascript code.

Let's take simple example: you want to get current browser name in your java code. Java doesn't provide with such functionality, so we must to do it with native JavaScript code. (Remember that in javascript we can get the full browser name with the statement navigator.userAgent). For doing this we will use the @j2sNative JavaDoc annotation for embbeding native javascript code inside the java code. In the following example, notice the java comment with the @j2sNative string and the javascript code before the empty java block {}:

String fullBrowserName = null;                            

/**                                                       
 * @j2sNative                                             
 * fullBrowserName = navigator.userAgent;                 
 */{}                                                     
 
System.out.println("Full browser name is : "+fullBrowserName);

The above code will be translated to the following javascript code:

var fullBrowserName = null;
{fullBrowserName = navigator.userAgent;}
System.out.println ("Full browser name is : " + fullBrowserName);

Notice how the empty java code block has been filled with the native javascript code that we introduced inside the @j2sNative JavaDoc.

Since this compiler directive is so important and has several usage scenarios, we will discuss its usage in detail in a separate chapter Chapter 9.

A more complex example that shows all use cases. Read the javadocs for info about each of them.

package net.sf.j2s.tutorial.debug;

public class HelloJ2SNative {
  /**
   * For java native methods, if Java2Script native codes are given, the
   * native method will be generated when Java2Script compiler is enabled
   *
   * @j2sNative
   * var styleCSS = "position:absolute;left:150px;top:5px;width:100px;height:40px;" 
   *    + "text-align:center;font-weight:bold;color:yellow;background-color:blue;" 
   *    + "border:1px solid red;";
   * var hiEl = document.createElement("<div style=\"" +  styleCSS + "\"></div>");
   * document.body.appendChild(hiEl);
   * hiEl.appendChild (document.createTextNode ("Hi!"));
   */
  native static void sayHi();
  
  /**
   * For java native methods, if you did not define Java2Script native codes,
   * the method will be simply ignored when generating the JavaScript codes.
   */
  native static void sayWell();
  
  /**
   * When j2sNative is defined fro a method, the method body will be overrided
   * with the given native JavaScript codes.
   *
   * @j2sNative alert ("Hello, JavaScript");
   */
  static void sayHello() {
    System.out.println("Hello, Java");
  }
  
  static void sayHei(String name) {
    if(name != null) 
    /**
     * For a normal block, inert j2sNative Javadoc before the brace will
     * replace the inner block body.
     *
     * @j2sNative alert ("Hei, " + name); 
     */
    {
      System.out.println("Hei, " + name + ", how are you?");
    } else
    /**
     * @j2sNative alert ("Hei.");
     */
    {
      System.out.println("Hei, how are you?");
    }
  }
  
  static void saySomething() {
    /**
     * Insert JavaScript only codes with an empty brace block.
     *
     * @j2sNative alert ("En, things will go fine.");
     */ 
    {}
  }
  
  public static void main(String[] args) {
    /*
     * When running from Java, the following line must be commented, as
     * there are not implemented native codes for the native method #sayHi
     */
    sayHi();
    sayHello();
    sayHei("Josson");
    saySomething();
  }
}

And the following is the generated javascript code. We indicate mark with 2 new lines where the native code embbeded with @j2sNative is for each directive call.

Clazz.declarePackage ("net.sf.j2s.tutorial.debug");
c$ = Clazz.decorateAsClass (function () {
Clazz.instantialize (this, arguments);
}, net.sf.j2s.tutorial.debug, "HelloJ2SNative");
c$.sayHi = Clazz.defineMethod (c$, "sayHi", 

function () {
var styleCSS = "position:absolute;left:150px;top:5px;width:100px;height:40px;"
+ "text-align:center;font-weight:bold;color:yellow;background-color:blue;"
+ "border:1px solid red;";
var hiEl = document.createElement("<div style=\"" +  styleCSS + "\"></div>");
document.body.appendChild(hiEl);
hiEl.appendChild (document.createTextNode ("Hi!"));
});
c$.sayHello = Clazz.defineMethod (c$, "sayHello",
 
function () {
alert ("Hello, JavaScript");
});
c$.sayHei = Clazz.defineMethod (c$, "sayHei", 
function (name) {
if (name != null) {

alert ("Hei, " + name);
} else {

alert ("Hei.");
}}, "String");
c$.saySomething = Clazz.defineMethod (c$, "saySomething", 
function () {
{

alert ("En, things will go fine.");
}});
c$.main = Clazz.defineMethod (c$, "main", 
function (args) {
net.sf.j2s.tutorial.debug.HelloJ2SNative.sayHi ();
net.sf.j2s.tutorial.debug.HelloJ2SNative.sayHello ();
net.sf.j2s.tutorial.debug.HelloJ2SNative.sayHei ("Josson");
net.sf.j2s.tutorial.debug.HelloJ2SNative.saySomething ();
}, "Array");

Using real Java annotations instead JavaDoc for @j2s

for each @j2s javadoc tag there is an equivalent java annotation that we can use. In some cases, the java @J2S annotation can be more convinient than the javadoc comment.

you must include net.sf.j2s.ajax project in yout java classpath fgor using them... TODO: better this section

J2s also support using real java annotations (not JavaDoc) instead @j2s annotations inside JavaDoc, For each @j2s JavaDoc annotation there exists a @J2S java annotation class that can be used:

  If you want to refactoring use @J2SRequireImport annotation:
/**
 */
@J2SIgnoreImport(B.class)
public class A {
}
instead of javaDoc
/**
 * @j2sIgnoreImport("a.b.c.B")
 */
public class A {
}

All @j2s* javaDoc has its @J2S* annotations.

Generated JavaScript files

In this section we will examine the generated JavaScript files and also the generated HTML document for a basic understanding of how java code is translated to JavaScript and how that JavaScript can be loaded and executed from an HTML document.

Consider the following simple java class that contains one static method and one instance method:

package my.first.project;
public class HelloWorld {
	public String getName() {
		return this.getClass().getName() + this.hashCode();
	}
	public static void main(String[] args) {
		HelloWorld obj = new HelloWorld();
		System.out.println("object name " + obj.getName());
	}
}

And the generated javascript, with comments, is the following:

Clazz.declarePackage ("my.first.project");                
c$ = Clazz.declareType (my.first.project, "HelloWorld");  
Clazz.defineMethod (c$, "getName", function () {          
  return this.getClass().getName() + this.hashCode();
});
c$.main = Clazz.defineMethod (c$, "main", function (args) {
  var obj =  new my.first.project.HelloWorld ();
  System.out.println ("object name " + obj.getName ());
}, "~A");

As we can see, the Clazz object contains functions that emulate the java language. We will document all this functions in the Section called Java Language Emulation API in Appendix A.

Other thing to notice is that the code translation is linear: for a java statement there is a single javascript statement. Also, it is noticeable that, for the point of view of the translator, there are two main types of Java statements:

• Supported by javascript. Most java statements, like method calling, for, while, if, etc. expressions, are supported directly by the javascript language and do not need almost any translation. In the previous example, the java statement System.out.println ("hello world"); remains the same both in java and in javascript.

• Containing java concepts not supported by javascript. . Doing Object Oriented programming stuf like cľasses, methods definition, etc. Here is when we use the object Clazz: the J2S java language emulator for javascript. So, for example, if we ewant to define a new class in javascript, we use Clazz.declareType.

Now let's finnish examining a more advance java example and its transjaltion to javascript:

package my.first.project;

import java.util.HashMap;
import java.util.Iterator;

public class MyTable extends HashMap<String, Integer>{
	public String print() {
		String s = "";
		Iterator<String> i = keySet().iterator();
		while (i.hasNext()) {
			s += i.next()+",";
		}
		return s;	
	}
}

that is translated to the following commented javascript code:

Clazz.declarePackage ("my.first.project");
Clazz.load (["java.util.HashMap"], "my.first.project.MyTable", null, function () {
  c$ = Clazz.declareType (my.first.project, "MyTable", java.util.HashMap);
  Clazz.defineMethod (c$, "print", function () {          
    var s = "";
    var i = this.keySet ().iterator ();
    while (i.hasNext ()) {
      s += i.next () + ",";
    }
    return s;
  });
});

Doing java in HTML documents

When you run a J2s application in eclipse with menu Run->Run as..->Java2Script Application the Java2Script plugin generates a simple html document that execute the java application. For doing that it is required to perform at least the following tasks:

• load the j2slib.z.js Java2Script runtime script

• configure J2S runtime

• Load main class java class dependencies

• execute some ava code like calling the main() method of main class.

You can use the generated html file in yout web applications, nevertheless, it is very common to launch your Java2Script application from an existing html document, or from a server page (php, jsp asp, whatever). In those cases, it is very helpful to understand how J2s applcations are loaded and executed. So lets examine a minimal html document that calls our HelloWorld java example. For generating the following html markup, the HelloWorkd java class is launched with a clean configuration:

A short version of generated HTML document is the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head><title>my.first.project.HelloWorld</title>
<script type="text/javascript" src="../path/to/j2slib/j2slib.z.js"></script>
</head>
<body>
  <script type="text/javascript">
    ClazzLoader.packageClasspath ("java", "../path/to/j2slib/", true);
    ClazzLoader.setPrimaryFolder ("bin");                 
    ClazzLoader.packageClasspath (["my.first.project", "net.sf.j2s.probes"], "bin/");  
    ClazzLoader.loadClass ("my.first.project.HelloWorld", function () {
      my.first.project.HelloWorld.main([]);               
    });
  </script>
</body>
</html>

As we can see, the ClazzLoader javascript object contains an API do dialogate with the java runtime from javascript. It lets us configure and manipulate the "java virtual machine", for example, telling where main java library code is located, set the "class path", dynamically loading java classes and give as a context from where to call java classes

We will examine and document each of this functions in the Section called Java Runtime Emulation API in Appendix A.

Types

Explain how j2s emulates java types. ej: string and characters are all javascript strings, long, int short, double, float are all javascript numbers. arrays are javascript arrays

Java2Script also wrapps some exceptions that can occurr

Exceptions

Exceptions are well supported by Java2Script and so exception related statements have a very simple translation. There is only one special thing we have take care about when programming Java2Script code and is that in Java2Script, besides Java exceptions, there are also JavaScript native exceptions. For example, as we have seen, using @j2sNative compiler directive we can introduce native javascript code. And native javascript code can throw native javascript exceptions, that may have not be related at all with java exceptions (java.lang.Exception class). For example, the following example will show native javascript code that throws a native DOM exception.

/**
 * native DOM exception siumulation
 * @j2sNative
 * document.body.appendChild(null);
 */{}
   

It is important to understand that these native exceptions, are not java.lang.Exception instances and so, they cannot be catched with catch(Exception e) expression. So, how we catch native exceptions and how can we diferentiate them from common java exceptions? The answer is that native exceptions are instance of class java.lang.Throwable (a superclass of java.lang.Exception) and so, we can catch them using Throwable, as the following example shows:

try {
  /**
   * native DOM exception siumulation
   * @j2sNative
   * document.body.appendChild(null);
   */{}
} catch (Exception e) {
  //catching java exceptions
  System.out.println("this is NOT printed!!!");
}
catch(Throwable e) {
  //catching native exceptions!
  System.out.println("this is printed!!!");
} 
   

The only special case of native exceptions are the null pointer exceptions. Since both in java and javascript null is the same object, and in java we spect NullPointerException to be throwed when accessing the null object, native javascript null pointer exceptions will be objects of the class java.lag.NullPointerException. Let understand this with a litlle example. In the following listing, we emulate a native null pointer exception and show that is catched with a NullPointerException and not as another native exception with Throwable:

   try {
      /**
       * This simulates a native null pointer exception
       * @j2sNative
       * var a = null;
       * a.sdf();
       */{}
    } catch (NullPointerException e) {
      System.out.println("printed!");
    }
    catch (Throwable e) {
      System.out.println("NOT printed!");
    }
   

Native Objects

a native object is TODO

why we have to be careful when dealing with native objects?

TODO

Accessing native JavaScript objects from Java

In section Writing native JavaScript code with @j2sNative we learn how to include our JavaScript code in our Java classes and how our native JavaScript code can call our Java objects. But, wait a moment, in JavaScript we have access to a the document object model, and a lot of JavaScript utilities and toolkits .... TODO

In Java, all objects are inherited from Java.lang.Object. So they must implement methods like hashCode(), equals(), etc. We say that an object is native when it is created from native JavaScript code and doesn't implements java.lang.Object. .... TODO

Native objects mode support

By default, J2S will overwrite javascript Object.prototype adding methods of java.lang.Object like equals, hashCode, notifyAll, etc, so all created objects are valid java objects. Normally this is fine because you don't have to worry about javascript objects that are not valid java objects.

Nevertheless, in some situations, this default behaviour is not desiderable. For example, if you want to integrate your J2S application with a 3rd party javascript toolkit, there can be compatibilities issues because some javascript toolkits simply don't work with a modified Object.prototype. More, since all javascript objects contains java.lang.Object methods, it is impossible to create a clean javascript object, something really common and required for working with 3rd party javascript toolkits.

Fortunately J2S supports a "native object" mode, in which javascript Object.prototype is not contaminated

explain the problems with native objects and explain j2s.native mode

JavaScript functions

TODO: this sections contains the escense but has a bad english. it should be rewritten more elegantly.

The first problem that we face when working with native javascript is that , in javascript, we work with functions and the java language doesn't support such a concept or nothing similar. In java, the only beahaviour language concepts we have are instance methods and static methods. Mixing native javascript functions and java code without realizing what we really are doing, can cause very nasty bugs and problems, and so in this section we will examine possible problems and advices about how to do it right.

function context:

what is a function context? In javascript, any function can be evaluated using any object as its context. The context of a function when evaluated is the object referenced by the "this" keyword.

since in java we always have to use an object, the function in java have a fixed context (the this object). But in javascript this is not true and we must ensure the context. for example, the following example for registering a mouse click listener in document.body will work, but it is incorrect! :

Runnable r = new Runnable(){
  public void run() {
    System.out.println("clicked");
  }
};
/**
 * @j2sNative
 * document.body.onclick=r.run; //WRONG!
 */{}
    

Why this is wrong? When an html document is clicked, and a function is registered for listen to clicks with "element.onclick", the function will be evaluated using the clicked html element as the function context. This means that any reference to "this" in the function body, will point to the target html element and not where it should be, to the Runnable instance. Let examine an example that fails because of this:

With java static methods there is no problem because they do no context (no this pointer). But it is not useful to work with static methods for

ajax

TODO

Simple RPC

http://inside.java2script.com/2007/06/02/tutorial-of-java2script-swt-and-simple-rpc-application.html

Simple pipe / commet

simple pipe : http://inside.java2script.com/2007/08/01/introducing-java2scripts-simple-pipe.html

http://inside.java2script.com/category/comet

Getting Java2Script sources

This section is for those developers who want to install Java2Script sources, run the plugin in Eclipse plugins sdk for testing, see how J2S works, be able to change it, fix it, redistribute it with your own modifications, etc

We will use Eclipse 3.6. You should choose an Eclipse distribution that supports for Eclipse plugin development (almost all).

Source organization

the Java2Script eclipse plugin is cosntituted by several projects working together. Some of these projects contains the eclipse plugin implementation, other contains the java implementation of required java APIs like java.lang, java.util, org.ecipse.swt, etc and other are only auxiliary. In the following table we list the projects that are part of Java2Script and the responsbility of each of them.

Building the sources

There is a couple of things that should be done before building the sources. You only have this two things only once

The first is to decompress the file net.sf.j2s.lib/j2slib.zip. The easy way of doing so is to open net.sf.j2s.lib/build/build.xml in Ant view and run the j2s.unzip ant task

Second, the project net.sf.j2s.ajax requires JAVAX_SERVLET classpath variable to point to a .jar with the Java servlet specification. This is easy to infer looking at Eclipse Problems view.

You can create such a classpath variable pointing to Tomcat 5.0+'s servlet-apis.jar or plugin org.eclipse.tomcat's servlets.jar or other similar jar. Fortunately this is easy, first of all, locate the servlet-api.jar file in your computer. Probably you can find it on your Eclipse plugins directory (in my case it is located at eclipse/plugins/javax.servlet_2.5.0.v200910301333.jar). Also, this .jar file comes in any Java web server, like Tomcat (in the case of Tomcat 5.5 it is at common/lib/servlet-api.jar)

Now that you have located servlet-api.jar file in your computer, go to Eclipse Package Explorer view, right click on the project net.sf.j2s.ajax -> Build Path -> Configure Build Path.... Go to the "Libraries" tab, double click the JAVAX_SERVLET variable, then click on Variable... button and the click on New... button. In the "New Variable Entry" dialog, enter JAVAX_SERVLET as the variable name and the path to servlet-api.jar as the variable value:

After this there should be no errors in the "Problems" Eclipse view and all projects should be rebuilt. The first time, this may take a while. Remember that there are two compilers compiling some large projects like java.lang, java.util package, swt, and other java toolkits both to .class and to javascript.

As said in the previous section, Java2Script plugin contains two different kind of java sources. In one side we have the J2S eclipse plugin itself in projects net.sf.j2s.core and net.sf.j2s.ui and in the other side we have projects like net.sf.j2s.java.core and net.sf.j2s.java.org.eclipse.swt that are actually java libraries to be compiled into javascript and used by our Java2Script applications developed with the Java2Script plugin.

Both kind of projects will be built automatically [4] so we only have to save our files to impact the changes. Nevertheless, if we are modifying files that will be compiled to JavaScript, like the ones in project net.sf.j2s.java.core, we should also rebuild j2slib. It is easy. Just open net.sf.j2s.lib/build/build.xml in Ant view and run the j2s.pack.lib ant task:

Remember, as with any Java project, if you want to force project rebuild, you can always goto menu "Project -> Clean" and clean all projects: also be sure that "Project -> Build Automatically" is checked for automatically building when you change a file.

Running and debugging

Now that our sources are ready and builded, we want to run and debug the plugin. This is very easy, all you need is to open net.sf.j2s.core/plugin.xml and click the link "Launch an Eclipse application" or the link "Launch an Eclipse application in debug mode"

This will start a second Eclipse instance with our Java2Script plugin installed. Try to create a new Java2Script application and test your plugin's mdifications in that instance...

Like with any Eclipse plugin, rememeber that you can add breakpoints in Java code for better debbugging the Java to JavaScript compiler:

Exporting the plugin

So you make your changes and now you want to redistribute the plugin. As with any other Eclipse plugin, you have to export it as an eclipse plugin. It is very easy...

TODO. this is documented at : http://j2s.sourceforge.net/setup-j2s-from-subversion.html. this is what it sais:

Export the above 4 projects as "Deployable plug-ins and fragments". For example, you may select C:\eclipse as the directory of export destination. Project "net.sf.j2s.ajax" and "net.sf.j2s.lib" must be exported with "Package plug-ins as individual Jar archives" UNCHECKED. And project "net.sf.j2s.ajax" should be exported with "Include source code" option CHECKED, so later you can bind sources much easily.

How to Extend the Java2Script compiler

Now that you know how to install and run Java2Script from the sources, and know how to export your own version of Java2Script, we will describe a mechanism supported by Java2Script eclipse plugin that will let us extend the compiler easily, without modifying the compiler sources and without having to learn all compiler related classes internals for doing it.

In this section you will learn how to customize how to customize the output of j2s compiler. You will be able to make an eclipse plugin that contribute to Java2Script Compiler with custom code for performing the translation of desired java language elements, like methods, classes, fields, expressions, statements, comments, etc to javascript. The main benefit of using an independent eclipse plugin is that you can isolate your customization code from java2script compiler nd so the same java2script distribution can be used for different java to javascript compiling scenarios.

Basically, this eclipse plugin must indicate what it want to customize, and provide the actual code translation for that parts. For example,

• analize each method invocation and add some javascript code before or after the invocation.

• analize each javadoc comment and search for a certain string or javadoc annotation inside it and add some javascript code before or after the java element documented with that javadoc

• add javascript code before or after a class declaration for classes that apply some conditions

• customize how java classes must be loaded in certain circunstances

For developing the eclipse plugin we will use the eclipse plugin environment (PDE) that comes with common eclipse distributions. It is recommended but not mandatory to be familiarized with PDE, so you may want to read Plug-in Development Environment Guide .

We will also will need to model java elements like classes, methods, attributes, expressions, statements. For this, we will use eclipse Java Develpment Tools (JDT) and so, for taking full advantadge of this, it is recommended to know the basics about JDT. So, you may want to read JDT programmers guide

package j2s.extension1;

import net.sf.j2s.core.astvisitors.ASTScriptVisitor;
import net.sf.j2s.core.astvisitors.DependencyASTVisitor;
import net.sf.j2s.core.astvisitors.SWTDependencyASTVisitor;
import net.sf.j2s.core.compiler.IExtendedVisitor;

public class MethodInvocationComment1 implements IExtendedVisitor {

  public MethodInvocationComment1() {
  }

  public ASTScriptVisitor getScriptVisitor() {            
    return new MethodInvocationComment1ScriptVisitor();
  }

  public DependencyASTVisitor getDependencyVisitor() {    
    return new DependencyASTVisitor();
  }
}

package j2s.extension1;

import org.eclipse.jdt.core.dom.MethodInvocation;

import net.sf.j2s.core.astvisitors.SWTScriptVisitor;

public class MethodInvocationComment1ScriptVisitor extends SWTScriptVisitor {
  @Override
  public boolean visit(MethodInvocation node) {           
    buffer.append("/* A COMMENT ADDED WITH our J2S compiler extension plugin */\n");
    return super.visit(node);                             
  }
}

package j2s.extension1;

import org.eclipse.jdt.core.dom.MethodInvocation;

import net.sf.j2s.core.astvisitors.ASTScriptVisitor;

public class MethodInvocationComment1ScriptVisitor extends ASTScriptVisitor {
  @Override
  public boolean visit(MethodInvocation node) {
    buffer.append("/* A COMMENT ADDED WITH our J2S compiler extension plugin */\n");
    return super.visit(node);
  }
}

Clazz.declarePackage ("org.foo");
c$ = Clazz.declareType (org.foo, "Test1");
c$.main = Clazz.defineMethod (c$, "main", 
function (args) {
/* A COMMENT ADDED WITH our J2S compiler extension plugin */
java.lang.System.out.println ("hee");
}, "~A");

package j2s.extension1;

import java.util.Iterator;
import java.util.List;

import net.sf.j2s.core.astvisitors.SWTScriptVisitor;

import org.eclipse.jdt.core.dom.FieldDeclaration;
import org.eclipse.jdt.core.dom.Javadoc;
import org.eclipse.jdt.core.dom.TagElement;
import org.eclipse.jdt.core.dom.VariableDeclarationFragment;

public class MethodInvocationComment1ScriptVisitor extends SWTScriptVisitor {

  @Override
  public boolean visit(FieldDeclaration node) {       
    boolean ret = super.visit(node); /* first visit the default visitor implementation */
    
    Javadoc javadoc = node.getJavadoc();
    List tags = javadoc.tags();   
    if(tags!=null&&tags.size()>0) {
      for (Iterator it = tags.iterator(); it.hasNext();) {
        Object o = (Object) it.next();
        if(o instanceof TagElement) {
          TagElement tag = (TagElement) o;
          String tagName = tag.getTagName();
          if(tagName!=null&&tagName.equals("@j2sLoadString")) { /* annotation found. all the 
            following javadoc comment until other tag is found will be loaded */
            StringBuffer sb = new StringBuffer();
            List frags = tag.fragments();
            for (Iterator it2 = frags.iterator(); it2.hasNext();) {
              sb.append(it2.next()+"\\n");
            }
            List fieldDeclFrags = node.fragments();
            /* now that we have the @j2sLoadString string, we add the javascript statement this.attributeName="str.." for loading the string field.*/
            if(fieldDeclFrags!=null&&fieldDeclFrags.size()>0) {
              VariableDeclarationFragment f1 = (VariableDeclarationFragment) fieldDeclFrags.get(0);
              String str = sb.toString();             
              buffer.append("this."+f1.getName()+"=\'");
              buffer.append(str);
              buffer.append("\';\n");
            }
          }
        }
      }
    }
    return ret;
  }
}

  package org.foo;

public class Test1 {    
       
  public static void main(String[] args) {
    Test1 test1 = new Test1();
    System.out.println("loaded html code: "+test1.getHtmlCode1());
    System.out.println("loaded json code: "+test1.getJsonCode1());
    System.out.println("lot easier isn't it?");
  }  
  /** this field will be loaded with the fololowing string:
   * @j2sLoadString 
   * <h1>this is an <b>html</b> string loaded from javadoc</h1>
   */
  String htmlCode1;
  
  /**
   * this other too
   * @j2s LoadString
   * {p1: [1, 2, 3], p2: {p21: "thi sis a json loaded from javadoc"}}
   */
  String jsonCode1;

  public String getHtmlCode1() {
    return htmlCode1;
  }

  public String getJsonCode1() {
    return jsonCode1;
  }    
}  
  

loaded html code:
<h1>this is an <b>html</b> string loaded from javadoc</h1>
 
loaded json code: {p1: [1, 2, 3], p2: {p21: "thi sis a json loaded from javadoc"}}
 
lot easier isn't it?