Jump to: navigation, search

VJET/JSRReference

Contents

Purpose

The purpose is the document how the VJET JS or Java to JS is transformed into a Java API using a reference based programming model.

What is a JSR

A JSR (JavaScript Reference) is a Java type that serves as a reference to the following types:

  • VJET JavaScript Authored in multiple languages
    • JavaScript language
    • Java language
  • Native Types
    • JavaScript Native Types
    • DOM types

Java APIs to Access JavaScript

JSR provides access to JavaScript and provides Java APIs for public

  • Functions
  • Methods
  • Properties
  • Function References
  • Type References

Java code can access JavaScript references using Java. JavaScript developers can develop a definition neutral JavaScript Reference API. Developers can choose to use JavaScript authored in JavaScript language or in the Java language. JSRs are part of a larger technology set, V4, which supports the development of web pages and applications using Java.


Resource Access

JSRs provide a resource reference for any JavaScript resource backing the type. This is used for ensuring that when executing the JavaScript that all the definitions have loaded in the runtime. Resource Specs can be added to view specs. Please see the V4 resource pattern documentation for more information.


APIs Public Access Required

Methods, nested classes, and properties that are public will have generated JSR apis. All others will not be generated in JSR.


JSR Creation Options

VJET JS to JSR

VJET JS to Jsr is the entry point for JavaScript developers to work with Java developers. The JSR generated from the VJET JS source file is not meant to be edited by hand. The name of a JSR is composed of the name of the type it represents, appended with ‘Jsr’. For example, VJET JavaScript type named MyClass (.js) will generate a JSR named MyClassJsr.java. Generated java files should always be generated and never checked into source control. To handle this case the generated JSR contains a Java 5 annotation: @org.eclipse.vjet.resource.utils.CodeGen("JsrGenerator")


There are 3 ways this can be done:

  1. Eclipse plugin – right click V4-> Js reference generation -
  2. Java main program - org.eclipse.vjet.jstojava.codegen.JsToJavaGen
  3. ANT task - org.eclipse.vjet.jstojava.prebuild.JsLibPreBuildTask

//Note for eBay this task has been integrated into the Build3 and Build2 systems.


VJET Java to JSR

JSRs can also be generated from Java files. This provides the capability for JavaScript code to be authored in Java or JavaScript code without having consumer change their code if the signature doesn't change. The JSR generated from the Java source file is not meant to be edited by hand. The name of a JSR is composed of the name of the Java type it represents, appended with ‘Jsr’. For example, Java type named MyClass.java will generate a JSR named MyClassJsr.java. Generated java files should always be generated and never checked into source control. To handle this case the generated JSR contains a Java 5 annotation: @org.eclipse.vjet.resource.utils.CodeGen("JsrGenerator")


There are 3 ways this can be done:

  1. Eclipse plug-in – right click V4-> Java 2 Js Generation
  2. Java main program - org.eclipse.vjet.javatojs.cli.Java2Vjo
  3. ANT task - org.eclipse.vjet.javatojs.prebuild.J2JsBuildTask

Hand coded Jsr

JSRs can also be generated by hand. For example if the original api authored by the JavaScript developer doesn't handle a specific case such as using a JavaScript type or DOM type but there is a more appropriate Java type that should be used a custom Jsr can be created.

When to not use Jsr

JSRs should not be used when writing JavaScript definitions using Java. Native java proxies should be used when trying to access native JavaScript code from a Java 2 Js definition.


VJET Types map to Jsr generated types

A JSR definition preserves all aspects of the original type definition, including inheritance, interface implementations, and dependencies. For example, if a JavaScript definition inherits from another type, the JSR will extend from the super class; if a JavaScript definition implements an interface, the JSR will specify the implemented interface. Please refer to the Appendix Xxx for more information.


Below is the list of fundamental VJO types that are supported.


Java Related types

  1. CType - a java class extending JsObj is generated
  2. IType – a java interface is generated
  3. EType – a java class extending JsEnum is generated
  4. Static Inner Type – a nested java class will be created for each public nested class.
  5. Instance Inner Type
  6. Anonymous Type

Js Types with no equivalent Java type

  1. MType – a java class is generated since java doesn't support mixin natively. This type answers to let you know it isMixin and provides access to resource backing mixin.
  2. OType – a java class with nested java classes is generated.

Js Functions

The following diagram shows the relationships for the Java Script Reference model for JavaScript Functions,

Vjet jsrreference jsfunction.png

Functions with No Arguments

If a method takes no arguments, a single function reference is generated. The reference preserves all modifier information from the original definition, in this case, a void return type, and public access.


JS code JSR Java API
 
//> public void warn();
warn:function(){}
public JsFunc<Void> warn() {}
Java authored Js code
public void warn(){}

Functions with arguments

If a method takes one or more arguments, two function references are generated:

  • A reference that accepts the given argument type
JS code JSR Java API
//> public String foo(String s);
foo:function(s){}
public JsFunc<String> foo(String s)


Java authored Js code
public void warn(String s){}
  • A reference that accepts a value binding


JS code JSR Java API
//> public String foo(String s);
foo:function(s){} // assume this code is in props section / static
public static JsFunc<String> foo(IValueBinding<String> s)
Java authored Js code
public String foo(String s)
  • Passing a value binding allows delegation and deferring the materialization of a value to another object. In this case another Jsr property or function that returns JsFunc<String> can be passed into the warn method. For example since foo method returns JsFunc<String> it can be passed into itself.


Java JSR Usage Code Generated Js Method call code (un-optimized)
MyJsr.foo(MyJsr.foo("test"));
a.b.c.MyJsr.foo(a.b.c.MyJsr.foo("test")); 
// note that there are optimization techniques we use to shorten this.



Functions with Optional Arguments in methods (Js authored only)

Optional arguments will produce overloaded apis in JSR.

One required argument and one optional argument:

JS code JSR Java API
//>public void foo(Foo a, String? b) 
foo : function(a, b){}
public JsFunc<Void> foo(FooJsr a, String b)
 
public JsFunc<Void> foo(</nowiki>IValueBinding<nowiki><? extends 
FooJsr> a, IValueBinding<nowiki><String> b)
 
public JsFunc<Void> foo(FooJsr a)
 
public JsFunc<Void> foo(</nowiki>IValueBinding<? extends FooJsr> a)

Multiple Optional Arguments:

JS code JSR Java API
//>public void foo(Foo a, String? b, String? c) 
foo2 : function(a, b){}
public JsFunc<Void> foo2(FooJsr a, String b, String c)
 
public JsFunc<Void> foo2(IValueBinding<? extends
 FooJsr> a, IValueBinding<String> b, IValueBinding<String> c)
 
public JsFunc<Void> foo2(FooJsr a, String b)
 
public JsFunc<Void> foo2(IValueBinding<? extends 
FooJsr> a, IValueBinding<String> b)
 
public JsFunc<Void> foo2(FooJsr a)
 
public JsFunc<Void> foo2(IValueBinding<? extends FooJsr> a)

Incorrect Optional arguments

Optional arguments are only supported as the last arguments in the argument list. If the optional argument occurs before a required argument the jsr generation will assume that the optional argument is required.


JS code JSR Java API
//>public void foo(Foo? a, String b) 
foo : function(a, b){}
public JsFunc<Void> foo(FooJsr a, String b)
 
public JsFunc<Void> foo(IValueBinding<? extends FooJsr> a, IValueBinding<String> b)


Supporting Variable arguments

Variable Argument only

JS code JSR Java API
//>public void foo3(Foo ... s)
foo3 : function(s){}
public JsFunc<Void> foo3(FooJsr... p0)
 
public JsFunc<Void> foo3(IValueBinding<? extends FooJsr>... p0)
Java authored Js code
public String foo3(Foo … s)

Required argument and Variable argument

JS code JSR Java API
//>public void foo5(String z, Foo ... b) 
foo5 : function(z, b){
 
}
public JsFunc<Void> foo5(String z, FooJsr... b)
 
public JsFunc<Void> foo5(IValueBinding<String> z, IValueBinding<? 
extends FooJsr>... b)
Java authored Js code
public String foo3(Foo … s)

Variable Argument listed before required argument – not supported

VJET validation error will be produced and if error is ignored no method will be generated. In Java authored code java compiler will give you an error.


JS code JSR Java API
//>public void foo4(Foo ... s, String b) 
foo3 : function(s, b){}
// nothing produced

Overloaded Methods

JavaScript developers can declare overloaded methods but JavaScript can only have one function per name so the Js developer must handle the overloading in the function internally. The Java developer can author 2 independent methods rather than rely on one method. The Jsr Generation supports up to 15 overloaded signatures.

Simple overloading scenario

JS code JSR Java API
//>public void foo4(String) 
//>public void foo4(int) 
foo4 : function(){}
public JsFunc<Void> foo4(String a)
 
public JsFunc<Void> foo4(IValueBinding<String> a)
 
public JsFunc<Void> foo4(int a)
 
public JsFunc<Void> foo4(IValueBinding<Integer> a, org.eclipse.vjet.aggregator.jsref.d.D1... notUsed)
Java authored Js code
public void foo4(String a){}
 
public void foo4(int a){}

Note: the D1 class is for working around a problem with overloading and generics in Java. We use the D1 vararg to fake out the compiler. Since the generic is an erasure the compile get's confused between IValueBinding<Integer> vs IValueBinding<String>.

Hand coding a function reference

In the base JsObj there is an overloaded method called call where you can pass in the return type, method name, and arguments. If you look at the generated code you will see this simple internal call.


Original Js code JSR Hand coded Function reference
//> public String foo(String s);
foo:function(s){}
public JsFunc<String> foo(String s){
 
return call(String.class, "foo").with(s);
 
}
 //> public String foo2();
foo2:function(){}
public JsFunc<String> foo2(){
    return call(String.class,"foo2");
}

If a JavaScript developer doesn't correctly declare a method you can add a call method directly. This is not recommended practice it is similar to using reflection to call a method. It is possible to get a runtime error because there is no contract that the method will exist.

Js Property References

Vjet jsrreference jsproperty reference.png

Js property reference getting value (JsProp)

You can get a reference to the value. On the server side you will not have access to the value 10. You will have access to the property reference which could be passed into another IValueBinding based API. If you need access to the value you must be writing your JavaScript definitions in Java or JavaScript.


JS code JSR Java API
MyProp:10, //< public int; assume protos


public JsProp<Integer> MyProp();
Java authored Js code
public int MyProp = 10;

Js property reference setting value (JsPropSetter)

If the property is public and not final a property setter api is available which allows you to change the property reference value. There are 2 apis created for this property one for the main type and one for the IValueBinding similar to the function with one argument. Properties do not allow for different types; JSRs only provide one argument methods.


JS code JSR Java API
MyProp:10, //< public int; assume protos
public IJsPropSetter MyProp(int v) {
    return setProp("MyProp", v);
}
 
public IJsPropSetter MyProp(IValueBinding<Integer> v) {
    return setProp("MyProp", v);
}
Java authored Js code
public int MyProp = 10;

JavaScript Object References

Vjet jsrreference javascript object reference.png


Constructors

Default Constructor

Constructors are generated for concrete types:

  • Ctypes / classes,
  • Etypes / enum,
  • Otypes (authored in Js only)

Constructors are not created for

  • Itypes / Interfaces
  • Mixins (authored in Js only)

By default, JSRs include a no-argument default constructor, unless the constructor is overloaded:


JS code Java API
// no constructs method
public SimpleJsr()
Java authored Js code
// no java constructor

Overloaded Constructor

Js to Jsr

JS code Java API
 //>public constructs(String)
constructs : function(a){}
public FooJsr(String a)
 
public FooJsr(IValueBinding<String> a)

Java to Jsr

Java authored Js code Java API
public FooJ2J(String a){}
public FooJsr(String a)
 
public FooJsr(IValueBinding<String> a)</nowiki>

Default protected constructor

There is a default protected constructor created that takes the JsObjectMeta, determines if an instance should be created, and passes the value of the arguments.


Registration of the Object Instance

TODO

Resource Pattern Integration

Any non native type that has a source backing file will have a resource spec added during code generation. Any reference to this Jsr will automatically add its resources into the JsRuntimeCtx.

Js Native Types

Vjo Types

When there is a resource that is required to support the definition of the JavaScript type the Jsr must implement an ISpecBasedComponent. Js Objects implement an ISpecBasedComponent to allow the active needs to be translated to a resource spec which supports resource aggregation.


ResourceSpec that is generated for user defined types should include the following:

  1. VjoBootstrap for Vjo Types,
  2. The type itself and
  3. all active needs and
  4. honorary needs. Honorary needs are from sections such as extends, satisfies, and mixin.

Resource Specs should not include inactive needs in resource spec or implied types such as JavaScript Date or DOM types.


Types to JSR

Class or CType to JSR

JS code Java API
vjo.ctype('vjo.example.MyCType') //< public
.endType();
public class MyCTypeJsr extends JsObj {
Java authored Js code
package vjo.example;
 
public class MyCType {
 
}

Interface or IType to JSR

In this case the interface doesn't extend JsObj the interface is used to load the resources and provide access to the type reference.


JS code Java API
vjo.itype('vjo.example.MyIType') //< public
.protos({
 
})
.endType();
public interface MyITypeJsr {
Java authored Js code
package vjo.example;
public interface MyIType {
 
}

MType to JSR

We create a JSR for resource pattern only. The APIs are not added to this class. The methods and properties declared in the mixin are added directly into the Jsr class since at the time of Java 5 and 6. Java does not support native mixin or module support.


JS code Java API
vjo.mtype('vjo.MyMType') //< public
.endType();
public abstract class MyMTypeJsr {
 
…
}


Java authored Js code
// not applicable no mixin concept in Java.

Java enum or EType to JSR

ETypes in JSR do not use the Java Enum construct instead they use a Java Class so that the members can be referenced. We support a simple enum to a more complex enum. In all cases the name references are static final. While the enum names are referenced statically in a Jsr there is actually an instance created during Js runtime for each name. We borrow the small talk static instance concept here.

JS code Java API
vjo.etype('vjo.MyEType') //< public
.values(
"A,B"
)
.endType();
public final class MyETypeJsr extends JsEnum {
…
 
public static final JsProp<MyETypeJsr> A = 
              new JsProp<MyETypeJsr>(<S.getStaticAnchor(), "A");
 
public static final JsProp<MyETypeJsr> B = 
              new JsProp<MyETypeJsr>(S.getStaticAnchor(), "B");
…
 
}
Java authored Js code
package vjo;
 
public enum MyEType {
A,B
}

OType (JS only)

Object literal types provide JSR apis for functions and object literals without requiring class hierarchy. These APIs are used to ensure function signature safety and property safety rather than type safety since the function and object can live on their own in a JavaScript runtime.

Object Literal in Defs

JS code Java API
vjo.otype('example.A')
.defs({
foo:{
a:10, //<int
b:null//<Date
},
 
foo2:{
a:10, //<int?
b:null//<Date?
}
 
})
.endType();
public abstract class AJsr {
 
…
 
    public static class fooJsr extends JsObjectLiteral { 
 
        public static fooJsr obj(int a, Date b)
        public static fooJsr obj(IValueBinding<Integer> a, IValueBinding<? extends Date> b)
        public IValueBinding<Integer> getA() 
        public IValueBinding<? extends Date> getB()
    }
 
…
}

Object Literal with optional properties

Optional properties create a similar pattern to the optional arguments in a method. In this case there are 5 methods created one for zero values, and then the arguments go in order of entry in the object literal with int a first, then b Date. The Jsr generator bases the order on order of entry and doesn't create additional overloaded methods for reverse order.


JS code Java API
vjo.otype('vjo.MyOType') //< public
.defs({
foo:{
a:10, //<int?
b:null//<Date?
}
 
})
.endType();
public abstract class MyOTypeJsr {
…
 
    public static class fooJsr extends JsObjectLiteral { 
 
        public static fooJsr obj(int a, Date b) 
 
        public static fooJsr obj(IValueBinding<Integer> a, IValueBinding<? extends Date> b) 
 
        public static fooJsr obj()
 
        public static fooJsr obj(int a)
 
        public static fooJsr obj(IValueBinding<Integer> a)
 
        public IValueBinding<Integer> getA()
 
        public IValueBinding<? extends Date> getB() 
 
        …
 
    }

Defining a Function Definition

JS code Java API
vjo.otype('vjo.MyOType') //< public
.defs({
//>public MyOType.foo doIt() 
doIt : function(){
 
}
 
})
.endType();
public abstract class MyOTypeJsr {
    …
 
    public static class doItJsr extends JsFuncRef<MyOTypeJsr.fooJsr> { 
 
        …
 
        // advanced API
 
        public doItJsr(JsObjData obj, String funcName)
 
        public doItJsr(JsObj obj, String funcName)
 
 
    }
    …
 
}

Using Function Defs in CType (Simple)

CType definition:

vjo.ctype('org.eclipse.vjet.jsr.runtime.tests.otype.B') //< public
//>needs(org.eclipse.vjet.jsr.runtime.tests.otype.A)
.props({
    //>public void foo(A.foo) 
    foo : function(a){
 
    },
 
    //>public void foo(A.foo2) 
    foo2 : function(a){
 
    }
})
.endType();

Passing a typed object literal to a static function:

BJsr.foo(AJsr.fooJsr.obj(1, new Date()))

Resulting JS code:

org.eclipse.vjet.jsr.runtime.tests.otype.B.foo({a:1,b:new Date(1274728865945)});

Passing a typed object literal with optional arguments to a static function:

BJsr.foo2(AJsr.foo2Jsr.obj(1)
BJsr.foo2(AJsr.foo2Jsr.obj(1, new Date()))

Resulting JS code:

org.eclipse.vjet.jsr.runtime.tests.otype.B.foo2({a:1});
org.eclipse.vjet.jsr.runtime.tests.otype.B.foo2({a:1,b:new Date(1274728866195)});

Using Function Defs (Advanced)

If you want to pass a function reference into another function reference you can use the utility methods that are added. This is advanced because you must watch your execution scope for passing any methods on an instance. Jsrs do not automatically hitch the methods to the instance object. Also there is no type safety with this advanced mode so if the API changes or the method is removed you will not find out until runtime. This api is primarily for library developers or library developers who are adapting existing JavaScript object literals from the internet.

Step 1 defines the JS code:

OType: X – defines the function reference X.foo

vjo.otype('org.eclipse.vjet.jsr.runtime.tests.otype.X') //< public
.defs({
    //>public void foo(String x)
    foo:vjo.NEEDS_IMPL
})
.endType();

CType 1 : Y – defines a method that passes the function reference defined in X

vjo.ctype('org.eclipse.vjet.jsr.runtime.tests.otype.Y') //< public
//> needs(org.eclipse.vjet.jsr.runtime.tests.otype.X)
.protos({
    //>public void doIt(X.foo) 
    doIt : function(f){
        assertTrue(f != null);
        f("test");
    }
})
.endType();

CType 2 : Z – defines 2 methods that implement the api X.foo

vjo.ctype('org.eclipse.vjet.jsr.runtime.tests.otype.Z') //< public
//> needs(org.eclipse.vjet.jsr.runtime.tests.otype.X)
.props({
    //> X.foo
    method:function(x){
        //vjo.sysout.println(x);
        assertTrue(x == "test");
    }
})
.protos({
    //> X.foo
    bar : function(x){
        //vjo.sysout.println(x);
        assertTrue(x == "test");
    }
})
.endType();

Step 2 Generate the Jsr


Step 3 Using the Jsr


Pass an instance function into a static method:

XJsr.fooJsr foo = new XJsr.fooJsr(new ZJsr(), "bar");
new YJsr().doIt(foo);

Resulting Js

var _r = vjo.Registry;
r.put('0',new org.eclipse.vjet.jsr.runtime.tests.otype.Z());
vjo.Registry._1.doIt(vjo.Registry._0.bar);

Pass a static function into a static method

XJsr.fooJsr foo2 = new XJsr.fooJsr(new JsObjData("org.eclipse.vjet.jsr.runtime.tests.otype.Z", ZJsr.class, "Z"), "method");
new YJsr().doIt(foo2)

Resulting JS code:

var _r = vjo.Registry;
function $o2(){return new org.eclipse.vjet.jsr.runtime.tests.otype.Y();};
_r.put('2',$o2());
vjo.Registry._2.doIt(org.eclipse.vjet.jsr.runtime.tests.otype.Z.method);

Nested Types

Static Inner Type

JS code Java API
vjo.ctype('vjo.NestedTypeEx') //< public
.props({
    Foo:vjo.ctype()
    .endType()
})
.endType();
 public class NestedTypeExJsr extends JsObj {public NestedTypeExJsr()public static class FooJsr extends JsObj {
        public FooJsr()
        public static JsTypeRef<FooJsr> prototype = 
                                new JsTypeRef<FooJsr>(S);
    }
    public static JsTypeRef<NestedTypeExJsr> prototype = 
                                new JsTypeRef<NestedTypeExJsr>(S);
 
}
Java authored Js code
public class NestedTypeEx {
    public static class Foo{}
}

Function References and Type References

The following diagram shows the relationships for the Java Script Reference model for JavaScript Function references, JavaScript type references (added by VJO JS), and JavaScript properties.


Vjet jsrreference function reference.png


Function References (JsFuncRef)

There are 2 ways to have a reference to a function one way is to use the JavaScript Function type in your API but this doesn't specify return type or arguments that are accepted.

Function Ref using Function API

In the Java authored JS code you will notice the type is JFunction not Function.


JS code JSR Java API
vjo.otype()
.defs({
    //> public int doIt(String x)
    doIt : function(x){}
}
public static class doItJsr extends JsFuncRef<Integer> { 
 
public doItJsr(JsObjData obj, String funcName)
 
public doItJsr(JsObj obj, String funcName)
 
}
Java authored Js code
// not supported

TODO – I tried declaring a function reference but this is an otype only construct. We can pass Function objects in Java but this is not function reference.

Using the JsFuncRef in a Class

JS code JSR Java API
//> public OType.doIt foo(OType.doIt f);
foo:function(f){}
public JsFunc<? extends MyOTypeJsr.doItJsr> foo(){}
Java authored Js code
public MyOType.doIt foo() 
// This is using the native proxy 
//MyOType not the MyOTypeJsr

Type References (JsTypeRef)

API for Type References

JS code JSR Java API
//> public Type::X foo(Type::X f);

foo:function(f){}

public JsFunc<? extends JsTypeRef<FooJsr>> foo5(JsTypeRef<FooJsr> f){}
 
 
public JsFunc<? extends JsTypeRef<FooJsr>> 
    foo5(IValueBinding<? extends JsTypeRef<FooJsr>> f){}
Java authored Js code
 // currently not supported

TODO – fix the Java to Jsr for type references.

Access a Type Reference for any Type

A type reference property is added for all types except for:

  1. OType
  2. Mixin

For nested types we support type references for

  1. Static nested types.
  2. Nested type inside an interface.
public static JsTypeRef<NestedTypeExJsr> prototype = new JsTypeRef<NestedTypeExJsr>(S);

Imports and Jsr

  • Imports are translated into a nested class resource spec that can be used in a view spec.
  • Inactive needs will not include the resource in the Jsr.
  • Implicit types such as Date or HTMLSelectElement do not get included in the Jsr resource spec.

TODO example of needs/extends to resource spec inside outer type


Java to JS Converters

For any Java types used in Jsr APIs there is a converter registered. That will convert the Java object to a js object during runtime. There are default converters for the following Java types and literals:


BooleanJsConverter

This converter converts Boolean literal from Java Boolean literal to Js Boolean literal


BooleanWrapperConverter

This converter takes a java.lang.Boolean object and converts it to a JS Boolean object. In most cases this should not be used since developers mostly expect a Boolean literal not a


DateJsConverter

StringArrayJsConverter

StringJsConverter

EnumJsConverter

DsfMessageJsConverter

DefaultJava2JsConverter

JsContentGenJsConverter

JsObjRefConverter

JsVariableBindingConverter

JsonObjectConverter

VjoObjectConverter

Js to Jsr Mappings

In most cases JavaScript types will map XJsr types. In some cases for types that are similar to JavaScript native types and literals we use the Java data type rather than a Jsr. This is to provide Java developer a simple way to pass primitive information such as String literal or boolean literals without creating a Jsr.

Js Native Type mapping

JavaScript Type used in JavaScript Language Java API Notes
Arguments Not supported This type should not be used in API. Type is only available in function scope.
Array ArrayJsr.java should not be abstract
Boolean java.lang.Boolean Converter is registered. Converts to js Boolean. Note you should not use this in your Js code instead use boolean (lower case b) and you will receive the literal.
Date java.util.Date Converter is registered. Converts to a Js date.
Enumerator EnumeratorJsr.java Maps to Jsr
Error ErrorJsr.java Maps to Jsr
EvalError EvalErrorJsr.java Maps to Jsr
Function FunctionJsr.java Maps to Jsr
Global GlobalJsr.java Should not be used since this is implied type for global scope.
Math MathJsr.java Maps to Jsr
Number double Converter is registered.
Object java.lang.Object Maps to vjo.ObjectJsr
ObjLiteral java.lang.Object Should not be used in API. Use Object. We have mapping to Object for backwards compatibility
RangeError RangeErrorJsr.java Maps to Jsr
ReferenceError ReferenceErrorJsr.java Maps to Jsr
RegExp RegExpJsr.java Maps to Jsr
String java.lang.String Converter takes java string and converts to Js string literal
SyntaxError SyntaxErrorJsr.java Maps to Jsr
TypeError TypeErrorJsr.java Maps to Jsr
URIError URIErrorJsr.java Maps to Jsr

Js / Java Literals to Jsr mappings

Java Literal used in JavaScript language Java API Notes
float float Not supported literal in Js but we add this literal to help declare precision. At Js runtime precision may be higher then Float.MAX_VALUE.
double double Not supported literal in Js but we add this literal to help declare precision. At Js runtime precision may be higher then Double.MAX_VALUE.
byte byte Not supported literal in Js but we add this literal to help declare precision. At Js runtime precision may be higher then Byte.MAX_VALUE.
void void
char char should extend String
boolean boolean boolean represents a boolean literal and should never be Boolean object.
long long
short short

VJO Type mappings in Jsr

Vjo type Java API Notes
vjo.Object vjo.ObjectJsr JsObj is currently base for all native objects and vjo objects but really user defined objects using VJO should extend from vjo.ObjectJsr not JsObj.
vjo.Enum vjo.EnumJsr
vjo.Class vjo.ClassJsr Converter is registered

DOM Type mappings in Jsr

DOM types are used for the type name only.


Browser Data Types
DOM JS Built-in Type Corresponding Jsr
ActiveXObject ActiveXObjectJsr.java
Attr AttrJsr.java
CDATASection CDATASectionJsr.java
CharacterData CharacterDataJsr.java
Comment CommentJsr.java
DocumentEvent DocumentEventJsr.java
DocumentFragment DocumentFragmentJsr.java
Document DocumentJsr.java
DocumentType DocumentTypeJsr.java
DOMConfiguration DOMConfigurationJsr.java
DOMErrorHandler DOMErrorHandlerJsr.java
DOMError DOMErrorJsr.java
DOMException DOMExceptionJsr.java
DOMImplementation DOMImplementationJsr.java
DOMImplementationList DOMImplementationListJsr.java
DOMImplementationSource DOMImplementationSourceJsr.java
DOMLocator DOMLocatorJsr.java
DOMStringList DOMStringListJsr.java
Element ElementJsr.java
ElementView ElementViewJsr.java
Entity EntityJsr.java
EntityReference EntityReferenceJsr.java
EventException EventExceptionJsr.java
Event EventJsr.java
EventListener EventListenerJsr.java
EventTarget EventTargetJsr.java
External ExternalJsr.java
Frames FramesJsr.java
History HistoryJsr.java
HTMLAbbrElement HTMLAbbrElementJsr.java
HTMLAcronymElement HTMLAcronymElementJsr.java
HTMLAddressElement HTMLAddressElementJsr.java
HTMLAnchorElement HTMLAnchorElementJsr.java
HTMLAppletElement HTMLAppletElementJsr.java
HTMLAreaElement HTMLAreaElementJsr.java
HTMLArticleElement HTMLArticleElementJsr.java
HTMLAsideElement HTMLAsideElementJsr.java
HTMLAudioElement HTMLAudioElementJsr.java
HTMLBaseElement HTMLBaseElementJsr.java
HTMLBaseFontElement HTMLBaseFontElementJsr.java
HTMLBbElement HTMLBbElementJsr.java
HTMLBDOElement HTMLBDOElementJsr.java
HTMLBElement HTMLBElementJsr.java
HTMLBgsoundElement HTMLBgsoundElementJsr.java
HTMLBigElement HTMLBigElementJsr.java
HTMLBlockquoteElement HTMLBlockquoteElementJsr.java
HTMLBodyElement HTMLBodyElementJsr.java
HTMLBRElement HTMLBRElementJsr.java
HTMLButtonElement HTMLButtonElementJsr.java
HTMLCanvasElement HTMLCanvasElementJsr.java
HTMLCenterElement HTMLCenterElementJsr.java
HTMLCiteElement HTMLCiteElementJsr.java
HTMLCodeElement HTMLCodeElementJsr.java
HTMLColgroupElement HTMLColgroupElementJsr.java
HTMLCollection HTMLCollectionJsr.java
HTMLCommandElement HTMLCommandElementJsr.java
HTMLDataGridElement HTMLDataGridElementJsr.java
HTMLDataListElement HTMLDataListElementJsr.java
HTMLDdElement HTMLDdElementJsr.java
HTMLDelElement HTMLDelElementJsr.java
HTMLDetailsElement HTMLDetailsElementJsr.java
HTMLDfnElement HTMLDfnElementJsr.java
HTMLDialogElement HTMLDialogElementJsr.java
HTMLDirectoryElement HTMLDirectoryElementJsr.java
HTMLDivElement HTMLDivElementJsr.java
HTMLDListElement HTMLDListElementJsr.java
HTMLDocument HTMLDocumentJsr.java
HTMLDOMImplementation HTMLDOMImplementationJsr.java
HTMLDtElement HTMLDtElementJsr.java
HTMLElement HTMLElementJsr.java
HTMLElementStyle HTMLElementStyleJsr.java
HTMLEmbedElement HTMLEmbedElementJsr.java
HTMLEmElement HTMLEmElementJsr.java
HTMLFieldSetElement HTMLFieldSetElementJsr.java
HTMLFigureElement HTMLFigureElementJsr.java
HTMLFontElement HTMLFontElementJsr.java
HTMLFooterElement HTMLFooterElementJsr.java
HTMLFormElement HTMLFormElementJsr.java
HTMLFrameElement HTMLFrameElementJsr.java
HTMLFrameSetElement HTMLFrameSetElementJsr.java
HTMLHeadElement HTMLHeadElementJsr.java
HTMLHeaderElement HTMLHeaderElementJsr.java
HTMLHeadingElement HTMLHeadingElementJsr.java
HTMLHGroupElement HTMLHGroupElementJsr.java
HTMLHRElement HTMLHRElementJsr.java
HTMLHtmlElement HTMLHtmlElementJsr.java
HTMLIElement HTMLIElementJsr.java
HTMLIFrameElement HTMLIFrameElementJsr.java
HTMLImageElement HTMLImageElementJsr.java
HTMLInputElement HTMLInputElementJsr.java
HTMLInsElement HTMLInsElementJsr.java
HTMLIsIndexElement HTMLIsIndexElementJsr.java
HTMLKbdElement HTMLKbdElementJsr.java
HTMLKeyGenElement HTMLKeyGenElementJsr.java
HTMLLabelElement HTMLLabelElementJsr.java
HTMLLegendElement HTMLLegendElementJsr.java
HTMLLIElement HTMLLIElementJsr.java
HTMLLinkElement HTMLLinkElementJsr.java
HTMLMapElement HTMLMapElementJsr.java
HTMLMarkElement HTMLMarkElementJsr.java
HTMLMarqueeElement HTMLMarqueeElementJsr.java
HTMLMenuElement HTMLMenuElementJsr.java
HTMLMetaElement HTMLMetaElementJsr.java
HTMLMeterElement HTMLMeterElementJsr.java
HTMLModElement HTMLModElementJsr.java
HTMLNavElement HTMLNavElementJsr.java
HTMLNoBrElement HTMLNoBrElementJsr.java
HTMLNoFramesElement HTMLNoFramesElementJsr.java
HTMLNoScriptElement HTMLNoScriptElementJsr.java
HTMLObjectElement HTMLObjectElementJsr.java
HTMLOListElement HTMLOListElementJsr.java
HTMLOptGroupElement HTMLOptGroupElementJsr.java
HTMLOptionElement HTMLOptionElementJsr.java
HTMLOptionsCollection HTMLOptionsCollectionJsr.java
HTMLOutputElement HTMLOutputElementJsr.java
HTMLParagraphElement HTMLParagraphElementJsr.java
HTMLParamElement HTMLParamElementJsr.java
HTMLPreElement HTMLPreElementJsr.java
HTMLProgressElement HTMLProgressElementJsr.java
HTMLQuoteElement HTMLQuoteElementJsr.java
HTMLRpElement HTMLRpElementJsr.java
HTMLRtElement HTMLRtElementJsr.java
HTMLRubyElement HTMLRubyElementJsr.java
HTMLSampElement HTMLSampElementJsr.java
HTMLScriptElement HTMLScriptElementJsr.java
HTMLSectionElement HTMLSectionElementJsr.java
HTMLSelectElement HTMLSelectElementJsr.java
HTMLSElement HTMLSElementJsr.java
HTMLSmallElement HTMLSmallElementJsr.java
HTMLSourceElement HTMLSourceElementJsr.java
HTMLSpanElement HTMLSpanElementJsr.java
HTMLStrikeElement HTMLStrikeElementJsr.java
HTMLStrongElement HTMLStrongElementJsr.java
HTMLStyleElement HTMLStyleElementJsr.java
HTMLSubElement HTMLSubElementJsr.java
HTMLSupElement HTMLSupElementJsr.java
HTMLTableCaptionElement HTMLTableCaptionElementJsr.java
HTMLTableCellElement HTMLTableCellElementJsr.java
HTMLTableColElement HTMLTableColElementJsr.java
HTMLTableElement HTMLTableElementJsr.java
HTMLTableRowElement HTMLTableRowElementJsr.java
HTMLTableSectionElement HTMLTableSectionElementJsr.java
HTMLTextAreaElement HTMLTextAreaElementJsr.java
HTMLThElement HTMLThElementJsr.java
HTMLTimeElement HTMLTimeElementJsr.java
HTMLTitleElement HTMLTitleElementJsr.java
HTMLTtElement HTMLTtElementJsr.java
HTMLUElement HTMLUElementJsr.java
HTMLUListElement HTMLUListElementJsr.java
HTMLUnknownElement HTMLUnknownElementJsr.java
HTMLVarElement HTMLVarElementJsr.java
HTMLVideoElement HTMLVideoElementJsr.java
HTMLWbrElement HTMLWbrElementJsr.java
HTMLXmlElement HTMLXmlElementJsr.java
HTMLXmpElement HTMLXmpElementJsr.java
Image ImageJsr.java
KeyboardEvent KeyboardEventJsr.java
Location LocationJsr.java
MimeType MimeTypeJsr.java
MouseEvent MouseEventJsr.java
NamedNodeMap NamedNodeMapJsr.java
NameList NameListJsr.java
Navigator NavigatorJsr.java
Node NodeJsr.java
NodeList NodeListJsr.java
Notation NotationJsr.java
Opera OperaJsr.java
Option OptionJsr.java
PluginArray PluginArrayJsr.java
Plugin PluginJsr.java
ProcessingInstruction ProcessingInstructionJsr.java
Screen ScreenJsr.java
Selection SelectionJsr.java
TextEvent TextEventJsr.java
Text TextJsr.java
TextRange TextRangeJsr.java
TextRectangle TextRectangleJsr.java
TextRectangleList TextRectangleListJsr.java
TypeInfo TypeInfoJsr.java
UIEvent UIEventJsr.java
UserDataHandler UserDataHandlerJsr.java
Window WindowJsr.java
XMLHttpRequest XMLHttpRequestJsr.java

JSR Built-in Convenience Extensions

Events Jsr Generation

Events Using Java Enum name (Js -> Jsr only) - deprecated

This way causes issues with code completion, searching and validation. We do not recommend using this and we need to clean this up.


If the JsHandlerObjectEnum is the first argument then there will be 2 apis generated one with the object enum and one without. The native event object will be passed in by the EventDispatcher automatically. Since the browser passes the native event.


JS code Java API
//> public boolean doIt(org.eclipse.vjet.resource.html.
//event.handler.JsHandlerObjectEnum);
 doIt : function (currentDsfMsg) {
     return true;
 }
 public JsFunc<Boolean> doIt(){
 
}
 
 
public JsFunc<Boolean> doIt(org.eclipse.vjet.resource.html.
event.handler.JsHandlerObjectEnum currentDsfMsg){
 
}
Java authored Js code
// not supported

Events Using Native Event (not recommended due to portability issues)

In this case the Event object in Js is using the native event object. There are 4 apis generated.

  1. One with the EventJsr to allow for passing of the EventJsr object from other method that returns the event object.
  2. One with the EventJsr IValueBinding.
  3. One for backward compatibility with deprecated mode using JsHandlerObjectEnum
  4. One without any arguments to allow for the event object to be passed into by the event dispatcher automatically. No user defined code required to pass the event object.


JS code Java API
//> public boolean doIt(Event);
doIt2 : function (evt) {
    evt.cancelBubble = true;
    return false;
}
public JsFunc<Boolean> doIt2(EventJsr evt)
 
public JsFunc<Boolean> doIt2(IValueBinding<? extends EventJsr> evt)
 
public JsFunc<Boolean> doIt2(org.eclipse.vjet.resource.html
.event.handler.JsHandlerObjectEnum evt)
 
public JsFunc<Boolean> doIt2(){
    return call(Boolean.class, "doIt2").with(org.eclipse.vjet.resource.html.
                          event.handler.JsHandlerObjectEnum.nativeEvent);
}


Java authored Js code
public boolean doIt2(Event evt){
    evt.setCancelBubble(true);
    return false;
}

Note: Event.setCancelBubble needs to be added to make this work

Events using vjo.dsf.Event (preferred solution)

This is the preferred solution because the native event api is not standard across browsers where this object deals with these differences and you get consistent code completion, validation, and searching in VJET IDE.


There are 4 apis generated for this case.


  1. One with the EventJsr to allow for passing of the EventJsr object from other method that returns the event object.
  2. One with the EventJsr IValueBinding to allow EventJsr to be passed from one reference to another.
  3. One for backward compatibility with deprecated mode using JsHandlerObjectEnum
  4. One without any arguments to allow for the event object to be passed into by the event dispatcher automatically. No user defined code required to pass the event object.


JS code Java API
//> needs(vjo.dsf.Event)
//> public boolean doIt(Event);
doIt2 : function (evt) {
    return true;
}
//note EventJsr is referring to 
//vjo.dsf.EventJsr not the native EventJsr. 
public JsFunc<Boolean> doIt2(EventJsr evt)
 
public JsFunc<Boolean> doIt2(IValueBinding<? 
extends EventJsr> evt)
 
public JsFunc<Boolean> doIt2(org.eclipse.vjet.resource.html.
event.handler.JsHandlerObjectEnum evt)
Java authored Js code
// Event in this case is referring 
//to the native js proxy vjo.dsf.Event
public boolean doIt2(Event evt){
    evt.setCancelBubble(true); 
    return false;
 
}

Ajax Service Engine Message Generation

Using the JsHandlerObjEnum - Deprecated

Similar to the Event using the same type we do not want to support this going forward. This example has multiple issues:

  1. Doesn't declare needs correctly which causes an implicit dependency on vjo.dsf.Message
  2. It is very verbose and difficult to read.
  3. Code completion, searching, validation doesn't work correctly. Causing workarounds in VJET JS.
JS code Java API
//> public org.eclipse.vjet.resource.html.event.handler.JsHandlerObjectEnum
doIt(org.eclipse.vjet.resource.html.event.handler.JsHandlerObjectEnum);
 
doIt : function (message) {
    return message;
}
public JsFunc<? extends org.eclipse.vjet.resource.
html.event.handler.JsHandlerObjectEnum> 
doIt(org.eclipse.vjet.resource.html.event.
handler.JsHandlerObjectEnum message)
Java authored Js code
// not supported

Using vjo.dsf.Message in API – preferred solution

JS code Java API
//>needs(vjo.dsf.Message)
//> public Message doIt(Message)
doIt : function (message) {
    return message;
}
public JsFunc<? extends MessageJsr> doIt(MessageJsr message)
 
public JsFunc<? extends MessageJsr> doIt(IValueBinding<? extends MessageJsr> message)
 
public JsFunc<? extends MessageJsr> doIt(){
    return call(MessageJsr.class, "doIt").with
           (org.eclipse.vjet.resource.html.event.handler.JsHandlerObjectEnum.message);
}
Java authored Js code
public void doIt(Message message){}

TODO – Currently there is a problem with 3rd API not being generated.

TODO – Add more tests here

Note – On the server side there is org.eclipse.vjet.service.Message but this class should not be passed into Jsr.

Types supporting Java type and Java Jsr Type API

TODO – fix this on Zam currently broken after first iteration of Jsr fixes

ArrayList and HashMap are currently supported as types that support a native Java api as well as the ArrayListJsr and HashMapJsr respectively.

JS code Java API
//>public constructs(HashMap)
constructs : function(a){}
public FooJsr(HashMap a)
 
public FooJsr(HashMapJsr a)
 
public FooJsr(IValueBinding<HashMap> a)
 
public FooJsr(IValueBinding<HashMapJsr> a)
Java authored Js code
public FooJ2J(HashMap a){}

In order to support this HashMap api must have a converter registered or the default converter will take the HashMap and convert it to a JSON object.

A user can also define a Java type that supports this using the

Using JSR

JSRs are Independent of the Source Language

Recall that there are no differences in JSR references whether they are generated from JavaScript or Java code.


The following example creates two Buttons, and adds a Click event to each button. One button associates the Click event to a JSR generated from Java (JavaCommunicatorJsr); the other button associates the Click event with a JSR generated from JavaScript (CommunicatorJsr).

public class CommExample {
 
    public DDiv div() {
        // CommunicatorJsr source of truth is .js (JavaScript)
        DButton b1 = getButton("Warn me").add(EventType.''CLICK'', CommunicatorJsr.''warn''("Will Robinson")) ;
        // JavaCommunicatorJsr source of truth is .java (Java)
        DButton b2 = getButton("Warn me again").add(EventType.''CLICK'', JavaCommunicatorJsr.''warn''("The Wolf")) ; 
        DDiv div = new DDiv().add(b1).addBr().add(b2) ;
        return div ;
    }
 
    private DButton getButton(String label) {
       return new DButton(label).setHtmlType(DButton.''TYPE_BUTTON'') ;
    }
}

APPENDIX: VJET Sections and JSR

VJET Section JSR Notes
.needs import
.values Creates a JsProp member for each element
.inherits Extends, import
.satisfies Implements,import
.mixin mtype members are incorporated with the type that includes the mixin
.props static Members defined in the props section become static members
.protos Instance members only public members Members defined in the protos section become instance members


.constructs Creates JSR constructor(s) if the constructor is overloaded; otherwise a no-argument, default constructor is created.
.options Not included
.inits Not included
.globals Not included
.expects Not included
.defs Nested classes Nested classes representing functions and object literals

Review #1 5/20/10

Additions Requested

  • MType isMixin api to be added
  • Undefined type / Jsr do we want to add this?
  • Utility to convert org.eclipse.vjet.service.Message to MessageJsr
  • Change spec so that all Jsrs that implement VJO extend vjo.ObjectJsr
  • Do we want to add function references to Spec for each static method? Preferred we have some Jsr Utilities for this.
  • After all definitions show usage example.
  • Mention something about property setting last one in wins.
  • Look at having a way to hint that certain types need convenience APIs without changing code generator.
  • Add example of using the annotation @Package and getting a Jsr with a resource spec
  • Add Note about Property gets reference not actual value.
  • Add Hand coding show the call without the method name repeated but state there is a performance enhancement by using overloaded method.
  • Flow diagram that shows Jsr usage during page construction and how the code is invoked on a browser.

Changes Requested

  • 13.1 – Number usage in JS should be double in Jsr – added to spec – code gen change needed
  • Make VJET validation requirement for Jsr generation currently they are separate today.
  • 6.4.2 missing required argument
  • Inner types – show differences between static, instance, interface, .. Usage of type references.
  • EType mention that EType must be final
  • Etype from reference perspective are static but internally the values are static instances. A small talk concept.
  • OTYPE - Show usage of the JsFuncRef constructors show simple and complex examples.
  • OTYPE show object literal first before function references. Since I am using object literal in function reference.
  • 10.1.2 examples are wrong
  • 10.2.1 Need to determine how to do a type reference in Java to Jsr or what is should be?
  • Section 12 more examples of converters
  • 13.1 – java.lang.Number should be vjo.java.lang.Number not js Number (do we want different mapping for Java to Jsr types.
  • 13.2 – remove the extends Number comment
  • Show function and type references before types
  • Function references… Text is covering Function instance
  • Remove section 11 already covered in resource spec info
  • Remove the usage section and integrate into after each definition. Write test cases at the same time.
  • Move the convenience extensions into another document. It is not part of the core Jsr.

Verification Required

  • Does VJET validator error on foo(Foo? A, String ) – need to verify
  • Hand coding examples - Reflection different between Java Sun vs IBM?? Need to confirm this.
  • Is there a resource pattern document to refer to?

Known Issues

  • Native types are names only and do not have their api's exposed.
  • Js developers who declare Boolean are not expecting a Boolean object in most cases but expecting the boolean literal or boolean.
  • Serialization feature was removed due to no documentation / support/ tests. More information is needed.
  • Globals can not be referenced in Jsr
  • Java 2 Jsr – type references do not generate correctly / same as Vjo to Jsr right now.
  • JsObj is currently base for all native objects and vjo objects but really user defined objects using VJO should extend from vjo.ObjectJsr not JsObj.
  • VJET validation fixes were being added that used overloading for event and message.
  • When doing right click js to java generation I noticed that Event apis are missing zero argument signature. 14.5.1
  • VjoObjectConverter is not added by default due to issues with JS code using HashMap, ArrayList but not using the VJO JDK classes. This issue needs to be addressed. There are currently validation errors on this code.
  • When auditing tests I found that Java to Js was not correctly using interfaces but using concrete classes which do not translate correctly to JSR or VJO. Biggest offender was using DapCtx to get the window or document rather than using VJ type.
  • Native types should not have active or inactive needs in some cases I found that VJO code and Jsr was pulling

Type Omissions

Jsr should not include imports for anything inside java.lang

Inactive Needs

Should Object be in inactive needs?

.needs('Object',) active needs for Object?

.needs('Object','org.eclipse.vjet.jsnative.global.Object') – strange


  • Also show an example of adding vjo.ctype to get a vjo type. Which one is preferred and do they both work in runtime?
  • Issue with nested object literals in otypes Jsr do not generate correctly. Added note into language spec this is not supported.
  • OType on RA and previous did not correctly serialize object literals that used any of the java types such as Date. On ZAM fixed this to use the Js converters to prevent a JSON deserialize api call
  • JFunction had utility method def which I moved to JFunctionX since we want JFunction to map to JFunction. DOM JSR apis were using Native proxies not Jsrs this was fixed on ZAM. Example:

From

HtmlDocument is not a Jsr

public JsFunc<String> getReferrer(HtmlDocument doc){
    return call(String.class, "getReferrer").with(doc);
}
 
public JsFunc<String> getReferrer(IValueBinding<? extends HtmlDocument> doc){
    return call(String.class, "getReferrer").with(doc);
}

HTMLDocumentJsr can be used here:

public JsFunc<String> getReferrer(HTMLDocumentJsr doc){
    return call(String.class, "getReferrer").with(doc);
}
 
public JsFunc<String> getReferrer(IValueBinding<? extends HTMLDocumentJsr> doc){
    return call(String.class, "getReferrer").with(doc);
}