native_code_javascript.txt

Native code for javascript
--------------------------

The interfacing of the converted javascript code to the actual runtime 
environment (a browser or node.js system) needs the implementation of 
native classes.

Nearly everything that is necessary to understand how to implement 
native classes can be learned from looking at the provided core classes
(in the subfolder runtimejs/ in converter.jar). 
Nevertheless there is a short explanation of the most important concepts.

Linker directives:

    //load// java/lang/Object

    This is a directive to the javascript linker that this file depends on
    another file that has to be loaded before this one. That is normally
    used for the base class or when implementing interfaces.

    //reference// java/util/Enumeration

    This directive tells the linker that the file needs to be loaded eventually
    before the actual startup of the program, but probably at a later time
    than the current file.

    //complete// java/io/PrintStream
    
    This is the most strict requirement directive and tells the linker that
    the file and all its reference-dependencies (fully recursively) need to 
    be loaded before this one. This is important if a class has some static
    initialization to do that is actually done at loading time but may depend
    on other classes to be completely loaded already.


Class definitions are done by creating a single allocator function that
populates all members and sets them to their java default value (0 or null).
Proper java-style construction will then be done with one of the special 
instance methods named _0, _1, ...

var c = function() {
    this.member1 = 0;
    this.member2 = null;
};

After that, you need to set up the prototyping chain and some additional internal
stuff with this call:

_defclass(class, baseclass, interfaces, instance_methods);

An example:
_defclass(com_greentube_MyClass, java_lang_Object, [],  
{   _0: function() { this.member1= 47; this.member2=11; return this; }
    print_0: function() { console.log(this.member1,this.member2); }
});


All static methods and fields need to be defined just as global variables with
a proper fully qualified name:

com_greentube_MyClass_static1_1 = function(x) {};
com_greentube_MyClass_static2_1 =  function(y) {};
com_greentube_MyClass_staticfield = 4711;

For pure static classes for which it is not necessary to create any instance objects,
you can leave out the allocator function and the _class() call. Just specify the
global methods and variables  (like it is done for java.lang.Math or java.lang.System).

There is no specific implementation class for java.lang.String, because 
the existing javascript-strings are directly used, but enhanced with many 
java-style methods. 


Interface definitions are like so:

var i = { 
    _superinterfaces: [ ... ], 
    _defaults: { ... },
}; 

var i_staticmember = 99;
var i_staticmethod_0 = function() { return "something"; };

Interfaces are very light-weight in javascript. They mainly consist of an object that
references its super-interfaces for the type-inclusion checks.
Optionally you can provide a set of default method implementations. These will be attached
to all classes implementing this interface (inside the _class() call).
Static members are just implemented as global javascript variables;


Identifier escaping

To avoid any potential name clashes with converted java code, the following rules are
applied to java identifiers:
    A-Z,a-z,0-9 are used directly
    anything else - even underscores - are escaped in hexadecimal unicode with $xxxx
    
    A direct consequence of this method is that there can never be any underscores
    in converted identifiers (beside what is inserted by the converter itself).
    So if you want to have private fields or methods
    in native code that will not clash with any java identifier, 
    you can simply prefix it with a single _
   

Method overloading

All methods have a suffix that denote the number of parameters 
  (  java_lang_Integer_valueOf_1(i)  for example). 
This allows a basic form of overloading, and is still compatible with the identifier 
escaping (the _1 is not considered part of the identifier and will not be escaped).